@hienlh/ppm 0.17.57 → 0.18.1

package/src/services/fs-browse.service.ts

@@ -1,20 +1,30 @@
-import {
-  existsSync,
-  readdirSync,
-  statSync,
-  lstatSync,
-  readFileSync,
-  writeFileSync,
-} from "node:fs";
-import { resolve, basename, dirname, normalize } from "node:path";
+import { lstat, readdir, stat } from "node:fs/promises";
+import { basename, dirname, resolve, sep } from "node:path";
 import { homedir } from "node:os";
+import {
+  assertAllowed,
+  isAllowedPath,
+  resolvePath,
+} from "./fs-path-guard.service.ts";
+import { isHiddenName } from "./fs-ops/fs-hidden-names.ts";
+import { kindOfStats, type EntryKind } from "./fs-ops/fs-ops-stat.service.ts";
+
+// Re-exported so existing importers keep a single filesystem entry point.
+export { isAllowedPath, resolvePath };
+export {
+  readSystemFileSync,
+  writeSystemFile,
+} from "./fs-ops/fs-ops-read-write.service.ts";
+export { list } from "./fs-ops/fs-list-files.service.ts";
 
 // ── Types ──────────────────────────────────────────────────────────
 
 export interface BrowseEntry {
   name: string;
   path: string;
+  /** Coarse type kept for existing consumers; `kind` carries the detail. */
   type: "file" | "directory";
+  kind: EntryKind;
   size?: number;
   modified: string;
 }
@@ -24,6 +34,10 @@ export interface BrowseResult {
   current: string;
   parent: string | null;
   breadcrumbs: { name: string; path: string }[];
+  /** Platform path separator, so the client can render native paths. */
+  sep: string;
+  /** True when the directory held more entries than the listing cap. */
+  truncated?: boolean;
 }
 
 export interface BrowseOptions {
@@ -32,86 +46,84 @@ export interface BrowseOptions {
 
 // ── Constants ──────────────────────────────────────────────────────
 
-const SKIP_NAMES = new Set([".git", "node_modules", ".DS_Store"]);
-const LIST_MAX_FILES = 200;
-const LIST_MAX_DEPTH = 4;
-const READ_MAX_SIZE = 5 * 1024 * 1024; // 5 MB
-
-/** Roots allowed for system-level browsing (outside project scope). */
-const ALLOWED_ROOTS_POSIX = ["/Volumes", "/mnt", "/media", "/tmp", "/home"];
-
-// ── Shared helpers ─────────────────────────────────────────────────
-
-/** Resolve a path, expanding leading `~` to home directory. */
-export function resolvePath(input: string): string {
-  const home = homedir();
-  return input.startsWith("~")
-    ? resolve(home, input.slice(2))
-    : resolve(input);
-}
-
-/** Check if an absolute path is within the allowed whitelist. */
-export function isAllowedPath(resolved: string): boolean {
-  const home = homedir();
-  if (resolved === home || resolved.startsWith(home + "/")) return true;
-
-  // SDK background-command output lives under the OS temp dir, outside the
-  // home/posix-root whitelist. Allow reading those specific files so the chat
-  // output panel works. The claude dir name varies by platform/CLI version:
-  // "claude" (Windows Temp, older macOS /var/folders/.../T) or "claude-<uid>"
-  // (macOS /tmp/claude-501, reported by lsof as /private/tmp/...). Matched by
-  // structure (claude*/…/tasks/*.output) to be symlink-agnostic.
-  if (/[\\/]claude[^\\/]*[\\/].+[\\/]tasks[\\/][^\\/]+\.output$/.test(resolved)) return true;
-
-  if (process.platform === "win32") {
-    return /^[A-Z]:\\/i.test(resolved);
+/** Listing cap — beyond this the UI is unusable and the scan gets expensive. */
+const BROWSE_MAX_ENTRIES = 5_000;
+/** Parallel stat calls; enough to hide latency, few enough to stay polite. */
+const STAT_CONCURRENCY = 16;
+/**
+ * A dead SMB share, sleeping USB disk or OneDrive placeholder can make a
+ * single stat hang for minutes. The browse answer must still arrive, so a
+ * slow entry is reported with an unknown kind instead of holding the request.
+ */
+const STAT_TIMEOUT_MS = 1_500;
+
+// ── Browse ─────────────────────────────────────────────────────────
+
+async function statEntry(fullPath: string, name: string): Promise<BrowseEntry | null> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<"timeout">((r) => {
+    timer = setTimeout(() => r("timeout"), STAT_TIMEOUT_MS);
+  });
+  const stats = await Promise.race([lstat(fullPath).catch(() => "error" as const), timeout]);
+  // Clearing matters: a listing of thousands of entries would otherwise hold
+  // thousands of live timers until they each fire.
+  clearTimeout(timer);
+
+  if (stats === "error") return null; // unreadable — skipped, never fatal
+  if (stats === "timeout") {
+    return {
+      name,
+      path: fullPath,
+      type: "file",
+      kind: "unknown",
+      modified: new Date(0).toISOString(),
+    };
   }
-
-  return ALLOWED_ROOTS_POSIX.some(
-    (r) => resolved === r || resolved.startsWith(r + "/"),
-  );
+  const kind = kindOfStats(stats);
+  return {
+    name,
+    path: fullPath,
+    type: kind === "directory" ? "directory" : "file",
+    kind,
+    size: kind === "file" ? stats.size : undefined,
+    modified: stats.mtime.toISOString(),
+  };
 }
 
-// ── Browse (new) ───────────────────────────────────────────────────
+/** Run `worker` over `items` with a fixed number of workers in flight. */
+async function mapBounded<T, R>(items: T[], limit: number, worker: (item: T) => Promise<R>): Promise<R[]> {
+  const results: R[] = new Array(items.length);
+  let next = 0;
+  const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await worker(items[index]!);
+    }
+  });
+  await Promise.all(runners);
+  return results;
+}
 
