Google Drive

Build a self-hosted personal file locker called "Vault". Single Node.js service, no framework soup.

Stack, non negotiable:
- Node 20 with Fastify and TypeScript
- SQLite via better-sqlite3 for metadata
- Files stored on local disk under DATA_DIR, sharded by the first two chars of a content hash
- Server rendered HTML with Nunjucks plus a little vanilla JS, no React
- Single admin user, password hash in .env, cookie session

In scope:
- Upload via drag and drop, chunked, resumable, files up to 5 GB, using tus protocol or a simple range based chunk endpoint you write
- Content addressed storage: hash on upload, dedupe identical bytes, keep every version of a path
- Folder tree browsing, rename, move, soft delete with a 30 day trash table and a purge command
- Search on filename, extension, size range, and date, all from SQLite
- Share links: random 22 char token, optional expiry, optional download limit, optional password, served from a read only route that streams with correct Content-Type and range support
- Thumbnails for images and PDF first pages using sharp and pdftoppm if present, skipped gracefully if not
- A "vault backup" CLI command that rsyncs DATA_DIR and dumps the SQLite file, plus a "vault verify" that rehashes everything and reports drift

Out of scope, do not attempt:
- Desktop or mobile sync clients
- Multi user accounts, sharing between accounts, permissions matrices
- Document editing or previews beyond thumbnails
- Any cloud service, telemetry, or analytics

Requirements:
- All config in .env: PORT, DATA_DIR, ADMIN_PASSWORD_HASH, SESSION_SECRET, PUBLIC_BASE_URL
- docker-compose.yml with one service and one named volume
- Integration tests covering chunked upload, resume after interrupt, dedupe, share link expiry, and trash purge
- README that states plainly: this is one disk, it is not a backup, here is the restore drill, run it once a quarter

# AGENTS.md — Build guide for Google Drive

## Project scope
A self-hosted file locker: upload, browse folders, full text search on filenames, and generate expiring public share links from a single box you control.

Catalogue verdict: no. You can absolutely build a file upload page with folders, search, and share links in an afternoon. What you cannot build is durable multi-region storage that has not lost a byte in fifteen years, a sync daemon that survives sleep, flaky wifi, and two machines editing the same folder, and native apps on every platform your family owns. The cost side is brutal too: two terabytes of redundant storage plus egress will run you more than the consumer plan, before you have written a line of code. Add that half the value is not storage at all, it is that everyone you share with already has an account and Docs opens in one click. This is infrastructure wearing a UI, and infrastructure is the part you are paying for.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- A VPS or always-on home machine with disk you actually trust
- S3-compatible object storage or a RAID array plus a real offsite backup
- A domain and TLS cert for share links
- Willingness to test your own restore path before you need it

## Stack and architecture
- Build a self-hosted personal file locker called "Vault". Single Node.js service, no framework soup.
- Content addressed storage: hash on upload, dedupe identical bytes, keep every version of a path.
- Interface for this file sync and sharing workflow: a focused file sync and sharing input, review, and export interface.

## Security and data integrity
- Multi user accounts, sharing between accounts, permissions matrices.
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: Real sync clients on macOS, Windows, iOS, and Android, including offline files and conflict resolution.

## Agent implementation rules
- Project rule, data: Content addressed storage: hash on upload, dedupe identical bytes, keep every version of a path.
- Project rule, behavior: Share links: random 22 char token, optional expiry, optional download limit, optional password, served from a read only route that streams with correct Content-Type and range support.
- Project rule, recovery: Multi user accounts, sharing between accounts, permissions matrices.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this file sync and sharing operation with sample or user-owned data: Share links: random 22 char token, optional expiry, optional download limit, optional password, served from a read only route that streams with correct Content-Type and range support.
- Show a concrete result or export: Share links: random 22 char token, optional expiry, optional download limit, optional password, served from a read only route that streams with correct Content-Type and range support.
- State the practical limit: Real sync clients on macOS, Windows, iOS, and Android, including offline files and conflict resolution.

## Engineering roadmap
1. Phase 1, architecture and data: Build a self-hosted personal file locker called "Vault". Single Node.js service, no framework soup. Content addressed storage: hash on upload, dedupe identical bytes, keep every version of a path.
2. Phase 2, implement: Share links: random 22 char token, optional expiry, optional download limit, optional password, served from a read only route that streams with correct Content-Type and range support.
3. Phase 3, implement: A self-hosted file locker: upload, browse folders, full text search on filenames, and generate expiring public share links from a single box you control.
4. Phase 4, review and output: Cloud file storage with sync clients, sharing links, and the Google Docs suite bolted on. Share links: random 22 char token, optional expiry, optional download limit, optional password, served from a read only route that streams with correct Content-Type and range support.
5. Phase 5, recovery and acceptance: Multi user accounts, sharing between accounts, permissions matrices. Verify this invariant with a saved fixture: An invalid input or interrupted operation must retain the source and show a recoverable state; exported records must reload with the same IDs. State the practical limit: Real sync clients on macOS, Windows, iOS, and Android, including offline files and conflict resolution.

## Paid-product capabilities outside this build
- Real sync clients on macOS, Windows, iOS, and Android, including offline files and conflict resolution
- Google Docs, Sheets, and Slides opening inline with live multiplayer editing
- Durability and availability engineering you will never match, plus versioning and trash that actually works
- Sharing with people who already have accounts, plus granular permissions and audit trails
- OCR and content search inside PDFs and images, and the mobile scanner

## Implementation prompt
Build a self-hosted personal file locker called "Vault". Single Node.js service, no framework soup.

Stack, non negotiable:
- Node 20 with Fastify and TypeScript
- SQLite via better-sqlite3 for metadata
- Files stored on local disk under DATA_DIR, sharded by the first two chars of a content hash
- Server rendered HTML with Nunjucks plus a little vanilla JS, no React
- Single admin user, password hash in .env, cookie session

In scope:
- Upload via drag and drop, chunked, resumable, files up to 5 GB, using tus protocol or a simple range based chunk endpoint you write
- Content addressed storage: hash on upload, dedupe identical bytes, keep every version of a path
- Folder tree browsing, rename, move, soft delete with a 30 day trash table and a purge command
- Search on filename, extension, size range, and date, all from SQLite
- Share links: random 22 char token, optional expiry, optional download limit, optional password, served from a read only route that streams with correct Content-Type and range support
- Thumbnails for images and PDF first pages using sharp and pdftoppm if present, skipped gracefully if not
- A "vault backup" CLI command that rsyncs DATA_DIR and dumps the SQLite file, plus a "vault verify" that rehashes everything and reports drift

Out of scope, do not attempt:
- Desktop or mobile sync clients
- Multi user accounts, sharing between accounts, permissions matrices
- Document editing or previews beyond thumbnails
- Any cloud service, telemetry, or analytics

Requirements:
- All config in .env: PORT, DATA_DIR, ADMIN_PASSWORD_HASH, SESSION_SECRET, PUBLIC_BASE_URL
- docker-compose.yml with one service and one named volume
- Integration tests covering chunked upload, resume after interrupt, dedupe, share link expiry, and trash purge
- README that states plainly: this is one disk, it is not a backup, here is the restore drill, run it once a quarter


## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.