feat(files): copy & duplicate, bulk actions, disk-backed uploads, and an accessible file tree (#1409)

* perf(files): spool uploads to disk instead of buffering in memory

Switch the stack file-explorer upload from multer memoryStorage to
diskStorage and stream the spooled temp file through the file-root
gateway, so an upload is never held fully in RAM. Authorization and
root resolution now run before multer spools, so an unauthorized or
read-only-root request is rejected without writing a temp file, and the
spool is removed on every exit path. The named-volume helper write
verifies the written byte count, since cat cannot report a short write.

* feat(files): copy and duplicate files in the explorer

Add a copy capability to the stack file explorer: a same-folder
Duplicate (auto-suffixed name) and a "Copy to..." destination picker,
on both filesystem and named-volume roots. Copying is within-root,
symlink-leaf-safe, blocks a directory copy into its own subtree, and
refuses to create a protected name (compose/.env) at the stack root
while still allowing a protected file to be duplicated under a new name.

* feat(files): make the file tree keyboard accessible

Bring the stack file explorer tree to the WCAG tree pattern: rows are
treeitems carrying aria-level, aria-selected, and aria-expanded, with a
single roving tabindex and full keyboard navigation (arrow keys,
Home/End, Enter/Space) over a flattened visible-node list that stays in
lockstep with the rendered rows. A polite live region announces the
selected file. No visual change to the tree.

* feat(files): bulk select, delete, move, and download files

Add multi-select to the stack file explorer (checkboxes plus Shift and
Ctrl/Cmd click over the visible order) driving three bulk actions:
delete, move, and download as a streamed .tar.gz. All run within the
active root on both filesystem and named-volume backends, report
per-item results so partial failures surface (with the failed items
kept selected for retry), normalize ancestor/descendant selections
server-side, and cap the archive entry and byte counts before any
bytes are streamed. Protected compose/.env files are excluded from
bulk delete and move but may still be downloaded.

* docs(files): document copy, bulk actions, and keyboard navigation

Add the copy/duplicate and multi-select bulk delete/move/download
sections to the Files & Volumes page, a keyboard-navigation note for the
tree, an updated context-menu reference, and bulk troubleshooting entries.

* fix(files): inline path-injection barriers at the new file-op sinks

CodeQL js/path-injection does not credit the wrapped isPathWithinBase
containment check, so the new copy/bulk/disk-upload flows tripped the
gate. Inline the canonical path.resolve + startsWith barrier at the
realpath sink in resolveSafePathWithin (covers every user-relPath flow)
and confirm the multer spool path resolves within UPLOAD_TMP_DIR before
unlinking it or streaming it onward. Behavior is unchanged; the paths
were already validated.

* fix(files): guard the ancestor-walk realpath sink too

The first barrier covered realpath(target), but the ENOENT ancestor
walk re-derives the path via path.dirname, which static analysis treats
as a fresh tainted value. Add the same inline containment barrier before
that realpath and resolve the root case via the untainted base, so the
only tainted realpath input is one the startsWith check has cleared.
Behavior is unchanged.

* fix(files): resolve the root case off the taint path in the ancestor walk

The compound guard on existing (the same variable as the startsWith
subject) was not credited as a sanitizer. Handle the root case before
the barrier by resolving the untainted base directly, leaving a plain
canonical startsWith guard on the strictly-within ancestor. Behavior is
unchanged.

* fix(files): harden helper-backend bulk download and uploads

Address three issues found in the named-volume (helper) backend:

- Bulk download could send 200 headers before discovering a file the
  helper download path refuses, tearing the archive mid-stream. The
  prewalk now rejects symlinks, non-regular ("other") entries, and
  files over the per-file download cap before any header (400/413).
  FileEntry gains an 'other' type so non-regular entries stay distinct
  from regular files as they pass through the gateway.
- The helper directory listing was fully buffered before the archive
  entry cap could fire. listDir now accepts a limit; the list script
  stops after limit+1 rows and the gateway reports truncation.
- A stdin pipeline error during a helper upload masked the container's
  real nonzero exit code (and its 4xx mapping) as a generic 500. The
  nonzero exit now wins; the masked stream error is logged.

* feat(files): add a New file toolbar button with server-enforced create-only

The stack file explorer could create a folder from a toolbar button but a
new file only from a folder's right-click menu, so a file could not be
created at the stack root at all. Add a New file toolbar button beside New
folder, targeting the current directory.

Creating a file now routes through a new createEmptyStackFile helper that
posts a zero-byte file through the existing upload endpoint with overwrite
off, so the server's exclusive-create path rejects an existing name instead
of clobbering it. A file collision surfaces inline in the dialog; a folder
collision and other failures surface as a toast.

* fix(files): widen the tree row hit area and add horizontal scroll for long names

Right-clicking a file tree row only opened the Sencho context menu when the
click landed on the filename; the rest of the row fell through to the native
browser menu, and long names were truncated with no way to read them.

Make each row span the full pane width (and grow with its content) so the
whole row is the context-menu trigger, and let the tree scroll horizontally
so a long name is reachable instead of clipped. A new opt-in horizontal prop
on ScrollArea adds the styled horizontal scrollbar without clamping content
width.

* docs(files): document the New file button, full-row right-click, and long-name scrolling

* test(files): cover createEmptyStackFile targeting the stack root

Add an API-layer case for the empty-directory (stack root) create path, the
primary reason the New file toolbar button exists, so a regression in the
root-level URL would be caught at unit speed rather than only in e2e.

backend/src/services/FileSystemService.ts

@@ -1,9 +1,10 @@
 import path from 'path';
 import os from 'os';
 import crypto from 'crypto';
-import { promises as fsPromises, createReadStream } from 'fs';
+import { promises as fsPromises, createReadStream, createWriteStream } from 'fs';
 import type { Dirent } from 'fs';
-import type { Readable } from 'stream';
+import { Readable } from 'stream';
+import { pipeline } from 'stream/promises';
 import { NodeRegistry } from './NodeRegistry';
 import { isPathWithinBase, isValidStackName } from '../utils/validation';
 import { isBinaryBuffer } from '../utils/binaryDetect';
@@ -11,7 +12,10 @@ import { sanitizeForLog } from '../utils/safeLog';
 
 export interface FileEntry {
   name: string;
-  type: 'file' | 'directory' | 'symlink';
+  // 'other' covers non-regular helper-volume entries (fifo/socket/device): they
+  // are unrepresentable on the fs backend but the helper can surface them, and
+  // they must stay distinct from 'file' so the archive guard can reject them.
+  type: 'file' | 'directory' | 'symlink' | 'other';
   size: number;
   mtime: number;
   isProtected: boolean;
@@ -100,6 +104,18 @@ function fsCaseKey(s: string): string {
   return process.platform === 'win32' || process.platform === 'darwin' ? s.toLowerCase() : s;
 }
 
+/**
+ * True when resolved absolute path `candidate` is `parent` itself or sits inside
+ * it, compared case-folded so the guard stays authoritative on a case-insensitive
+ * filesystem. Used to block moving/copying a directory into its own subtree.
+ */
+function isSameOrDescendantFsPath(parent: string, candidate: string): boolean {
+  const parentKey = fsCaseKey(parent);
+  const parentKeyWithSep = parentKey.endsWith(path.sep) ? parentKey : parentKey + path.sep;
+  const candidateKey = fsCaseKey(candidate);
+  return candidateKey === parentKey || candidateKey.startsWith(parentKeyWithSep);
+}
+
 function isProtectedRelPath(relPath: string): boolean {
   if (!relPath) return false;
   const normalized = stripTrailingSlash(relPath);
@@ -1043,9 +1059,14 @@ export class FileSystemService {
    * compose. Tracked as a follow-up hardening, not a per-root regression.
    */
   private async resolveSafePathWithin(rootAbsDir: string, relPath: string): Promise<string> {
-    const target = relPath === '' ? rootAbsDir : path.resolve(rootAbsDir, relPath);
-
-    if (!isPathWithinBase(target, rootAbsDir)) {
+    // Canonical js/path-injection barrier inline with the realpath sinks below:
+    // isPathWithinBase performs the same containment check, but static analysis
+    // only credits the path.resolve + startsWith form when it sits at the sink.
+    // relPath === '' resolves to the (server-controlled) root itself and carries
+    // no user input, so it needs no containment check.
+    const baseResolved = path.resolve(rootAbsDir);
+    const target = path.resolve(baseResolved, relPath);
+    if (relPath !== '' && !target.startsWith(baseResolved + path.sep)) {
       throw Object.assign(new Error('Path escapes root directory'), { code: 'INVALID_PATH' });
     }
 
@@ -1067,6 +1088,21 @@ export class FileSystemService {
         }
         suffix.unshift(path.basename(existing));
         existing = parent;
+        if (existing === baseResolved) {
+          // Reached the root: realpath the untainted base (never a tainted input)
+          // and reattach the not-yet-existing suffix.
+          const realBase = await fsPromises.realpath(baseResolved);
+          if (!isPathWithinBase(realBase, rootAbsDir)) {
+            throw Object.assign(new Error('Symlink escapes root directory'), { code: 'SYMLINK_ESCAPE' });
+          }
+          realTarget = path.join(realBase, ...suffix);
+          break;
+        }
+        // Inline js/path-injection barrier: existing is now strictly below the
+        // root, so the canonical path.resolve + startsWith form credits the sink.
+        if (!existing.startsWith(baseResolved + path.sep)) {
+          throw Object.assign(new Error('Path escapes root directory'), { code: 'INVALID_PATH' });
+        }
         try {
           const realExisting = await fsPromises.realpath(existing);
           if (!isPathWithinBase(realExisting, rootAbsDir)) {
@@ -1255,7 +1291,7 @@ export class FileSystemService {
    */
   private async writeStackFileAtomic(
     safePath: string,
-    data: string | Buffer,
+    data: string | Buffer | Readable,
     opts: { exclusive?: boolean } = {},
   ): Promise<void> {
     await fsPromises.mkdir(path.dirname(safePath), { recursive: true });
@@ -1265,13 +1301,28 @@ export class FileSystemService {
     const tmpPath = `${safePath}.sencho-tmp-${suffix}`;
     let stagedTmp = false;
     try {
-      const fh = await fsPromises.open(tmpPath, 'wx');
-      stagedTmp = true;
-      try {
-        await fh.writeFile(data);
-        await fh.sync();
-      } finally {
-        await fh.close();
+      if (data instanceof Readable) {
+        // Stream a temp-file source (an upload spooled to disk) into the staging
+        // file without buffering it in memory. 'wx' exclusively creates the
+        // staging file; the random suffix already guarantees a fresh name.
+        const ws = createWriteStream(tmpPath, { flags: 'wx' });
+        stagedTmp = true;
+        await pipeline(data, ws);
+        const synced = await fsPromises.open(tmpPath, 'r+');
+        try {
+          await synced.sync();
+        } finally {
+          await synced.close();
+        }
+      } else {
+        const fh = await fsPromises.open(tmpPath, 'wx');
+        stagedTmp = true;
+        try {
+          await fh.writeFile(data);
+          await fh.sync();
+        } finally {
+          await fh.close();
+        }
       }
       if (opts.exclusive) {
         // link() is atomic against EEXIST. Tmp and target are guaranteed to live
@@ -1306,14 +1357,22 @@ export class FileSystemService {
     await this.writeStackFileAtomic(safePath, content, opts);
   }
 
-  async writeStackFileBuffer(
+  /**
+   * Atomic, scoped write whose source is a temp file on disk (an upload spooled
+   * by multer's diskStorage). Streams the temp file into a staging sibling in the
+   * target's own directory, fsyncs, then links/renames into place, so a large
+   * upload is never buffered in memory and the temp file's filesystem can differ
+   * from the stack/volume filesystem (no cross-device rename). The caller owns
+   * deleting tempPath.
+   */
+  async writeScopedFileFromTemp(
     stackName: string,
     relPath: string,
-    buffer: Buffer,
+    tempPath: string,
     opts?: { exclusive?: boolean; scope?: FileRootScope },
   ): Promise<void> {
     const safePath = await this.resolveScopedPath(stackName, relPath, opts?.scope);
-    await this.writeStackFileAtomic(safePath, buffer, opts);
+    await this.writeStackFileAtomic(safePath, createReadStream(tempPath), { exclusive: opts?.exclusive });
   }
 
   /**
@@ -1481,17 +1540,10 @@ export class FileSystemService {
       throw Object.assign(new Error('Invalid destination name'), { code: 'INVALID_PATH' });
     }
     // Block moving a directory into itself or one of its own descendants; fs.rename
-    // would otherwise fail with an opaque EINVAL/EPERM. Compare case-folded so the
-    // guard stays authoritative when the source is supplied with non-disk casing on
-    // a case-insensitive filesystem.
+    // would otherwise fail with an opaque EINVAL/EPERM.
     const fromStat = await fsPromises.lstat(fromPath);
-    if (fromStat.isDirectory()) {
-      const fromKey = fsCaseKey(fromPath);
-      const fromKeyWithSep = fromKey.endsWith(path.sep) ? fromKey : fromKey + path.sep;
-      const toKey = fsCaseKey(toPath);
-      if (toKey === fromKey || toKey.startsWith(fromKeyWithSep)) {
-        throw Object.assign(new Error('Cannot move a folder into itself'), { code: 'INVALID_PATH' });
-      }
+    if (fromStat.isDirectory() && isSameOrDescendantFsPath(fromPath, toPath)) {
+      throw Object.assign(new Error('Cannot move a folder into itself'), { code: 'INVALID_PATH' });
     }
     // Prevent overwriting an existing path. lstat (not access) so a dangling
     // symlink already at the destination still counts as occupied.
@@ -1505,6 +1557,46 @@ export class FileSystemService {
     await fsPromises.rename(fromPath, toPath);
   }
 
+  /**
+   * Copies a file or directory within a single root. The source resolves through
+   * the leaf helper and the copy does not dereference symlinks, so a symlink
+   * entry is copied as a link (matching the delete/rename leaf policy) rather
+   * than followed to its target. Only the destination is protection-checked:
+   * duplicating a protected file (e.g. compose.yaml) elsewhere is allowed, but a
+   * copy cannot create a reserved name at a protected root. An existing
+   * destination is rejected (surfaced as EEXIST, which the route maps to 409).
+   */
+  async copyScopedPath(stackName: string, fromRel: string, toRel: string, scope?: FileRootScope): Promise<void> {
+    if ((scope?.protectedEnabled ?? true) && isProtectedRelPath(toRel)) throw protectedFileError(toRel);
+    const fromPath = await this.resolveScopedLeafPath(stackName, fromRel, scope);
+    const toPath = await this.resolveScopedLeafPath(stackName, toRel, scope);
+    const toName = path.basename(toPath);
+    if (!toName || toName === '.' || toName === '..') {
+      throw Object.assign(new Error('Invalid destination name'), { code: 'INVALID_PATH' });
+    }
+    // Block copying a directory into itself or one of its own descendants;
+    // fs.cp would otherwise recurse into the copy it is creating.
+    const fromStat = await fsPromises.lstat(fromPath);
+    if (fromStat.isDirectory() && isSameOrDescendantFsPath(fromPath, toPath)) {
+      throw Object.assign(new Error('Cannot copy a folder into itself'), { code: 'INVALID_PATH' });
+    }
+    try {
+      await fsPromises.cp(fromPath, toPath, {
+        recursive: fromStat.isDirectory(),
+        dereference: false,
+        errorOnExist: true,
+        force: false,
+      });
+    } catch (err: unknown) {
+      // fs.cp raises ERR_FS_CP_EEXIST when the destination already exists; remap
+      // to EEXIST so the route returns 409, matching rename's conflict handling.
+      if ((err as NodeJS.ErrnoException).code === 'ERR_FS_CP_EEXIST') {
+        throw Object.assign(new Error('A file or folder with that name already exists'), { code: 'EEXIST' });
+      }
+      throw err;
+    }
+  }
+
   async getStackEntryMode(stackName: string, relPath: string, scope?: FileRootScope): Promise<{ mode: number; octal: string }> {
     const safePath = await this.resolveScopedPath(stackName, relPath, scope);
     const stat = await fsPromises.stat(safePath);