-/** List entries of a single directory (1-level, structured). */
-export function browse(
-  dirPath?: string,
-  options?: BrowseOptions,
-): BrowseResult {
+/** List entries of a single directory (1 level, no symlink descent). */
+export async function browse(dirPath?: string, options?: BrowseOptions): Promise<BrowseResult> {
   const resolved = dirPath ? resolvePath(dirPath) : homedir();
+  assertAllowed(resolved);
 
-  if (!isAllowedPath(resolved)) {
-    throw Object.assign(new Error("Access denied"), { status: 403 });
-  }
-  if (!existsSync(resolved)) {
-    throw Object.assign(new Error("Directory not found"), { status: 404 });
-  }
-  if (!statSync(resolved).isDirectory()) {
-    throw Object.assign(new Error("Not a directory"), { status: 400 });
+  const st = await stat(resolved);
+  if (!st.isDirectory()) {
+    throw Object.assign(new Error("Not a directory"), { status: 400, code: "ENOTDIR" });
   }
 
-  const raw = readdirSync(resolved, { withFileTypes: true });
-  const entries: BrowseEntry[] = [];
-
-  for (const entry of raw) {
-    if (!options?.showHidden && entry.name.startsWith(".")) continue;
-
-    const fullPath = resolve(resolved, entry.name);
-    try {
-      if (lstatSync(fullPath).isSymbolicLink()) continue;
-      const st = statSync(fullPath);
-      entries.push({
-        name: entry.name,
-        path: fullPath,
-        type: st.isDirectory() ? "directory" : "file",
-        size: st.isFile() ? st.size : undefined,
-        modified: st.mtime.toISOString(),
-      });
-    } catch {
-      /* permission denied — skip */
-    }
-  }
+  const names = (await readdir(resolved)).filter(
+    (name) => options?.showHidden || !isHiddenName(name),
+  );
+  const truncated = names.length > BROWSE_MAX_ENTRIES;
+  const visible = truncated ? names.slice(0, BROWSE_MAX_ENTRIES) : names;
+
+  const statted = await mapBounded(visible, STAT_CONCURRENCY, (name) =>
+    statEntry(resolve(resolved, name), name),
+  );
+  const entries = statted.filter((e): e is BrowseEntry => e !== null);
 
   entries.sort((a, b) => {
     if (a.type !== b.type) return a.type === "directory" ? -1 : 1;
@@ -124,12 +136,18 @@ export function browse(
     current: resolved,
     parent: parentDir !== resolved ? parentDir : null,
     breadcrumbs: buildBreadcrumbs(resolved),
+    sep,
+    ...(truncated ? { truncated: true } : {}),
   };
 }
 
-function buildBreadcrumbs(
-  absPath: string,
-): { name: string; path: string }[] {
+/** Label of a filesystem root: `C:` on Windows, `/` on POSIX. */
+function rootLabel(rootPath: string): string {
+  const trimmed = rootPath.replace(/[\\/]+$/, "");
+  return trimmed || "/";
+}
+
+function buildBreadcrumbs(absPath: string): { name: string; path: string }[] {
   const home = homedir();
   const parts: { name: string; path: string }[] = [];
   let current = absPath;
@@ -143,84 +161,9 @@ function buildBreadcrumbs(
     current = dirname(current);
   }
 
-  // Reached filesystem root
+  // Reached a filesystem root (drive root on Windows, `/` on POSIX)
   if (!parts.length || parts[0]!.path !== current) {
-    parts.unshift({ name: basename(current) || "/", path: current });
+    parts.unshift({ name: rootLabel(current), path: current });
   }
   return parts;
 }
-
-// ── List (moved from index.ts inline) ──────────────────────────────
-
-/** Breadth-first file listing for command palette.
- *  Lists all files at each level before descending into subdirectories,
- *  so root-level files (e.g. ~/.npmrc) are always found before the limit. */
-export function list(dir: string): string[] {
-  const resolved = resolvePath(dir);
-  if (!isAllowedPath(resolved)) {
-    throw Object.assign(new Error("Access denied"), { status: 403 });
-  }
-
-  const files: string[] = [];
-  const queue: { path: string; depth: number }[] = [{ path: resolved, depth: 0 }];
-
-  while (queue.length > 0 && files.length < LIST_MAX_FILES) {
-    const { path: dirPath, depth } = queue.shift()!;
-    if (depth > LIST_MAX_DEPTH) continue;
-    let entries: import("node:fs").Dirent[];
-    try {
-      entries = readdirSync(dirPath, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-    for (const entry of entries) {
-      if (SKIP_NAMES.has(entry.name)) continue;
-      const full = resolve(dirPath, entry.name);
-      if (entry.isFile()) {
-        files.push(full);
-        if (files.length >= LIST_MAX_FILES) return files;
-      } else if (entry.isDirectory()) {
-        queue.push({ path: full, depth: depth + 1 });
-      }
-    }
-  }
-
-  return files;
-}
-
-// ── Read (moved from index.ts inline) ──────────────────────────────
-
-/** Read a file outside project scope. */
-export function readSystemFile(
-  filePath: string,
-): { content: string; path: string } {
-  const resolved = resolvePath(filePath);
-  if (!isAllowedPath(resolved)) {
-    throw Object.assign(new Error("Access denied"), { status: 403 });
-  }
-  if (!existsSync(resolved)) {
-    throw Object.assign(new Error("File not found"), { status: 404 });
-  }
-
-  const st = statSync(resolved);
-  if (!st.isFile()) {
-    throw Object.assign(new Error("Not a file"), { status: 400 });
-  }
-  if (st.size > READ_MAX_SIZE) {
-    throw Object.assign(new Error("File too large (>5MB)"), { status: 400 });
-  }
-
-  const content = readFileSync(resolved, "utf-8");
-  return { content, path: resolved };
-}
-
-// ── Write (moved from index.ts inline) ─────────────────────────────
-
-/** Write a file outside project scope. */
-export function writeSystemFile(filePath: string, content: string): void {
-  const resolved = resolvePath(filePath);
-  if (!isAllowedPath(resolved)) {
-    throw Object.assign(new Error("Access denied"), { status: 403 });
-  }
-  writeFileSync(resolved, content, "utf-8");
-}

package/src/services/fs-ops/fs-content-disposition.ts

@@ -0,0 +1,17 @@
+/**
+ * Percent-encode a filename for the RFC 5987 `filename*` form.
+ * `encodeURIComponent` leaves `'`, `(`, `)` and `*`, which are not attr-chars
+ * there, so a name containing them would produce a header value a strict
+ * parser rejects.
+ */
+export function encodeRfc5987(name: string): string {
+  return encodeURIComponent(name).replace(
+    /['()*]/g,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}
+
+/** `Content-Disposition` for a download, with a UTF-8 safe filename. */
+export function attachmentDisposition(filename: string): string {
+  return `attachment; filename*=UTF-8''${encodeRfc5987(filename)}`;
+}

package/src/services/fs-ops/fs-core-ops.ts

@@ -0,0 +1,149 @@
+import { cpSync, renameSync, rmSync, lstatSync } from "node:fs";
+import { cp, lstat, rename, rm } from "node:fs/promises";
+import { resolve, sep } from "node:path";
+
+/**
+ * Shared copy/move/rename/remove core used by both the project-scoped file
+ * service and the out-of-project explorer routes. The interesting rules —
+ * collision detection, self-nesting refusal, case-only rename, cross-device
+ * fallback — live here once so the two doors cannot drift apart. Everything
+ * inspects the link itself (`lstat`), never the symlink target, so operating
+ * on a link never touches the file it points at.
+ */
+
+function fsError(message: string, code: string, status: number): Error {
+  return Object.assign(new Error(message), { code, status });
+}
+
+export function eexist(path: string): Error {
+  return fsError(`Already exists: ${path}`, "EEXIST", 409);
+}
+
+/** Path-level equality on a case-insensitive filesystem. */
+function sameNameIgnoringCase(a: string, b: string): boolean {
+  return a.toLowerCase() === b.toLowerCase();
+}
+
+/**
+ * A rename that only changes letter case (`Foo` → `foo`) hits a false
+ * collision on Windows/macOS, where the destination "exists" because it is
+ * the source. Allowed when the platform is case-insensitive or the two paths
+ * resolve to the same inode.
+ */
+export function isCaseOnlyRename(src: string, dst: string): boolean {
+  const a = resolve(src);
+  const b = resolve(dst);
+  if (a === b || !sameNameIgnoringCase(a, b)) return false;
+  if (process.platform === "win32" || process.platform === "darwin") return true;
+  try {
+    return lstatSync(a).ino === lstatSync(b).ino;
+  } catch {
+    return false;
+  }
+}
+
+/** Copying or moving a directory into its own subtree would recurse forever. */
+export function assertNotNested(src: string, dst: string): void {
+  const a = resolve(src);
+  const b = resolve(dst);
+  if (b === a || b.startsWith(a.endsWith(sep) ? a : a + sep)) {
+    throw fsError(`Cannot place ${a} inside itself`, "EINVAL", 400);
+  }
+}
+
+async function existsAsLink(path: string): Promise<boolean> {
+  try {
+    await lstat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function existsAsLinkSync(path: string): boolean {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reject an occupied destination before any bytes move. `allowCaseOnly` is
+ * set for rename/move, where the "existing" destination is the source itself
+ * under different casing; a copy in that situation would target one file with
+ * itself and must still fail.
+ */
+async function assertFreeDestination(src: string, dst: string, allowCaseOnly: boolean): Promise<void> {
+  if (!(await existsAsLink(dst))) return;
+  if (allowCaseOnly && isCaseOnlyRename(src, dst)) return;
+  throw eexist(dst);
+}
+
+// ── Async ops (explorer routes; never block the event loop) ─────────
+
+export async function copyEntry(src: string, dst: string): Promise<void> {
+  assertNotNested(src, dst);
+  await assertFreeDestination(src, dst, false);
+  await cp(src, dst, { recursive: true, force: false, errorOnExist: true, verbatimSymlinks: true });
+}
+
+export async function renameEntry(src: string, dst: string): Promise<void> {
+  assertNotNested(src, dst);
+  await assertFreeDestination(src, dst, true);
+  await rename(src, dst);
+}
+
+export async function removeEntry(path: string): Promise<void> {
+  await rm(path, { recursive: true, force: false });
+}
+
+/**
+ * Move with a cross-device fallback: `rename` fails with EXDEV between two
+ * volumes (C: → D:, /home → /mnt), where a copy followed by a delete is the
+ * only way to keep the operation looking atomic to the caller.
+ */
+export async function moveEntry(
+  src: string,
+  dst: string,
+  /** Injectable so the cross-device branch is testable on a single volume. */
+  renameImpl: (from: string, to: string) => Promise<void> = rename,
+): Promise<{ crossDevice: boolean; sourceRemoved: boolean }> {
+  assertNotNested(src, dst);
+  await assertFreeDestination(src, dst, true);
+  try {
+    await renameImpl(src, dst);
+    return { crossDevice: false, sourceRemoved: true };
+  } catch (e) {
+    if ((e as { code?: string }).code !== "EXDEV") throw e;
+    await cp(src, dst, { recursive: true, force: false, errorOnExist: true, verbatimSymlinks: true });
+    // The copy succeeded, so the data is safe either way. If the source cannot
+    // be removed (locked file, read-only mount) the caller must learn that two
+    // copies now exist rather than be told the move completed.
+    try {
+      await rm(src, { recursive: true, force: false });
+    } catch {
+      return { crossDevice: true, sourceRemoved: false };
+    }
+    return { crossDevice: true, sourceRemoved: true };
+  }
+}
+
+// ── Sync ops (project-scoped file service keeps its sync contract) ──
+
+export function copyEntrySync(src: string, dst: string): void {
+  assertNotNested(src, dst);
+  if (existsAsLinkSync(dst)) throw eexist(dst);
+  cpSync(src, dst, { recursive: true, force: false, errorOnExist: true, verbatimSymlinks: true });
+}
+
+export function renameEntrySync(src: string, dst: string): void {
+  assertNotNested(src, dst);
+  if (existsAsLinkSync(dst) && !isCaseOnlyRename(src, dst)) throw eexist(dst);
+  renameSync(src, dst);
+}
+
+export function removeEntrySync(path: string): void {
+  rmSync(path, { recursive: true, force: false });
+}

package/src/services/fs-ops/fs-error-response.ts

@@ -0,0 +1,24 @@
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import { errorStatus } from "../../server/helpers/error-status.ts";
+import { mapFsError } from "../fs-path-guard.service.ts";
+import { err } from "../../types/api.ts";
+
+/**
+ * Single translation from a thrown filesystem error to the JSON body the
+ * explorer expects. `code` drives the client prompts (collision → rename,
+ * NO_TRASH → offer permanent delete), `hint` explains a refusal a user can
+ * actually fix (macOS Full Disk Access).
+ */
+export function fsErrorBody(e: unknown): {
+  body: ReturnType<typeof err> & { code: string; hint?: string };
+  status: ContentfulStatusCode;
+} {
+  const info = mapFsError(e);
+  // Domain errors from the project-scoped services carry no `code`; fall back
+  // to the shared class-based mapping so both doors answer alike.
+  const status = (info.status === 500 ? errorStatus(e) : info.status) as ContentfulStatusCode;
+  return {
+    body: { ...err(info.message), code: info.code, hint: info.hint },
+    status,
+  };
+}

package/src/services/fs-ops/fs-git-init.service.ts

@@ -0,0 +1,23 @@
+/**
+ * `git init` for a freshly created project folder. It gets a kill timer like
+ * every other spawn here: git can hang on a broken hooks template or a wedged
+ * filesystem, and the directory already exists by then, so a stuck init must
+ * not hold the HTTP request open.
+ */
+const GIT_INIT_TIMEOUT_MS = 5_000;
+
+export async function runGitInit(path: string): Promise<void> {
+  const proc = Bun.spawn(["git", "init", path], { stdout: "ignore", stderr: "ignore" });
+  const timer = setTimeout(() => {
+    try {
+      proc.kill();
+    } catch {
+      /* already exited */
+    }
+  }, GIT_INIT_TIMEOUT_MS);
+  try {
+    await proc.exited;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/services/fs-ops/fs-hidden-names.ts

@@ -0,0 +1,17 @@
+/**
+ * Hidden-entry rules shared by browse and stat. POSIX hides dot-names; on
+ * Windows the dot convention barely exists, so the shell-managed system
+ * entries a user never wants to see are named explicitly.
+ */
+const WINDOWS_HIDDEN_NAMES = new Set([
+  "desktop.ini",
+  "$recycle.bin",
+  "system volume information",
+  "thumbs.db",
+]);
+
+export function isHiddenName(name: string): boolean {
+  if (name.startsWith(".")) return true;
+  if (process.platform !== "win32") return false;
+  return WINDOWS_HIDDEN_NAMES.has(name.toLowerCase());
+}

package/src/services/fs-ops/fs-list-files.service.ts

@@ -0,0 +1,68 @@
+import type { Dirent } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { resolve } from "node:path";
+import { assertAllowed, resolvePath } from "../fs-path-guard.service.ts";
+
+/** Noise that would swamp a palette listing. */
+const SKIP_NAMES = new Set([".git", "node_modules", ".DS_Store"]);
+const LIST_MAX_FILES = 200;
+const LIST_MAX_DEPTH = 4;
+/** Directories read in parallel per level — same bound the browse listing uses. */
+const READ_CONCURRENCY = 16;
+/**
+ * A dead network mount or sleeping disk can make one `readdir` hang for
+ * minutes. The palette would rather return a short list than stall every
+ * websocket on the server, so a slow directory is simply dropped.
+ */
+const READ_TIMEOUT_MS = 1_500;
+
+async function readDirSafe(dirPath: string): Promise<Dirent[]> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<Dirent[]>((r) => {
+    timer = setTimeout(() => r([]), READ_TIMEOUT_MS);
+  });
+  try {
+    return await Promise.race([
+      readdir(dirPath, { withFileTypes: true }).catch(() => [] as Dirent[]),
+      timeout,
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Breadth-first file listing for the command palette. Lists all files at each
+ * level before descending, so root-level files (e.g. ~/.npmrc) are always
+ * found before the limit is reached.
+ */
+export async function list(dir: string): Promise<string[]> {
+  const resolved = resolvePath(dir);
+  assertAllowed(resolved);
+
+  const files: string[] = [];
+  let level = [resolved];
+
+  for (let depth = 0; depth <= LIST_MAX_DEPTH && level.length && files.length < LIST_MAX_FILES; depth++) {
+    const next: string[] = [];
+    for (let i = 0; i < level.length; i += READ_CONCURRENCY) {
+      const batch = await Promise.all(level.slice(i, i + READ_CONCURRENCY).map(readDirSafe));
+      batch.forEach((entries, index) => {
+        const dirPath = level[i + index]!;
+        for (const entry of entries) {
+          if (SKIP_NAMES.has(entry.name)) continue;
+          const full = resolve(dirPath, entry.name);
+          if (entry.isFile()) {
+            if (files.length < LIST_MAX_FILES) files.push(full);
+          } else if (entry.isDirectory()) {
+            next.push(full);
+          }
+        }
+      });
+      if (files.length >= LIST_MAX_FILES) return files.slice(0, LIST_MAX_FILES);
+    }
+    level = next;
+  }
+
+  return files;
+}