FileLink-PsiTransfer/AGENTS.md

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.

Thunderbird add-on conventions

This repository is not the only Thunderbird add-on in this workspace. When implementation details are unclear, check the maintainer's primary add-on conventions here:

• https://git.jordanwages.com/wagesj45/Sortana.git

If /tmp/Sortana does not already exist, the agent may clone that repository into /tmp and inspect it for implementation patterns, project structure, and Thunderbird-specific conventions that should also be followed here when they do not conflict with this repository's PsiTransfer-specific rules.

Required source of truth

Before changing PsiTransfer integration behavior:

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

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