hazo_files 1.5.2 → 2.0.0

package/docs/superpowers/plans/2026-05-23-test-app-v2-providers.md

@@ -0,0 +1,968 @@
+# Test-App v2 Provider Pages Implementation Plan
+
+## Implementation Progress
+
+- [x] Task 1: Export `AppFileServerProvider` from `hazo_files/server` + rebuild — c2a17c3 (2026-05-23)
+- [x] Task 2: Sidebar — v2 Providers section — 39d68fa (2026-05-23)
+- [x] Task 3: API route `/api/providers/app-file-server` — 0c2d598 (2026-05-23)
+- [x] Task 4: Signed-URL serve route — 0983dfa (2026-05-23)
+- [x] Task 5: AppFileServerProvider scenario page — fdff8ec (2026-05-23)
+- [x] Task 6: Stub pages (InMemory + GDrive) — d815df6 (2026-05-23)
+- [ ] Task 7: Smoke test — manual browser verification needed
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add interactive test pages for the Phase 1.16 `FileStorageProvider` abstraction to the hazo_files test-app — a live AppFileServerProvider page with 8 runnable scenarios, a signed-URL serve route, and stub pages for InMemoryProvider and GoogleDriveProvider.
+
+**Architecture:** The test-app's Next.js API routes instantiate `AppFileServerProvider` directly (no TrackedFileManager layer); a new `/api/files/serve/[token]/[...path]` route verifies HMAC tokens and streams files; the sidebar is extended to support optional section labels. No changes to the `hazo_files` package source logic — only exports and the test-app.
+
+**Tech Stack:** Next.js 14 (App Router), TypeScript, `hazo_files/server` (symlinked local package), Lucide React icons, Tailwind CSS, shadcn/ui Button component. All work is in `/Users/pubs/Local/01.code/00.lib/hazo_files/` unless stated otherwise. Test-app lives at `test-app/` within that root.
+
+---
+
+## File map
+
+| File | Action | Purpose |
+|---|---|---|
+| `src/server/index.ts` | Modify | Export `AppFileServerProvider` + `AppFileServerOpts` |
+| `test-app/app/components/Sidebar.tsx` | Modify | Add `section?` label support + 3 new nav entries |
+| `test-app/app/api/providers/app-file-server/route.ts` | Create | Action-dispatched API for all 8 provider operations |
+| `test-app/app/api/files/serve/[token]/[...path]/route.ts` | Create | HMAC-verified file serving |
+| `test-app/app/providers/app-file-server/page.tsx` | Create | 8 scenario cards + signed-URL link |
+| `test-app/app/providers/in-memory/page.tsx` | Create | Stub: interface listing + coming-soon badge |
+| `test-app/app/providers/gdrive/page.tsx` | Create | Stub: interface listing + coming-soon badge |
+
+---
+
+## Task 1: Export `AppFileServerProvider` from `hazo_files/server` and rebuild
+
+**Files:**
+- Modify: `src/server/index.ts`
+
+The test-app imports from `hazo_files/server` (the compiled `dist/server/index.js`). `AppFileServerProvider` is currently only at `src/providers/app-file-server.ts` with no export from the entry points. This task adds the export and rebuilds so the test-app can import it.
+
+- [ ] **Step 1: Add exports to `src/server/index.ts`**
+
+After the `// Schema exports` block (around line 93), add:
+
+```ts
+// Storage providers
+export { AppFileServerProvider } from '../providers/app-file-server';
+export type { AppFileServerOpts } from '../providers/app-file-server';
+export type {
+  FileStorageProvider,
+  StoragePath,
+  PutOpts,
+  PutResult,
+  SignedUrlOpts,
+  ProbeResult,
+} from '../providers/types';
+export { StorageCollisionExhausted, StorageNotConfigured, StorageUnavailable } from '../providers/types';
+```
+
+- [ ] **Step 2: Rebuild the package**
+
+```bash
+cd /Users/pubs/Local/01.code/00.lib/hazo_files
+npm run build
+```
+
+Expected: build completes with no errors.
+
+- [ ] **Step 3: Verify the export is reachable**
+
+```bash
+node -e "const { AppFileServerProvider } = require('./dist/server/index.js'); console.log(typeof AppFileServerProvider);"
+```
+
+Expected output: `function`
+
+- [ ] **Step 4: Commit**
+
+```bash
+cd /Users/pubs/Local/01.code/00.lib/hazo_files
+git add src/server/index.ts
+git commit -m "feat(hazo_files): export AppFileServerProvider from server entry point"
+```
+
+---
+
+## Task 2: Sidebar — add v2 Providers section
+
+**Files:**
+- Modify: `test-app/app/components/Sidebar.tsx`
+
+The sidebar renders a flat `menuItems` array. Extend the item shape with an optional `section` field; when a section label changes, render a `<Separator />` + small label before that group.
+
+- [ ] **Step 1: Update `Sidebar.tsx`**
+
+Replace the entire file content:
+
+```tsx
+'use client';
+
+import React from 'react';
+import Link from 'next/link';
+import { usePathname } from 'next/navigation';
+import {
+  FolderOpen,
+  Cloud,
+  Inbox,
+  Settings,
+  HardDrive,
+  Home,
+  ChevronLeft,
+  ChevronRight,
+  FileText,
+  FlaskConical,
+  Database,
+  Tags,
+  Upload,
+  Bot,
+  MessageSquare,
+  Tag,
+  Gauge,
+  Link as LinkIcon,
+  Archive,
+  Server,
+  MemoryStick,
+} from 'lucide-react';
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/ui/button';
+import { Separator } from '@/components/ui/separator';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '@/components/ui/tooltip';
+
+interface SidebarProps {
+  collapsed: boolean;
+  onToggle: () => void;
+}
+
+interface MenuItem {
+  title: string;
+  icon: React.ComponentType<{ className?: string }>;
+  href: string;
+  /** When set, renders a separator + this label before this item. */
+  section?: string;
+}
+
+const menuItems: MenuItem[] = [
+  { title: 'Home', icon: Home, href: '/' },
+  { title: 'Local Files', icon: HardDrive, href: '/local' },
+  { title: 'Google Drive', icon: Cloud, href: '/google-drive' },
+  { title: 'Dropbox', icon: Inbox, href: '/dropbox' },
+  { title: 'Naming Config', icon: FileText, href: '/naming-config' },
+  { title: 'Naming Test', icon: FlaskConical, href: '/naming-test' },
+  { title: 'File Metadata', icon: Database, href: '/file-metadata' },
+  { title: 'Naming Conventions', icon: Tags, href: '/naming-conventions' },
+  { title: 'Upload & Extract', icon: Upload, href: '/upload-extract' },
+  { title: 'Content Tag', icon: Tag, href: '/content-tag' },
+  { title: 'LLM API', icon: Bot, href: '/llm-api' },
+  { title: 'Prompts', icon: MessageSquare, href: '/prompts' },
+  { title: 'Quota', icon: Gauge, href: '/quota' },
+  { title: 'URL Import', icon: LinkIcon, href: '/url_import' },
+  { title: 'Lifecycle', icon: Archive, href: '/lifecycle' },
+  {
+    title: 'App File Server',
+    icon: Server,
+    href: '/providers/app-file-server',
+    section: 'v2 Providers',
+  },
+  { title: 'In-Memory', icon: MemoryStick, href: '/providers/in-memory' },
+  { title: 'GDrive Provider', icon: Cloud, href: '/providers/gdrive' },
+];
+
+const bottomItems: MenuItem[] = [
+  { title: 'Settings', icon: Settings, href: '/settings' },
+];
+
+export function Sidebar({ collapsed, onToggle }: SidebarProps) {
+  const pathname = usePathname();
+
+  function renderItem(item: MenuItem, index: number) {
+    const isActive =
+      pathname === item.href ||
+      (item.href !== '/' && pathname.startsWith(item.href));
+    const Icon = item.icon;
+
+    const button = collapsed ? (
+      <Tooltip key={item.href}>
+        <TooltipTrigger asChild>
+          <Link href={item.href}>
+            <Button
+              variant={isActive ? 'secondary' : 'ghost'}
+              size="icon"
+              className={cn(
+                'w-full justify-center',
+                isActive && 'bg-sidebar-accent text-sidebar-accent-foreground'
+              )}
+            >
+              <Icon className="h-5 w-5" />
+            </Button>
+          </Link>
+        </TooltipTrigger>
+        <TooltipContent side="right">{item.title}</TooltipContent>
+      </Tooltip>
+    ) : (
+      <Link key={item.href} href={item.href}>
+        <Button
+          variant={isActive ? 'secondary' : 'ghost'}
+          className={cn(
+            'w-full justify-start gap-3',
+            isActive && 'bg-sidebar-accent text-sidebar-accent-foreground'
+          )}
+        >
+          <Icon className="h-5 w-5" />
+          {item.title}
+        </Button>
+      </Link>
+    );
+
+    if (item.section) {
+      return (
+        <React.Fragment key={item.href}>
+          <div className="pt-2 pb-1">
+            <Separator />
+            {!collapsed && (
+              <p className="px-3 pt-2 text-[10px] font-semibold uppercase tracking-wider text-muted-foreground">
+                {item.section}
+              </p>
+            )}
+          </div>
+          {button}
+        </React.Fragment>
+      );
+    }
+
+    return <React.Fragment key={`${item.href}-${index}`}>{button}</React.Fragment>;
+  }
+
+  return (
+    <TooltipProvider delayDuration={0}>
+      <aside
+        className={cn(
+          'flex flex-col h-full bg-sidebar border-r border-sidebar-border transition-all duration-300',
+          collapsed ? 'w-16' : 'w-64'
+        )}
+      >
+        {/* Header */}
+        <div className="flex items-center h-16 px-4 border-b border-sidebar-border">
+          {!collapsed && (
+            <div className="flex items-center gap-2">
+              <FolderOpen className="h-6 w-6 text-sidebar-primary" />
+              <span className="font-semibold text-sidebar-foreground">Hazo Files</span>
+            </div>
+          )}
+          {collapsed && (
+            <FolderOpen className="h-6 w-6 text-sidebar-primary mx-auto" />
+          )}
+        </div>
+
+        {/* Navigation */}
+        <nav className="flex-1 p-2 space-y-1 overflow-y-auto">
+          {menuItems.map((item, index) => renderItem(item, index))}
+        </nav>
+
+        <Separator />
+
+        {/* Bottom items */}
+        <div className="p-2 space-y-1">
+          {bottomItems.map((item, index) => renderItem(item, index))}
+        </div>
+
+        {/* Collapse toggle */}
+        <div className="p-2 border-t border-sidebar-border">
+          <Button
+            variant="ghost"
+            size="icon"
+            onClick={onToggle}
+            className="w-full"
+          >
+            {collapsed ? (
+              <ChevronRight className="h-4 w-4" />
+            ) : (
+              <ChevronLeft className="h-4 w-4" />
+            )}
+          </Button>
+        </div>
+      </aside>
+    </TooltipProvider>
+  );
+}
+
+export default Sidebar;
+```
+
+- [ ] **Step 2: Verify it compiles**
+
+```bash
+cd /Users/pubs/Local/01.code/00.lib/hazo_files/test-app
+npx tsc --noEmit 2>&1 | head -20
+```
+
+Expected: no errors (or only pre-existing errors unrelated to Sidebar.tsx).
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd /Users/pubs/Local/01.code/00.lib/hazo_files
+git add test-app/app/components/Sidebar.tsx
+git commit -m "feat(test-app): add v2 Providers section to sidebar"
+```
+
+---
+
+## Task 3: API route for AppFileServerProvider
+
+**Files:**
+- Create: `test-app/app/api/providers/app-file-server/route.ts`
+
+Single route file handling GET (probe, exists, get, sign) and POST (put, delete). Instantiates `AppFileServerProvider` with root `./files/provider-test` and the `APP_FILE_SERVER_HMAC_SECRET` env var (dev fallback: `"dev-hmac-secret"`).
+
+- [ ] **Step 1: Create the directory and route file**
+
+```bash
+mkdir -p /Users/pubs/Local/01.code/00.lib/hazo_files/test-app/app/api/providers/app-file-server
+```
+
+Create `test-app/app/api/providers/app-file-server/route.ts`:
+
+```ts
+import { NextRequest, NextResponse } from 'next/server';
+import path from 'node:path';
+import { AppFileServerProvider } from 'hazo_files/server';
+
+function makeProvider() {
+  return new AppFileServerProvider({
+    root: path.join(process.cwd(), 'files/provider-test'),
+    hmac_secret: process.env.APP_FILE_SERVER_HMAC_SECRET ?? 'dev-hmac-secret',
+  });
+}
+
+export async function GET(request: NextRequest) {
+  const { searchParams } = new URL(request.url);
+  const action = searchParams.get('action');
+  const filePath = searchParams.get('path') ?? '';
+  const ttl = Number(searchParams.get('ttl') ?? '60');
+
+  const provider = makeProvider();
+
+  try {
+    switch (action) {
+      case 'probe': {
+        const result = await provider.probe();
+        return NextResponse.json({ success: true, data: result });
+      }
+
+      case 'exists': {
+        if (!filePath) return NextResponse.json({ success: false, error: 'path required' }, { status: 400 });
+        const exists = await provider.exists(filePath);
+        return NextResponse.json({ success: true, data: { exists } });
+      }
+
+      case 'get': {
+        if (!filePath) return NextResponse.json({ success: false, error: 'path required' }, { status: 400 });
+        const buf = await provider.get(filePath) as Buffer;
+        return NextResponse.json({ success: true, data: { content: buf.toString() } });
+      }
+
+      case 'sign': {
+        if (!filePath) return NextResponse.json({ success: false, error: 'path required' }, { status: 400 });
+        const url = await provider.getSignedUrl(filePath, { ttl_seconds: ttl });
+        return NextResponse.json({ success: true, data: { url } });
+      }
+
+      default:
+        return NextResponse.json({ success: false, error: `Unknown action: ${action}` }, { status: 400 });
+    }
+  } catch (err) {
+    const e = err as Error;
+    return NextResponse.json(
+      { success: false, error: e.message, errorType: e.constructor.name },
+      { status: 500 }
+    );
+  }
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json() as {
+    action: string;
+    path?: string;
+    content?: string;
+    ifNotExists?: boolean;
+  };
+  const { action, path: filePath, content, ifNotExists } = body;
+
+  if (!filePath) {
+    return NextResponse.json({ success: false, error: 'path required' }, { status: 400 });
+  }
+
+  const provider = makeProvider();
+
+  try {
+    switch (action) {
+      case 'put': {
+        const buf = Buffer.from(content ?? '');
+        const result = await provider.put(filePath, buf, { ifNotExists: ifNotExists ?? false });
+        return NextResponse.json({ success: true, data: result });
+      }
+
+      case 'delete': {
+        await provider.delete(filePath);
+        return NextResponse.json({ success: true, data: { deleted: true } });
+      }
+
+      default:
+        return NextResponse.json({ success: false, error: `Unknown action: ${action}` }, { status: 400 });
+    }
+  } catch (err) {
+    const e = err as Error;
+    return NextResponse.json(
+      { success: false, error: e.message, errorType: e.constructor.name },
+      { status: 500 }
+    );
+  }
+}
+```
+
+- [ ] **Step 2: Verify TypeScript**
+
+```bash
+cd /Users/pubs/Local/01.code/00.lib/hazo_files/test-app
+npx tsc --noEmit 2>&1 | grep "app-file-server"
+```
+
+Expected: no output (no errors in this file).
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd /Users/pubs/Local/01.code/00.lib/hazo_files
+git add test-app/app/api/providers/app-file-server/route.ts
+git commit -m "feat(test-app): AppFileServerProvider API route"
+```
+
+---
+
+## Task 4: Signed-URL serve route
+
+**Files:**
+- Create: `test-app/app/api/files/serve/[token]/[...path]/route.ts`
+
+Verifies the HMAC token, reads the file, returns it with a sniffed Content-Type. Uses `getMimeType` already exported from `hazo_files/server` — no new dependencies needed.
+
+- [ ] **Step 1: Create the nested route directories**
+
+```bash
+mkdir -p "/Users/pubs/Local/01.code/00.lib/hazo_files/test-app/app/api/files/serve/[token]/[...path]"
+```
+
+- [ ] **Step 2: Create the route file**
+
+Create `test-app/app/api/files/serve/[token]/[...path]/route.ts`:
+
+```ts
+import { NextRequest, NextResponse } from 'next/server';
+import path from 'node:path';
+import { AppFileServerProvider, getMimeType } from 'hazo_files/server';
+
+function makeProvider() {
+  return new AppFileServerProvider({
+    root: path.join(process.cwd(), 'files/provider-test'),
+    hmac_secret: process.env.APP_FILE_SERVER_HMAC_SECRET ?? 'dev-hmac-secret',
+  });
+}
+
+export async function GET(
+  _request: NextRequest,
+  { params }: { params: Promise<{ token: string; path: string[] }> }
+) {
+  const { token, path: pathSegments } = await params;
+  const virtualPath = pathSegments.join('/');
+
+  const provider = makeProvider();
+
+  if (!provider.verifySignedUrl(token, virtualPath)) {
+    return NextResponse.json({ error: 'invalid_or_expired' }, { status: 401 });
+  }
+
+  let buf: Buffer;
+  try {
+    buf = (await provider.get(virtualPath)) as Buffer;
+  } catch {
+    return NextResponse.json({ error: 'not_found' }, { status: 404 });
+  }
+
+  const contentType = getMimeType(virtualPath) || 'application/octet-stream';
+  const filename = path.basename(virtualPath);
+
+  return new NextResponse(buf, {
+    headers: {
+      'Content-Type': contentType,
+      'Content-Disposition': `inline; filename="${filename}"`,
+      'Cache-Control': 'private, no-store',
+    },
+  });
+}
+```
+
+- [ ] **Step 3: Verify TypeScript**
+
+```bash
+cd /Users/pubs/Local/01.code/00.lib/hazo_files/test-app
+npx tsc --noEmit 2>&1 | grep "serve"
+```
+
+Expected: no output.
+
+- [ ] **Step 4: Commit**
+
+```bash
+cd /Users/pubs/Local/01.code/00.lib/hazo_files
+git add "test-app/app/api/files/serve"
+git commit -m "feat(test-app): HMAC-verified file serve route"
+```
+
+---
+
+## Task 5: AppFileServerProvider page
+
+**Files:**
+- Create: `test-app/app/providers/app-file-server/page.tsx`
+
+Eight scenario cards following the exact pattern of `app/lifecycle/page.tsx`. Scenario 5 (Signed URL) renders an extra `<a>` link in its result panel so the user can click through to the served file.
+
+- [ ] **Step 1: Create the directory and page**
+
+```bash
+mkdir -p /Users/pubs/Local/01.code/00.lib/hazo_files/test-app/app/providers/app-file-server
+```
+
+Create `test-app/app/providers/app-file-server/page.tsx`:
+
+```tsx
+'use client';
+
+import React, { useState } from 'react';
+import { Server, CheckCircle, XCircle } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+
+const FILE_PATH = 'provider-test/test.txt';
+const FILE_CONTENT = 'Hello AppFileServer';
+const API = '/api/providers/app-file-server';
+
+interface ScenarioResult {
+  label: string;
+  success: boolean;
+  data?: unknown;
+  error?: string;
+  errorType?: string;
+  signedUrl?: string;
+}
+
+function ResultPanel({ result }: { result: ScenarioResult | null }) {
+  if (!result) return null;
+  return (
+    <div
+      className={`mt-3 p-3 rounded-md text-sm border ${
+        result.success
+          ? 'bg-green-50 border-green-200 text-green-900'
+          : 'bg-red-50 border-red-200 text-red-900'
+      }`}
+    >
+      <div className="flex items-center gap-2 font-medium mb-1">
+        {result.success ? <CheckCircle className="h-4 w-4" /> : <XCircle className="h-4 w-4" />}
+        {result.label}
+      </div>
+      {result.error && (
+        <div className="text-red-700">Error ({result.errorType}): {result.error}</div>
+      )}
+      {result.data !== undefined && (
+        <pre className="text-xs mt-1 overflow-auto whitespace-pre-wrap">
+          {JSON.stringify(result.data, null, 2)}
+        </pre>
+      )}
+      {result.signedUrl && (
+        <div className="mt-2">
+          <a
+            href={result.signedUrl}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="text-blue-700 underline text-xs break-all"
+          >
+            Open signed URL →
+          </a>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function ScenarioCard({
+  title,
+  description,
+  onRun,
+  result,
+  loading,
+}: {
+  title: string;
+  description: string;
+  onRun: () => void;
+  result: ScenarioResult | null;
+  loading: boolean;
+}) {
+  return (
+    <div className="border rounded-lg p-4 bg-white shadow-sm">
+      <div className="flex items-start justify-between gap-4">
+        <div className="flex-1">
+          <h3 className="font-semibold text-gray-900">{title}</h3>
+          <p className="text-sm text-gray-600 mt-0.5">{description}</p>
+        </div>
+        <Button onClick={onRun} disabled={loading} size="sm" variant="outline">
+          {loading ? 'Running…' : 'Run'}
+        </Button>
+      </div>
+      <ResultPanel result={result} />
+    </div>
+  );
+}
+
+async function call(method: 'GET' | 'POST', params: Record<string, string>, body?: object) {
+  if (method === 'GET') {
+    const qs = new URLSearchParams(params).toString();
+    const res = await fetch(`${API}?${qs}`);
+    return res.json();
+  }
+  const res = await fetch(API, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  return res.json();
+}
+
+export default function AppFileServerPage() {
+  const [results, setResults] = useState<Record<number, ScenarioResult | null>>({});
+  const [loading, setLoading] = useState<Record<number, boolean>>({});
+
+  function setResult(index: number, result: ScenarioResult) {
+    setResults((prev) => ({ ...prev, [index]: result }));
+  }
+
+  async function run(index: number, fn: () => Promise<ScenarioResult>) {
+    setLoading((prev) => ({ ...prev, [index]: true }));
+    try {
+      const result = await fn();
+      setResult(index, result);
+    } finally {
+      setLoading((prev) => ({ ...prev, [index]: false }));
+    }
+  }
+
+  const scenarios: { title: string; description: string; fn: () => Promise<ScenarioResult> }[] = [
+    {
+      title: '1. Probe',
+      description: 'Checks the provider root directory is writable. Expects { ok: true }.',
+      fn: async () => {
+        const json = await call('GET', { action: 'probe' });
+        return { label: 'probe()', success: json.success, data: json.data, error: json.error, errorType: json.errorType };
+      },
+    },
+    {
+      title: '2. Put',
+      description: `Writes "${FILE_CONTENT}" to ${FILE_PATH}. Expects provider=app_file_server, size=19.`,
+      fn: async () => {
+        const json = await call('POST', {}, { action: 'put', path: FILE_PATH, content: FILE_CONTENT });
+        return { label: 'put()', success: json.success, data: json.data, error: json.error, errorType: json.errorType };
+      },
+    },
+    {
+      title: '3. Exists (true)',
+      description: `Checks ${FILE_PATH} exists after put. Expects { exists: true }.`,
+      fn: async () => {
+        const json = await call('GET', { action: 'exists', path: FILE_PATH });
+        return { label: 'exists() → true', success: json.success && json.data?.exists === true, data: json.data, error: json.error, errorType: json.errorType };
+      },
+    },
+    {
+      title: '4. Get',
+      description: `Reads ${FILE_PATH} back. Expects content="${FILE_CONTENT}".`,
+      fn: async () => {
+        const json = await call('GET', { action: 'get', path: FILE_PATH });
+        const correct = json.data?.content === FILE_CONTENT;
+        return { label: 'get()', success: json.success && correct, data: json.data, error: json.error, errorType: json.errorType };
+      },
+    },
+    {
+      title: '5. Signed URL',
+      description: `Generates a 60-second HMAC-signed URL for ${FILE_PATH}. Click the link in the result to open the raw file.`,
+      fn: async () => {
+        const json = await call('GET', { action: 'sign', path: FILE_PATH, ttl: '60' });
+        return {
+          label: 'getSignedUrl()',
+          success: json.success,
+          data: json.data,
+          error: json.error,
+          errorType: json.errorType,
+          signedUrl: json.data?.url,
+        };
+      },
+    },
+    {
+      title: '6. ifNotExists collision',
+      description: `Tries to put to ${FILE_PATH} again with ifNotExists=true. Expects an error matching /exists/.`,
+      fn: async () => {
+        const json = await call('POST', {}, { action: 'put', path: FILE_PATH, content: 'y', ifNotExists: true });
+        const isCollision = !json.success && /exists/i.test(json.error ?? '');
+        return {
+          label: 'put() ifNotExists collision',
+          success: isCollision,
+          data: isCollision ? { expected_error: json.error } : json.data,
+          error: isCollision ? undefined : `Expected collision error, got: ${json.error ?? 'success'}`,
+          errorType: json.errorType,
+        };
+      },
+    },
+    {
+      title: '7. Delete',
+      description: `Deletes ${FILE_PATH}. Expects { deleted: true }.`,
+      fn: async () => {
+        const json = await call('POST', {}, { action: 'delete', path: FILE_PATH });
+        return { label: 'delete()', success: json.success, data: json.data, error: json.error, errorType: json.errorType };
+      },
+    },
+    {
+      title: '8. Exists (false)',
+      description: `Confirms ${FILE_PATH} is gone after delete. Expects { exists: false }.`,
+      fn: async () => {
+        const json = await call('GET', { action: 'exists', path: FILE_PATH });
+        return { label: 'exists() → false', success: json.success && json.data?.exists === false, data: json.data, error: json.error, errorType: json.errorType };
+      },
+    },
+  ];
+
+  return (
+    <div className="p-8 max-w-3xl mx-auto">
+      <div className="flex items-center gap-3 mb-2">
+        <Server className="h-7 w-7 text-primary" />
+        <h1 className="text-2xl font-bold">App File Server Provider</h1>
+      </div>
+      <p className="text-muted-foreground mb-6 text-sm">
+        Exercises the <code className="bg-muted px-1 rounded text-xs">AppFileServerProvider</code> v2 interface end-to-end.
+        Run scenarios 1–8 in order — they share the test file path{' '}
+        <code className="bg-muted px-1 rounded text-xs">{FILE_PATH}</code>.
+      </p>
+
+      <div className="space-y-3">
+        {scenarios.map((s, i) => (
+          <ScenarioCard
+            key={i}
+            title={s.title}
+            description={s.description}
+            onRun={() => run(i, s.fn)}
+            result={results[i] ?? null}
+            loading={loading[i] ?? false}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+- [ ] **Step 2: Verify TypeScript**
+
+```bash
+cd /Users/pubs/Local/01.code/00.lib/hazo_files/test-app
+npx tsc --noEmit 2>&1 | grep "app-file-server"
+```
+
+Expected: no output.
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd /Users/pubs/Local/01.code/00.lib/hazo_files
+git add test-app/app/providers/app-file-server/page.tsx
+git commit -m "feat(test-app): AppFileServerProvider scenario page"
+```
+
+---
+
+## Task 6: Stub pages for InMemoryProvider and GoogleDriveProvider
+
+**Files:**
+- Create: `test-app/app/providers/in-memory/page.tsx`
+- Create: `test-app/app/providers/gdrive/page.tsx`
+
+Static pages — no API calls. Display the `FileStorageProvider` interface contract plus a "coming soon" badge.
+
+- [ ] **Step 1: Create stub pages**
+
+```bash
+mkdir -p /Users/pubs/Local/01.code/00.lib/hazo_files/test-app/app/providers/in-memory
+mkdir -p /Users/pubs/Local/01.code/00.lib/hazo_files/test-app/app/providers/gdrive
+```
+
+Create `test-app/app/providers/in-memory/page.tsx`:
+
+```tsx
+import React from 'react';
+import { MemoryStick } from 'lucide-react';
+
+const INTERFACE = `interface FileStorageProvider {
+  put(path, body, opts?): Promise<PutResult>
+  get(path): Promise<Buffer | Readable>
+  delete(path): Promise<void>
+  exists(path): Promise<boolean>
+  getSignedUrl(path, opts?): Promise<string>
+  probe(): Promise<ProbeResult>
+}`;
+
+export default function InMemoryPage() {
+  return (
+    <div className="p-8 max-w-2xl mx-auto">
+      <div className="flex items-center gap-3 mb-2">
+        <MemoryStick className="h-7 w-7 text-primary" />
+        <h1 className="text-2xl font-bold">InMemoryProvider</h1>
+        <span className="ml-2 px-2 py-0.5 rounded-full bg-amber-100 text-amber-800 text-xs font-medium">
+          Coming soon — Task 4.4
+        </span>
+      </div>
+      <p className="text-muted-foreground text-sm mb-6">
+        An in-memory implementation of <code className="bg-muted px-1 rounded text-xs">FileStorageProvider</code> for
+        use in tests and CI. Registered behind the <code className="bg-muted px-1 rounded text-xs">STORAGE_TEST_MODE=1</code> environment variable.
+      </p>
+      <div className="border rounded-lg p-4 bg-muted/30">
+        <p className="text-xs font-semibold text-muted-foreground uppercase tracking-wider mb-2">
+          FileStorageProvider interface
+        </p>
+        <pre className="text-xs font-mono text-foreground whitespace-pre">{INTERFACE}</pre>
+      </div>
+    </div>
+  );
+}
+```
+
+Create `test-app/app/providers/gdrive/page.tsx`:
+
+```tsx
+import React from 'react';
+import { Cloud } from 'lucide-react';
+
+const INTERFACE = `interface FileStorageProvider {
+  put(path, body, opts?): Promise<PutResult>
+  get(path): Promise<Buffer | Readable>
+  delete(path): Promise<void>
+  exists(path): Promise<boolean>
+  getSignedUrl(path, opts?): Promise<string>
+  probe(): Promise<ProbeResult>
+}`;
+
+export default function GDriveProviderPage() {
+  return (
+    <div className="p-8 max-w-2xl mx-auto">
+      <div className="flex items-center gap-3 mb-2">
+        <Cloud className="h-7 w-7 text-primary" />
+        <h1 className="text-2xl font-bold">GoogleDriveProvider</h1>
+        <span className="ml-2 px-2 py-0.5 rounded-full bg-amber-100 text-amber-800 text-xs font-medium">
+          Coming soon
+        </span>
+      </div>
+      <p className="text-muted-foreground text-sm mb-6">
+        Service-account based Google Drive (Workspace + Shared Drive) implementation of{' '}
+        <code className="bg-muted px-1 rounded text-xs">FileStorageProvider</code>. Requires{' '}
+        <code className="bg-muted px-1 rounded text-xs">GOOGLE_SERVICE_ACCOUNT_JSON</code> (base64 JSON keyfile).
+      </p>
+      <div className="border rounded-lg p-4 bg-muted/30">
+        <p className="text-xs font-semibold text-muted-foreground uppercase tracking-wider mb-2">
+          FileStorageProvider interface
+        </p>
+        <pre className="text-xs font-mono text-foreground whitespace-pre">{INTERFACE}</pre>
+      </div>
+    </div>
+  );
+}
+```
+
+- [ ] **Step 2: Verify TypeScript**
+
+```bash
+cd /Users/pubs/Local/01.code/00.lib/hazo_files/test-app
+npx tsc --noEmit 2>&1 | grep "providers"
+```
+
+Expected: no output.
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd /Users/pubs/Local/01.code/00.lib/hazo_files
+git add test-app/app/providers/
+git commit -m "feat(test-app): stub pages for InMemoryProvider and GoogleDriveProvider"
+```
+
+---
+
+## Task 7: Smoke test in the browser
+
+No automated tests in the test-app. Verify manually.
+
+- [ ] **Step 1: Start the dev server**
+
+```bash
+cd /Users/pubs/Local/01.code/00.lib/hazo_files/test-app
+npm run dev
+```
+
+Expected: server starts on `http://localhost:3000`.
+
+- [ ] **Step 2: Check sidebar**
+
+Open `http://localhost:3000`. Confirm:
+- Sidebar shows `Lifecycle` then a separator with label "v2 Providers"
+- Three new entries below: `App File Server`, `In-Memory`, `GDrive Provider`
+- Collapsed sidebar shows icons with tooltips for all three
+
+- [ ] **Step 3: Run all 8 scenarios on the AppFileServerProvider page**
+
+Navigate to `http://localhost:3000/providers/app-file-server`. Click Run on each scenario in order 1→8.
+
+| # | Expected |
+|---|---|
+| 1 Probe | Green — `{ ok: true }` |
+| 2 Put | Green — `{ provider: "app_file_server", native_id: "provider-test/test.txt", size: 19 }` |
+| 3 Exists (true) | Green — `{ exists: true }` |
+| 4 Get | Green — `{ content: "Hello AppFileServer" }` |
+| 5 Signed URL | Green — URL shown + clickable link opens raw text in new tab |
+| 6 ifNotExists | Green — shows `expected_error: "File exists: ..."` |
+| 7 Delete | Green — `{ deleted: true }` |
+| 8 Exists (false) | Green — `{ exists: false }` |
+
+- [ ] **Step 4: Verify stub pages render**
+
+- `http://localhost:3000/providers/in-memory` — shows MemoryStick icon, "Coming soon — Task 4.4" badge, interface block.
+- `http://localhost:3000/providers/gdrive` — shows Cloud icon, "Coming soon" badge, interface block.
+
+---
+
+## Self-review
+
+**Spec coverage:**
+- ✅ 3 sidebar entries with v2 Providers section label
+- ✅ AppFileServerProvider page with 8 scenario cards (probe, put, exists×2, get, sign, ifNotExists, delete)
+- ✅ Signed URL renders as clickable anchor
+- ✅ `/api/files/serve/[token]/[...path]` route: token verify → 401, file read → 404, serve with Content-Type
+- ✅ Stub pages with interface contract + coming-soon badge
+- ✅ `AppFileServerProvider` exported from `hazo_files/server` (Task 1 prerequisite)
+
+**Placeholder scan:** None found.
+
+**Type consistency:**
+- `ScenarioResult.signedUrl?: string` — added in Task 5 `ResultPanel`, used only in scenario 5.
+- `makeProvider()` helper defined identically in Task 3 route and Task 4 serve route — consistent `root` and `hmac_secret` config.
+- `getMimeType(virtualPath)` from `hazo_files/server` — verified exported in Task 1.