93 lines
3.2 KiB
Markdown
93 lines
3.2 KiB
Markdown
# 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
|