From 72918c7180ceff89b6aaff5843a2f9cad2d1ca7e Mon Sep 17 00:00:00 2001 From: sneak Date: Wed, 23 Sep 2026 07:28:55 +0000 Subject: [PATCH] Bring README and TODO.md in line with the tree on next2 (closes #111) The README layout lists src/library/ and the other source files, the backup layout names failures.json and the optional thumbnails/, "Opening a library" says an empty cache opens with no data when the first refresh fails, and the test time limit is the 90 seconds the Dockerfile sets. The next step in both files is storing live photos (issue 107) instead of a v1.0.0 tag; tagging and releases are sneak's call alone. Model: opus-5-5 --- README.md | 41 +++++++++++++++++++++++++++++++++-------- TODO.md | 14 +++++++++++++- 2 files changed, 46 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 51bf3ef..c974343 100644 --- a/README.md +++ b/README.md @@ -214,11 +214,23 @@ quak/ auth/ login flow (SRP + email OTP + TOTP), key unwrap model/ decrypted Collection, File, Metadata types + decrypt fns download/ streaming file/thumbnail download + decryption + library/ the cache-backed Library: metadata store, read + surface, records, content cache, precache, ML data + and search, request pools backup.ts resilient full-account backup with dedup + metadata-backup.ts + backup-metadata: all decrypted metadata as JSON + mldata-fetch.ts fetch + decrypt per-file ML data + filename.ts safe file names from server metadata errors.ts error types shared across layers retry.ts retry classifier + exponential backoff with jitter thumbnails.ts detect + regenerate missing thumbnails client.ts high-level Client class assembled from the above + cli-commands.ts the CLI's commands as functions returning exit codes + cli-output.ts how the CLI prints a file's title and time + cli-read.ts fresh reads for the CLI's read commands + cli-run.ts run a command, print its error, exit with its code + cli-session.ts read the saved session file back into a Client index.ts public library exports bin/ quak.ts CLI entrypoint (commander.js) @@ -493,8 +505,15 @@ the smallest does not. / -> ../../originals/<fileID>.<ext> (symlink) <name>.json collection metadata + file list + failures.json files that failed and have not yet succeeded ``` +`failures.json` records each failed file with the kind of failure, how many +times it has been tried and when it was last tried. A file leaves it once it +succeeds, or once it is no longer in the library or in the backup's scope. The +library's `lib.backup({ includeThumbnails: true })` also writes +`thumbnails/<fileID>.jpg` beside `originals/`; `quak backup` does not. + A collection's directory and JSON are named after the collection, and a symlink after the file's title, both with unsafe characters replaced. When two collections would get the same name, or two files in one collection the same @@ -536,7 +555,12 @@ temporary file's permissions, not those of the file it replaced. errors - [x] Update the API reference section below to match the current implementation - [x] `make docker` green -- [ ] Tag `v1.0.0` +- [ ] Store live photos in a form a photo viewer can open + (https://git.eeqj.de/sneak/quak/issues/107), once sneak has chosen between + keeping the ZIP and unpacking it + +Tagging and releases are decided by sneak alone, and happen only when he +declares one. Future (desktop client, separate repo): @@ -556,10 +580,11 @@ test suite is the canonical, executable documentation — `test/library/` and ### Opening a library `Library.open(options)` loads the on-disk cache, starts the background refresh -loop, and resolves to a `Library`. On an empty cache it awaits the first refresh -so it never opens onto empty data; on an existing cache it returns immediately -and refreshes in the background, so an unreachable server does not block -opening. +loop, and resolves to a `Library`. On an empty cache it awaits the first +refresh, so it opens onto the account's data whenever the server is reachable; +if that refresh fails, it opens with no data and records the error in +`lib.status()`. On an existing cache it returns immediately and refreshes in the +background, so an unreachable server does not block opening. `LibraryOptions`: @@ -774,9 +799,9 @@ documents: - **Formatting:** prettier with 4-space indents and `proseWrap: always` for markdown. Use `make fmt` to format. Use `yarn` not `npm`. -- **Testing:** vitest. Tests go in `test/` mirroring the `src/` structure. - `make test` must complete in under 20 seconds. Use `mkdtempSync` for temporary - directories, never manual timestamp paths. +- **Testing:** vitest. Tests go in `test/` mirroring the `src/` structure. The + `test` phase of the `Dockerfile` stops the suite after 90 seconds. Use + `mkdtempSync` for temporary directories, never manual timestamp paths. - **Code style:** `const` for everything, `let` if reassignment is needed, never `var`. Avoid unnecessary comments. No hand-rolled crypto. The diff --git a/TODO.md b/TODO.md index c3998ac..33bdab6 100644 --- a/TODO.md +++ b/TODO.md @@ -14,10 +14,22 @@ pre-1.0 # Next Step -Tag v1.0.0. +Store live photos in a form a photo viewer can open +(https://git.eeqj.de/sneak/quak/issues/107). This waits on sneak's choice +between keeping the ZIP and unpacking it into the image and the video. + +Tagging and releases are decided by sneak alone, and happen only when he +declares one. # Completed Steps +- 2026-09-23: Brought the README and this file in line with the tree (issue + 111). The layout lists `src/library/` and the other source files, the backup + layout names `failures.json` and the optional `thumbnails/`, "Opening a + library" says what happens when the first refresh fails, the test time limit + is the 90 seconds the `Dockerfile` sets, and "Tag v1.0.0" is no longer listed + as the next step. + - 2026-09-23: Tested `quak login` and `backup-metadata --exif` (issue 110). `loginCommand` takes its login function and its prompts from `CliContext`, and `bin/quak.ts` passes `Client.login` and the terminal prompts. Tests cover a