feat(files): per-stack file explorer (#780)

* feat(files): backend foundation for stack file explorer

Install multer for multipart file upload handling. Add
isValidRelativeStackPath to validation.ts to guard client-supplied
relative paths against traversal, absolute paths, NUL bytes, backslash
injection, and double-slash segments. Add isBinaryBuffer to a new
binaryDetect.ts utility for heuristic text/binary detection via
NUL-byte fast exit and non-printable byte ratio sampling.

* fix(files): reject bare dot segments in isValidRelativeStackPath

* feat(files): add safe stack-scoped file I/O methods to FileSystemService

Adds FileEntry interface and seven new public methods to FileSystemService
for stack-scoped file operations: listStackDirectory, readStackFile,
streamStackFile, writeStackFile, deleteStackPath, mkdirStackPath, and
statStackEntry.

Each method routes through a private resolveSafeStackPath helper that
enforces two-phase path containment: a pre-realpath lexical check plus a
post-realpath symlink-escape check. ENOENT targets are handled by walking
up to the deepest existing ancestor, realpaths that ancestor, and
reattaching the remaining suffix.

Binary detection delegates to isBinaryBuffer; path safety delegates to
isPathWithinBase. Protected file names and the MIME map are module-level
constants to avoid repeated allocation.

* feat(files): frontend API wrappers and Monaco language helper

* fix(files): tighten stackFilesApi error handling and localOnly support

* fix(files): FileSystemService safety and correctness fixes

* feat(files): add file explorer API endpoints to stacks router

* feat(files): FileTree and FileTreeNode components

* fix(files): route security hardening and stream cleanup

* fix(files): FileTree accessibility, icon stroke, stale fetch guard

Add strokeWidth={1.5} to all Lucide icons in FileTreeNode to match the
design system. Add aria-expanded to directory rows for accessibility.
Guard handleDirClick .then() callbacks against stale stack name
references when the component re-renders with a new stack. Add
toast.info fallbacks when compose.yaml or .env is clicked without a
navigation callback registered.

* feat(files): FileViewer, FileUploadDropzone, NewFolderDialog, DeleteFileConfirm

* fix(files): resolve code quality findings in file explorer components

- Move editorOptions useMemo above conditional returns in FileViewer (Rules of Hooks fix)
- Fix blob download: append anchor to DOM before click, defer URL revoke 100ms
- Keep protected-file confirm input visible during NOT_EMPTY recursive retry in DeleteFileConfirm
- Remove non-functional cursor-pointer/onClick from Community upgrade pill in FileUploadDropzone
- Add success toast on folder creation in NewFolderDialog
- Switch all (e as Error).message casts to instanceof Error narrowing

* test(files): unit tests for binary detection, stack path safety, and file explorer routes

- binary-detection.test.ts: covers isBinaryBuffer edge cases (empty, NUL,
  PNG header, threshold boundary, sampleBytes parameter)
- filesystem-stack-paths.test.ts: covers isValidRelativeStackPath (accepts/
  rejects matrix) and FileSystemService stack methods against a real temp dir
  (listStackDirectory sort and protection flags, readStackFile text/binary/
  oversized paths, writeStackFile/Buffer, deleteStackPath, mkdirStackPath,
  traversal guard); platform-specific empty-dir/NOT_EMPTY cases skip on Windows
- stack-files-routes.test.ts: route-level integration tests for all seven
  file explorer endpoints; covers auth gating, Community-tier 403 gates,
  input validation, 413 TOO_LARGE upload limit, and 204/200 happy paths

* feat(files): StackFileExplorer container with lazy tree, viewer, and action bar

* fix(files): add Download button to explorer toolbar, fix Community upgrade pill, reset state on stack change

* test(files): add missing test coverage for file explorer routes and service

* feat(files): add Files tab to EditorLayout with StackFileExplorer integration

* fix(files): add defensive activeTab guard to saveFile and discardChanges

* test(files): unit tests for FileTree expand/collapse and FileViewer render modes

Covers the three FileViewer content modes (text/Monaco, binary panel,
oversized panel) and the FileTree expand/collapse/cache cycle: first
expand fetches the subdirectory, second click collapses without a fetch,
third click re-expands from the in-memory cache without a second fetch.

* test(e2e): file explorer community and skipper+ flows

Covers the full file-explorer feature surface in two describe blocks:

Community (read-only): intercepts /api/license to simulate community
tier, confirms the upgrade pill is visible in the left pane, and
asserts that the Save button is absent after opening a text file.

Skipper+ (full CRUD): uploads a text file and confirms it appears in
the tree; edits config/app.conf and saves via Monaco; deletes an
uploaded file and asserts the tree entry is gone; issues a raw HTTP
request to the download endpoint and checks for status 200 and the
content-disposition: attachment header.

Also adds data-testid="file-action-delete" to the action bar Delete
button in StackFileExplorer for stable targeting, and exports
waitForStacksLoaded from e2e/helpers.ts to eliminate the three
identical local copies in stacks, deploy-log-panel, and stack-files
spec files.

* fix(e2e): improve test isolation and selector stability in stack-files spec

Move beforeEach seed to beforeAll/afterAll so fixtures are created once per
suite, not before every test. Extract shared seedSuite/teardownSuite helpers
to eliminate the duplicate beforeAll/afterAll blocks. Wrap teardown in
try/catch so failures log a warning rather than masking test results.

Replace waitForTimeout(500) with a deterministic expect on the file tree
sentinel. Add data-testid="anatomy-files-btn" and data-testid="delete-confirm-btn"
to replace the fragile button text/positional selectors. Assert Save button
starts disabled before editing.

* docs(files): add stack file explorer documentation

Add user-facing guide for the stack file explorer feature covering
tier access (Community read-only, Skipper+ read-write), viewing
limits, upload/download caps, protected file routing, and
troubleshooting. Update the editor page to reference the new guide
and register the page in the navigation.

* fix(docs): use canonical Skipper tier name in file explorer overview card

* fix(files): resolve lint errors blocking CI

Remove unnecessary backslash escape before double-quote in the
Content-Disposition regex (no-useless-escape). Replace five synchronous
setState resets at the top of the FileTree mount effect with a React key
prop on the FileTree element in StackFileExplorer so remounting resets
state automatically, eliminating the react-hooks/set-state-in-effect
violation.

* test(files): fix e2e seeding to work on community-tier CI

Replace the browser-side paid upload/mkdir API calls in seedTestStack with
direct Node fs writes. The upload and folder endpoints require Skipper+ so
they returned 403 on CI, which runs with no license set. Stack creation
via POST /api/stacks stays as an API call since it is community-allowed and
keeps the backend registry in sync.

Add a per-test tier check in the Skipper+ beforeEach that skips gracefully
when the instance is community, matching the pattern in auto-heal-policies.

frontend/src/components/files/FileViewer.tsx

@@ -0,0 +1,292 @@
+import { useState, useEffect, useMemo } from 'react';
+import Editor from '@monaco-editor/react';
+import { AlertCircle, FileIcon, Download, Lock, Loader2, Save } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { Skeleton } from '@/components/ui/skeleton';
+import { toast } from '@/components/ui/toast-store';
+import { useLicense } from '@/context/LicenseContext';
+import { readStackFile, writeStackFile, downloadStackFile } from '@/lib/stackFilesApi';
+import { extensionToLanguage } from '@/lib/monacoLanguages';
+import { formatBytes } from '@/lib/utils';
+
+interface FileViewerProps {
+  stackName: string;
+  selectedPath: string | null;
+  canEdit: boolean;
+  isDarkMode: boolean;
+  onSaved?: () => void;
+}
+
+function getFilename(path: string): string {
+  return path.split('/').pop() ?? path;
+}
+
+interface SpecialFilePanelProps {
+  filename: string;
+  size: number;
+  label: string;
+  stackName: string;
+  relPath: string;
+  canDownload: boolean;
+}
+
+function SpecialFilePanel({
+  filename,
+  size,
+  label,
+  stackName,
+  relPath,
+  canDownload,
+}: SpecialFilePanelProps) {
+  const [downloading, setDownloading] = useState(false);
+
+  const handleDownload = async () => {
+    if (!canDownload) return;
+    setDownloading(true);
+    try {
+      const res = await downloadStackFile(stackName, relPath);
+      if (!res.ok) {
+        toast.error('Download failed.');
+        return;
+      }
+      const blob = await res.blob();
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = filename;
+      document.body.appendChild(a);
+      a.click();
+      document.body.removeChild(a);
+      setTimeout(() => URL.revokeObjectURL(url), 100);
+    } catch (e) {
+      toast.error(e instanceof Error ? e.message : 'Download failed.');
+    } finally {
+      setDownloading(false);
+    }
+  };
+
+  return (
+    <div className="flex flex-col items-center justify-center gap-4 h-full min-h-[200px] text-muted-foreground">
+      <FileIcon className="w-10 h-10 text-stat-icon" strokeWidth={1.25} />
+      <div className="text-center space-y-1">
+        <p className="font-mono text-sm text-stat-title">{filename}</p>
+        <p className="text-xs text-stat-subtitle">{label} &middot; {formatBytes(size)}</p>
+      </div>
+      {canDownload ? (
+        <Button
+          variant="outline"
+          size="sm"
+          onClick={() => void handleDownload()}
+          disabled={downloading}
+        >
+          {downloading ? (
+            <Loader2 className="w-4 h-4 mr-1.5 animate-spin" strokeWidth={1.5} />
+          ) : (
+            <Download className="w-4 h-4 mr-1.5" strokeWidth={1.5} />
+          )}
+          Download
+        </Button>
+      ) : (
+        <div title="Upgrade to download files">
+          <Button variant="outline" size="sm" disabled>
+            <Lock className="w-4 h-4 mr-1.5" strokeWidth={1.5} />
+            Download
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export function FileViewer({
+  stackName,
+  selectedPath,
+  canEdit,
+  isDarkMode,
+  onSaved,
+}: FileViewerProps) {
+  const { isPaid } = useLicense();
+
+  const [content, setContent] = useState('');
+  const [originalContent, setOriginalContent] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [isBinary, setIsBinary] = useState(false);
+  const [isOversized, setIsOversized] = useState(false);
+  const [size, setSize] = useState(0);
+
+  const readOnly = !canEdit || !isPaid;
+
+  const editorOptions = useMemo(
+    () => ({
+      readOnly,
+      minimap: { enabled: false },
+      fontFamily: "'Geist Mono', monospace",
+      fontSize: 13,
+      padding: { top: 8 },
+      scrollBeyondLastLine: false,
+    }),
+    [readOnly],
+  );
+
+  useEffect(() => {
+    if (!selectedPath) {
+      setContent('');
+      setOriginalContent('');
+      setIsBinary(false);
+      setIsOversized(false);
+      setError(null);
+      return;
+    }
+
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    setIsBinary(false);
+    setIsOversized(false);
+
+    readStackFile(stackName, selectedPath)
+      .then((result) => {
+        if (cancelled) return;
+        setSize(result.size);
+        if (result.binary) {
+          setIsBinary(true);
+        } else if (result.oversized) {
+          setIsOversized(true);
+        } else {
+          const text = result.content ?? '';
+          setContent(text);
+          setOriginalContent(text);
+        }
+      })
+      .catch((e: unknown) => {
+        if (cancelled) return;
+        setError(e instanceof Error ? e.message : 'Failed to load file.');
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [stackName, selectedPath]);
+
+  const handleSave = async () => {
+    if (!selectedPath) return;
+    setSaving(true);
+    const loadingId = toast.loading('Saving...');
+    try {
+      await writeStackFile(stackName, selectedPath, content);
+      setOriginalContent(content);
+      toast.success('Saved.');
+      onSaved?.();
+    } catch (e) {
+      toast.error(e instanceof Error ? e.message : 'Save failed.');
+    } finally {
+      toast.dismiss(loadingId);
+      setSaving(false);
+    }
+  };
+
+  if (!selectedPath) {
+    return (
+      <div className="flex items-center justify-center h-full text-muted-foreground text-sm">
+        Select a file to view it
+      </div>
+    );
+  }
+
+  if (loading) {
+    return (
+      <div className="flex flex-col h-full p-3 gap-2">
+        <Skeleton className="h-9 w-full" />
+        <Skeleton className="flex-1 w-full" />
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="flex flex-col items-center justify-center gap-2 h-full text-muted-foreground">
+        <AlertCircle className="w-6 h-6 text-destructive" strokeWidth={1.5} />
+        <p className="text-sm text-center px-4">{error}</p>
+      </div>
+    );
+  }
+
+  const filename = getFilename(selectedPath);
+  const language = extensionToLanguage(filename);
+
+  if (isBinary) {
+    return (
+      <SpecialFilePanel
+        filename={filename}
+        size={size}
+        label="Binary file"
+        stackName={stackName}
+        relPath={selectedPath}
+        canDownload={isPaid}
+      />
+    );
+  }
+
+  if (isOversized) {
+    return (
+      <SpecialFilePanel
+        filename={filename}
+        size={size}
+        label="File too large to preview"
+        stackName={stackName}
+        relPath={selectedPath}
+        canDownload={isPaid}
+      />
+    );
+  }
+
+  const hasChanges = content !== originalContent;
+
+  return (
+    <div className="flex flex-col h-full">
+      <div className="flex items-center justify-between gap-2 px-3 py-1.5 border-b border-glass-border shrink-0">
+        <span className="font-mono text-xs text-stat-subtitle truncate">{filename}</span>
+        <div className="flex items-center gap-2 shrink-0">
+          {readOnly && (
+            <span className="text-[10px] uppercase tracking-widest text-muted-foreground border border-border rounded px-1.5 py-0.5">
+              Read-only
+            </span>
+          )}
+          {!readOnly && (
+            <Button
+              size="sm"
+              className="h-7"
+              onClick={() => void handleSave()}
+              disabled={saving || !hasChanges}
+            >
+              {saving ? (
+                <Loader2 className="w-3.5 h-3.5 mr-1 animate-spin" strokeWidth={1.5} />
+              ) : (
+                <Save className="w-3.5 h-3.5 mr-1" strokeWidth={1.5} />
+              )}
+              Save
+            </Button>
+          )}
+        </div>
+      </div>
+
+      <div className="flex-1 min-h-0">
+        <Editor
+          height="100%"
+          language={language}
+          value={content}
+          onChange={(val) => {
+            if (!readOnly) setContent(val ?? '');
+          }}
+          theme={isDarkMode ? 'vs-dark' : 'light'}
+          options={editorOptions}
+        />
+      </div>
+    </div>
+  );
+}