lucasw89/STTracker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'feat/phase1' into task/8

Browse Source 
# Conflicts:
#	docs/ARCHITECTURE.md
#	docs/DECISIONS.md
#	docs/TODO.md
This commit is contained in:
Lucas Winther
2026-10-30 20:35:25 +01:00
parent 1975e971f9 c8ce107f73
commit b2e6e1948b
8 changed files with 873 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DECISIONS.md
+26
View File
@@ -52,6 +52,32 @@ are the mechanics a maintainer would otherwise reverse-engineer.
**Consequences:** `list` records are snapshotted but not applied, and removal of a de-duplicated engagement
deletes it even if another source still reports it (both in `docs/TODO.md`).
## 2026-10-30: Export format `sttracker-export/v1`: per-user zip, camelCase JSONL, deleted rows included, no secrets
**Status:** accepted
**Context:** Task 15 (`packages/core/src/{export,backup}.ts`) fixed the on-disk bundle format that backups and restore share.
**Decision:**
- **Files.** A zip (`fflate`) holding `manifest.json` (`{ format, exportedAt, user: { username, displayName } }`),
`works.jsonl`, `entries.jsonl`, `engagements.jsonl`, `listens.jsonl`, `lists.jsonl` (items nested),
`copies.jsonl`, `custom_fields.jsonl` (field definitions), `history.jsonl`, `attachments.jsonl` (links nested)
and `attachments/<sha256>` bytes. One JSON object per line, `\n` separated.
- **Keys.** camelCase; JSON columns are parsed into real JSON; `favorite` is a boolean. `user_id` columns are omitted
(the importing user owns everything). `works.jsonl` adds `private` and `externalIds`.
- **Deleted rows are included** with their `deletedAt`, and `fieldSources`/timestamps are kept, so a restore is lossless.
- **No secrets.** No users row beyond username/display name, no sessions, tokens, connections, credentials or source snapshots.
- **Merges and aliases.** `works.jsonl` rows carry `mergedIntoId` (the survivor and ancestors are exported too) and
`work_aliases.jsonl` holds the user's `{ fromWorkId, toWorkId }` rows. Both are additive to v1. Restore re-creates
tombstones (for works it creates) and aliases, so a later write to the old work still resolves to the moved entry.
- **Export is one snapshot:** all reads run in a single transaction (repeatable read on Postgres).
- **Restore** (`importUserBundle`) needs an account with no entries (`account_not_empty`) and `format === "sttracker-export/v1"`
(`unsupported_format`). Works with external IDs are re-matched (else created shared); works without become private.
Ids are remapped (UUIDs inside history `before`/`after` and custom-field value keys too). Rows are inserted directly, so no
new history is written. The import validates first (attachment mime/size/sha256, rating 0-100, status, visibility, 2 GB
uncompressed cap) and writes all rows, attachments included, in one transaction; errors are
`invalid_attachment`, `corrupt_bundle`, `bundle_too_large`, `conflict`. Works merged away at export time are exported as the tombstone row without `mergedIntoId`.
- **Backups** write `<dataDir>/backups/<ISO with ':'->'-'>/<username>.zip` per user plus `sttracker.db` (`VACUUM INTO`, SQLite only),
are built in `<stamp>.tmp` then renamed (modes 0700/0600), and prune to the newest `keep` (default 14).
**Consequences:** Any change to these files after release needs `v2` and a migration path for old bundles.
## 2026-10-30: User layer: per-user moves merge entries, keep aliases, and roll the library up by hierarchy
**Status:** accepted
**Context:** Task 6 built the user layer (`packages/core/src/{entries,engagements,history,lists,copies}.ts`).