# AGENTS.md

## Purpose

This repository is a Thunderbird Manifest V3 Filelink/cloudFile provider scaffold for PsiTransfer. Treat it as an integration-in-progress, not a finished provider.

## Required source of truth

Before changing PsiTransfer integration behavior:

1. Check whether `/tmp/psitransfer` already exists.
2. If it does not exist, clone it:

```bash
git clone https://github.com/psi-4ward/psitransfer.git /tmp/psitransfer
```

3. Use `/tmp/psitransfer` as the primary source of truth for the effective upload/download interface.
4. Use the official Thunderbird docs, especially:
   https://webextension-api.thunderbird.net/en/mv3/cloudFile.html

## Thunderbird library rule

Thunderbird add-ons are strict about how third-party libraries are referenced. Do not load `tus-js-client` or other dependencies from a CDN at runtime.

For this repository:

- Use the vendored local copy at `vendor/tus.js`
- Do not switch background/UI code to `https://cdn.jsdelivr.net/...` references
- If the tus client needs to be updated, download the new bundle into the repository first and record the exact resolved version in docs or commit notes

Current vendored tus client:

- Source URL used: `https://cdn.jsdelivr.net/npm/tus-js-client@latest/dist/tus.js`
- Resolved package version at download time: `4.3.1`
- Local path: `vendor/tus.js`

## Interpretation rules

Distinguish clearly between:

- `tus` standard behavior
- PsiTransfer-specific behavior
- Thunderbird `cloudFile` / Filelink behavior

Do not invent a polished public PsiTransfer API if the code only exposes an internal frontend-facing interface.

When uncertain, cite exact PsiTransfer source files and line ranges in notes or docs. Prefer adding a TODO with file references over guessing behavior.

## Minimal-v1 scope

Preserve a minimal-v1 mindset:

- configure endpoint
- upload
- obtain share URL
- skip delete/rename/reuse if source support is weak

Prefer explicit TODOs over guessed implementations.

## Concrete workflow

1. Inspect `manifest.json` and the existing scaffold under `src/` and `ui/`.
2. Inspect `/tmp/psitransfer` frontend and backend routes.
3. Document the inferred HTTP flow with exact source references.
4. Implement the minimal upload path.
5. Verify the generated share URL and Thunderbird `cloudFile` return shape.
6. Only then add optional delete, reuse, or rename support.

## PsiTransfer-specific notes to verify

- Upload config is exposed from PsiTransfer server-side code, not an external API contract by itself.
- Upload password behavior and bucket password behavior are different concerns.
- `sid` handling may mix PsiTransfer frontend convenience with server upload metadata requirements.
- Bucket locking is part of the upload flow and must not be dropped casually.
- Delete and rename support must not be claimed unless the PsiTransfer source clearly supports them for uploaded items.

## Files to update carefully

- `src/psitransfer/client.js`
- `src/cloudfile/provider.js`
- `src/cloudfile/account-store.js`
- `docs/psitransfer-notes.md`
- `README.md`

## Documentation expectation

If you infer or change transport behavior, update `docs/psitransfer-notes.md` with:

- the exact PsiTransfer files consulted
- the relevant line ranges
- what is confirmed
- what is still unresolved