# AI Agent Prompt: Remove Legacy ZIP Download Code ## Context StratoFusion now treats browser-direct downloads as the primary download path: - Chrome/Edge use the File System Access API and write directly to local disk. - Google and Dropbox browser-direct flows already use provider-specific stream/session helpers where needed. - Unsupported browsers are blocked with a clear compatibility message instead of falling back to ZIP. Legacy ZIP download code still exists in both Next.js and `fly-rclone`: - Next.js still exposes `/api/rclone/download` and `/api/rclone/download/events`. - Fly still exposes `/api/download-zip/*`. - The ZIP path still carries a `download_sessions` database table plus download-session persistence code. - ZIP progress still depends on machine-local SSE state, which is one of the remaining blockers to confidently scaling Fly beyond one machine. ## Objective Remove the ZIP download path end-to-end while preserving browser-direct downloads. Target outcomes: 1. Remove legacy ZIP route handlers, constants, tests, and docs 2. Remove ZIP-only persistence (`download_sessions`) from schema and Fly state services 3. Keep browser-direct downloads working for single files, folders, and batch downloads 4. Leave no code path that references `/api/rclone/download` or `/api/download-zip` 5. Update deployment docs/config only after verifying whether any remaining machine-local SSE paths still affect multi-machine readiness ## Constraints - Do not touch browser-direct download flows except where they still reference ZIP defaults/constants. - Do not assume `progressBus` can be deleted wholesale; audit all remaining consumers first. - Do not edit old migrations; add a new migration that drops ZIP-only schema. - Archive historical documentation instead of silently deleting valuable review history. - Treat this as a removal/refactor task, not a redesign of the current browser-direct architecture. --- ## Phase 1: Verification (Required First) ### Step 1: Find the Active ZIP Call Graph Search the repo for every ZIP-related entrypoint and report findings before changing code. Suggested searches: ```bash rg -n "download-zip|/api/rclone/download|DOWNLOAD_EVENTS|DEFAULT_ZIP_FILENAME|MAX_ZIP_SIZE|download_sessions|downloadSessionStore" src fly-rclone public/docs README.md rg -n "isBrowserDownloadCompatible|DOWNLOAD_BROWSER_REQUIREMENTS_MESSAGE|useDownloadRunner" src rg -n "progressBus|EventSource|/api/ops" src fly-rclone ``` Minimum findings to report: - Which UI/hook layer still decides between local/browser mode and ZIP mode. - Which Next.js routes still proxy ZIP behavior. - Which Fly routes/services still implement ZIP assembly or ZIP SSE. - Which schema/service code exists only to support ZIP session persistence. - Which docs still describe ZIP as supported behavior. Important: - Do not assume `DownloadDialog.tsx` contains the bulk of the ZIP logic. In the current repo, much of it lives in `src/hooks/useDownloadRunner.ts`. ### Step 2: Verify Unsupported Browser Behavior Inspect the current browser compatibility path and confirm there is no ZIP fallback. Minimum files to inspect: - `src/hooks/useDownloadRunner.ts`. - `src/lib/download/browser-compat.ts`. - `src/components/DownloadDialog.tsx`. - `src/components/DriveTable.tsx`. Expected result: - Unsupported browsers receive the existing compatibility error message. - The current code exits early instead of invoking ZIP download fallback behavior. Report: - The exact file/function responsible for blocking unsupported browsers. - Whether any dormant ZIP fallback remains reachable from the UI. ### Step 3: Identify the Removal Surface Build a concrete delete/update list before editing. At minimum, audit these files: #### Next.js - `src/app/api/rclone/download/route.ts`. - `src/app/api/rclone/download/events/route.ts`. - `src/hooks/useDownloadRunner.ts`. - `src/constants/download.ts`. - `src/constants/api-endpoints.ts`. - `src/constants/error-messages.ts`. - `src/components/DownloadDialog.tsx`. - `src/components/DriveTable.tsx`. #### Fly - `fly-rclone/src/routes/downloadRoutes.js`. - `fly-rclone/server.js`. - `fly-rclone/src/constants.js`. - `fly-rclone/src/services/downloadSessionStore.js`. - `fly-rclone/src/services/operationStateDb.js`. - `fly-rclone/openapi.json`. - `fly-rclone/src/services/progressBus.js`. #### Database - `src/lib/database/schema/jobs.ts`. - `drizzle/*` migration state. #### Tests/Docs - `src/app/api/rclone/download/route.test.ts`. - `src/constants/__tests__/api-endpoints.test.ts`. - `src/components/__tests__/DownloadDialog.test.tsx`. - ZIP references in `README.md`, `public/docs/FILE_MANAGEMENT.md`, `public/docs/TESTING.md`, `public/docs/CODE_REVIEWS.md`, `public/docs/REFACTORING_GUIDES.md`, `public/docs/DEPLOYMENT.md`, `public/docs/RCLONE_SERVICE.md`. Before proceeding, summarize: 1. Files to delete 2. Files to rewrite 3. Files to archive 4. Risks or unknowns, especially around remaining SSE / multi-machine behavior --- ## Phase 2: Code Removal Execute only after verification is complete. ### Step 1: Remove Next.js ZIP API Routes Delete: - `src/app/api/rclone/download/route.ts`. - `src/app/api/rclone/download/events/route.ts`. Then remove all upstream references: - `INTERNAL_API.RCLONE.DOWNLOAD`. - `INTERNAL_API.RCLONE.DOWNLOAD_EVENTS`. - tests that assert those endpoints exist. ### Step 2: Remove ZIP Logic from the Download Runner Primary file: - `src/hooks/useDownloadRunner.ts`. Required changes: - Remove ZIP mode/state and any `DownloadMode` branch that still includes `"zip"`. - Remove `DEFAULT_ZIP_FILENAME` usage and rename the remaining filename/default behavior appropriately. - Preserve browser-direct manifest resolution, folder selection, retries, error reporting, and unsupported browser handling. Secondary audit: - `src/components/DownloadDialog.tsx`. - `src/components/DriveTable.tsx`. Remove only ZIP-specific UI/state. Do not disturb current browser-direct UX. ### Step 3: Remove ZIP Constants and Errors Update: - `src/constants/download.ts`. - `src/constants/error-messages.ts`. Remove ZIP-only constants such as: - `DEFAULT_ZIP_FILENAME`. - `MAX_FILES_PER_ZIP`. - `MAX_ZIP_SIZE_BYTES`. - ZIP-specific method/event/status constants if they are no longer used anywhere. Preserve: - Browser-direct file timeout/retry constants. - Compatibility/error messages still used by browser-direct downloads. ### Step 4: Remove Fly ZIP Handlers Delete: - `fly-rclone/src/routes/downloadRoutes.js`. - `fly-rclone/src/services/downloadSessionStore.js` if it becomes ZIP-only and unused. Update: - `fly-rclone/server.js`. - `fly-rclone/src/constants.js`. - `fly-rclone/openapi.json`. Required changes: - Remove `/api/download-zip`, `/api/download-zip/session`, `/api/download-zip/stream`, and `/api/download-zip/events*`. - Remove any cleanup timer that exists only for ZIP download sessions. - Remove ZIP request/response models from OpenAPI. Important: - `progressBus` is currently shared with other operation-progress flows. Do not delete it unless all remaining consumers are removed or replaced. - If `progressBus` remains because sync/operation SSE still uses it, document that explicitly in the final report. ### Step 5: Remove ZIP Session Persistence Update: - `fly-rclone/src/services/operationStateDb.js`. - `src/lib/database/schema/jobs.ts`. Add a new migration that drops the ZIP-only table: - Drop `download_sessions`. - Remove related indexes. Also remove ZIP-only DB helpers such as: - `createDownloadSession`. - `consumeDownloadSession`. - `deleteDownloadSession`. - `cleanupExpiredDownloadSessions`. Do not touch active operation shared-state code unless it is genuinely ZIP-only. ### Step 6: Remove or Rewrite Tests Delete or rewrite tests that exist only for ZIP behavior, including: - `src/app/api/rclone/download/route.test.ts`. - ZIP-specific assertions in `src/constants/__tests__/api-endpoints.test.ts`. - any Fly ZIP session store tests. Preserve and update tests that still validate browser-direct downloads, dialog UX, or non-ZIP constants. ### Step 7: Update Documentation Update the current docs to reflect one supported download architecture: - `README.md`. - `public/docs/FILE_MANAGEMENT.md`. - `public/docs/TESTING.md`. - `public/docs/DEPLOYMENT.md`. - `public/docs/RCLONE_SERVICE.md`. Archive historical ZIP-specific sections from: - `public/docs/CODE_REVIEWS.md`. - `public/docs/REFACTORING_GUIDES.md`. Archive destination examples: - `public/docs/archive/code-reviews/HYBRID_DOWNLOAD_STRATEGY_2025-01-26.md`. - `public/docs/archive/refactoring/HYBRID_DOWNLOAD_REFACTORING_2025-01-26.md`. ### Step 8: Reassess Multi-Machine Readiness Before Changing Fly Scaling Do not automatically claim “multi-machine is now safe” just because ZIP is removed. Before changing `fly-rclone/fly.prod.toml`, explicitly verify: - whether any remaining machine-local SSE path still depends on `progressBus`. - whether `/api/ops` or any equivalent operation-progress stream still has same-machine assumptions. - whether polling fallback alone is considered sufficient for production readiness. Only if that audit passes: - update `fly-rclone/fly.prod.toml`. - update `fly-rclone/README.md`. - update `public/docs/DEPLOYMENT.md`. - update `public/docs/RCLONE_SERVICE.md`. If the audit does **not** pass: - keep the scaling policy conservative. - remove ZIP references anyway. - document the real remaining blocker accurately. --- ## Phase 3: Verification After Removal ### Step 1: Type Check ```bash pnpm typecheck ``` ### Step 2: Verify Fly Service ```bash pnpm --dir fly-rclone exec jest --runInBand node --check fly-rclone/server.js node --check fly-rclone/src/routes/syncRoutes.js ``` If `progressBus` or operation SSE code was touched, run any directly related tests too. ### Step 3: Verify ZIP References Are Gone from Active Code Run: ```bash rg -n "download-zip|/api/rclone/download|DEFAULT_ZIP_FILENAME|MAX_ZIP_SIZE|download_sessions|downloadSessionStore" src fly-rclone README.md public/docs ``` Expected result: - no active code references remain. - historical archive docs may still contain ZIP references. ### Step 4: Manual Product Verification ```bash pnpm dev ``` Manual checks: 1. Download a single file in a supported browser 2. Download multiple files in a supported browser 3. Download a folder in a supported browser 4. Verify folder picker / local destination flow still works 5. Verify unsupported browsers receive the existing compatibility message 6. Verify no client request hits `/api/rclone/download` If relevant, also verify direct Google/Dropbox stream exceptions still work. --- ## Phase 4: Deployment ### Step 1: Deploy to Development Deploy dev in the environment-specific way already documented in the repo. Verify: - app health. - browser-direct download flow. - no runtime references to removed ZIP endpoints. ### Step 2: Re-check Multi-Machine Assumptions in Development If you concluded ZIP was the final blocker, validate that claim in development before changing production scaling. Suggested checks: - scale Fly dev to 2 machines. - run an operation end-to-end. - verify polling, cancellation, and any live progress UI behave acceptably. ### Step 3: Promote to Production Carefully Only after dev verification: - deploy the code. - update scaling policy if the audit supports it. - monitor logs for missing route hits, stale docs, or client regressions. --- ## Success Criteria - ZIP download routes are removed from Next.js and Fly. - ZIP-only DB schema and helpers are removed with a forward migration. - No active code references `/api/rclone/download` or `/api/download-zip`. - Browser-direct downloads continue working. - Unsupported browsers still fail with the intended compatibility message. - Docs describe browser-direct downloads as the only supported download path. - Multi-machine deployment docs accurately describe the true remaining state instead of assuming ZIP was the only blocker. --- ## Rollback Plan If removal causes regressions: 1. Revert the removal commit 2. Redeploy Vercel and Fly to the prior working release 3. Re-apply the previous Fly scaling policy if it was changed 4. Restore the DB state via a forward follow-up migration if schema removal already shipped --- ## Notes for the Agent - Report Phase 1 findings before changing code. - Prefer deleting dead code over feature-flagging it. - Be explicit when a file is only partially ZIP-related. - Do not over-remove shared infrastructure just because ZIP used it. - If you discover that a “legacy” ZIP surface is still active in production, stop and report that before deleting it.