diff --git a/README.md b/README.md index 828f0cb..a72c918 100644 --- a/README.md +++ b/README.md @@ -18,9 +18,20 @@ The final command reports the HTML, text, JSON, overview image, and reading-pane Public reading is the default. Standard `bsky.app/profile//post/` URLs and AT URIs are accepted; handles are resolved to DIDs. The four real conversations used for visual acceptance are listed in `docs/examples.json`. +The home/following timeline is explicitly authenticated: + +```sh +bun run perch following --auth # newest page, default limit 20 +bun run perch following --auth --limit 40 # explicit range: 1..100 +bun run perch more --auth # next opaque-cursor page +bun run perch refresh --auth # a new newest page +``` + +Each page is a separate immutable view rather than an ever-growing feed. `more` retains the page limit unless overridden and refuses a missing, changed-account, changed-service, or unchanged continuation cursor without moving the session. `refresh` never reuses the page cursor. The feed preserves source order and repeated occurrences of the same post; it does not claim to reproduce a phone client ranking or the whole network. + ## Read, inspect, move, return -References printed by a view look like `v1-p1`, `v1-a1`, or `v1-m1`. Use the refs in your actual output, not a ref from an unrelated database. +References printed by a view look like `v1-p1`, `v1-a1`, or `v1-m1`; following-feed occurrences use `v1-e1`. Use the refs in your actual output, not a ref from an unrelated database. Opening an `e` ref reads that occurrence's canonical thread and retains a breadcrumb to the exact source page, occurrence, and feed reason. Opening its separate `p` ref remains the ordinary canonical-post operation. ```sh bun run perch show @@ -34,9 +45,9 @@ bun run perch sessions ``` - `peek` returns an exact typed target without fetching or moving. -- `open` fetches post/profile targets. Link, tag, and media refs open a local target-inspection view, not an article, search, or video player. Its exact destination can be passed to a separate browser/read tool. -- `back` restores the exact previous snapshot without fetching it again. -- `refresh` fetches the current canonical post or profile into a new view; it does not re-resolve a possibly reassigned original handle. +- `open` fetches post/profile targets and feed occurrences. Link, tag, and media refs open a local target-inspection view, not an article, search, or video player. Its exact destination can be passed to a separate browser/read tool. +- `back` restores the exact previous snapshot and its original refs without fetching it again. +- `refresh` fetches the current canonical post or profile into a new view; it does not re-resolve a possibly reassigned original handle. On a following feed it requires `--auth` and fetches a new newest page. - `fork` copies the current position and history. Subsequent movement is independent. The source session does not change. - `show`, `peek`, `render`, and `sessions` do not move the reading position or mark anything externally seen. @@ -52,7 +63,7 @@ bun run perch render --out .perch/reading --json The standard thread API is bounded, not a guarantee of the complete conversation. Perch keeps source sibling order and distinguishes local node omission from unknown remote coverage. It preserves available parent/root identities and explicit blocked/not-found/unsupported states without inventing why a post is unavailable. Missing counts are not zero. Quotes are not reply ancestors. Each snapshot carries one reference time, separate creation/indexing times, the service used, and its viewing mode. -Source text and UTF-8 facet offsets are preserved; facet destinations come from the record, not regexes over displayed text. Images and alt text retain their owning post. Video is reported as available with a poster where supplied; capture does not play it. Custom labeler/pronoun hydration, feeds/search/notifications, arbitrary article bodies, and social actions are outside this first reader. +Source text and UTF-8 facet offsets are preserved; facet destinations come from the record, not regexes over displayed text. Images and alt text retain their owning post. Video is reported as available with a poster where supplied; capture does not play it. Custom labeler/pronoun hydration, custom feeds, search, notifications, arbitrary article bodies, and social actions remain outside this reader. PNG/HTML is a reading surface, not a replacement for the exact record. HTML escapes source content and disables scripts. Capture only retrieves direct HTTPS image responses from `cdn.bsky.app`; other origins, credentials in image URLs, and redirects are blocked, with missing-media cues. Public source content remains untrusted even when rendered into pixels. diff --git a/docs/FOLLOWING-ACCEPTANCE.md b/docs/FOLLOWING-ACCEPTANCE.md new file mode 100644 index 0000000..066b863 --- /dev/null +++ b/docs/FOLLOWING-ACCEPTANCE.md @@ -0,0 +1,75 @@ +# Following-feed acceptance — 2026-09-05 + +The feature in `FOLLOWING.md` was exercised through real authenticated timeline reads, the actual CLI, immutable SQLite reading positions, browser-produced PNGs, independent raw-source comparisons, and focused regressions. This extends the first delivery at `eb02964`; it does not replace the thread reader or add social writes. + +## Final integrated checks + +Run from the repository: + +```sh +bun test +bun run typecheck +``` + +Final result: **47 tests passed, 0 failed, 546 assertions across nine files; strict TypeScript checking passed.** The first integrated compiler run exposed two missing discriminant/optional-value narrowings; Core fixed them and the final checks were rerun. The final CSS reference-contrast repair is included in these results. Sols ran only their owned targeted tests; Main ran the integrated suite and typecheck after source barriers settled. + +## Requirement evidence + +| Contract | Exercised behavior | +| --- | --- | +| F1 | Real `following --auth --limit 20` returned an authenticated Liv-view snapshot. Missing `--auth` failed without moving the existing position. Focused tests cover public-reader rejection, valid bounds, invalid bounds before requests, and unusable login credentials. | +| F2 | The raw API specimen requested 20 and returned 19 entries. Main independently compared all 19 normalized occurrences against original source order, canonical post URI, exact text including empty text, repost actor/reason, parent URI, and likes/reposts/replies. Duplicate occurrences, root/parent hydration, raw quotes, unknown counts/reasons, malformed records/media and the primary-first 600-node cap have focused coverage. | +| F3 | Main forked a feed, opened a repost occurrence into its real thread, and checked exact origin view/occurrence/post/repost attribution in the encounter breadcrumb. The parent session remained unchanged. `back` returned byte-identical original JSON; local occurrence `peek` remained stable. Ordinary shared links did not fabricate encounter metadata. | +| F4 | Real `more --auth` used the original opaque cursor, produced a separate 18-entry page, and retained the old occurrence ref. `back` restored the original page. `refresh --auth --limit 7` produced a newest page with no request cursor; back again restored the original. Tests cover no-cursor/no-request, unchanged-cursor rejection, failures, stale CAS, and viewer/service mismatch before timeline continuation. | +| F5 | Actual reply-heavy timelines were rendered and inspected at native reading scale, not just synthetic cards. People and post bodies lead; parent/quote context is shallow, images remain contained and uncropped, media-only posts do not acquire an empty-text warning box, and long original text is explicitly recoverable from disclosure/text/JSON. | +| F6 | The original specimen included Andrea reposting Damon Young's tablet-mail post at 3,327 likes, 920 reposts and 87 replies. Later polls included another image repost with 936 likes and 131 reposts. Compact visible engagement retained these differences without sorting or enlarging popular cards. Exact counts remain in the paired source. | +| F7 | Repeated real mixed feeds rendered approximately 3–5 complete cards per panel, with 20 entries across five panels in two later samples. Main independently measured 20px post body and 16px context-glimpse text in Chromium, zero horizontal overflow, no initially open disclosures, and no computed uppercasing of reference leaves. Repost-reference contrast was separately corrected and verified. | + +### Ordinary Bluesky links + +Main took an actual share URL from a source facet, rather than substituting an AT URI: + +```text +https://bsky.app/profile/thewaether.bsky.social/post/3murkp2raps27 +``` + +`open` selected `at://did:plc:ifcbmerblqzkochthw722ihk/app.bsky.feed.post/3murkp2raps27`, independently identified from the native quoted record. It retained the originally requested URL and returned a public thread with ten nodes. Opening the same URL as a detour from a forked feed and then going back restored the exact feed and refs. Martin can hand Liv an ordinary link in conversation; no AT-URI translation or new harness integration is needed. + +## Independent review and repairs + +Core's independent Luna falsifier rechecked the final source and reported no surviving concrete F1–F4/I1–I4 violation. Concrete repairs were: + +- Error redaction now retains config credentials and every session token observed through the SDK lifecycle, including superseded tokens after refresh. It merges overlapping matches against the original error string rather than destroying longer matches through sequential replacement. A real SDK synthetic 401 → refresh → retried 503 scenario exercises the boundary. +- Empty access/refresh credentials cannot label a request authenticated. The following path checks a usable same-viewer session before dispatch. +- Empty cursors normalize to unavailable with an explicit warning, rather than disagreeing with the renderer about whether `more` is possible. +- Malformed image-array entries produce unsupported-data cues rather than disappearing silently. +- A shared canonical single-record URI boundary rejects extra path segments, reserved record keys, disallowed characters and keys over 512 characters. The small local key guard is grounded in the installed AT Protocol syntax rules; no undeclared dependency or new auth protocol was added. + +Two proposed changes were rejected after checking the installed schemas: absent optional relationship URIs inside a supplied authenticated ViewerState are not the same as missing viewer metadata; and PostView.record must not be blended with a nonstandard shadow value because it looks richer. Valid quote ViewRecord.value follows its own supported path. + +Visual review identified warning overflow and missing hydrated-root disclosure; the renderer now retains that context in its one closed exact-source disclosure without restoring a large visible root card. The first visual falsifier supplied those two findings, then stalled during terminal recheck and was aborted; a fresh bounded read-only Luna independently checked the final root-disclosure, warning-wrap and reference-styling seams and returned a terminal empty finding list. Its evidence is source-only; the actual browser/regression evidence is recorded separately here. Main independently rejected the initial density and caught uppercased context references and low-contrast repost-actor references. Final contrast verification on the durable feed found all four repost-actor badges using the established light foreground `rgb(255, 250, 240)` on `rgb(23, 33, 43)`, with `text-transform: none`. The corrected capture retained byte-identical source JSON. + +## Durable reading position and artifacts + +The existing default database now has: + +- `main` → `v1`, unchanged burger conversation. +- `clarification` → `v2`, unchanged independent branch, with its original history. +- `following` → `v3`, a newly fetched authenticated feed with 20 occurrences, 43 canonical/context nodes, four repost occurrences and thirteen replies. + +The final durable feed capture is in ignored `.perch/following/`: `v3.html`, `v3.txt`, `v3.json`, `v3-overview.png`, and `v3-panel-01.png` through `v3-panel-05.png`. Main inspected the actual first durable panel and independently verified the final reference repair in Chromium. The harness browser could not navigate the host file URI, so its DOM check loaded the same generated HTML with `page.setContent`; Perch's own Playwright capture produced the actual PNGs normally. + +Additional ignored evidence includes `.perch/following-specimen.json`, `.perch/following-source-comparison.json`, `.perch/following-acceptance-1788624919513.sqlite`, and the Visual lead's fresh captures under `.perch/feed-visual-fresh/panels-final/`. These are local authenticated reading artifacts, not committed fixtures. + +```sh +bun run perch show --session following +bun run perch render --session following --out .perch/following +bun run perch more --auth --session following +bun run perch refresh --auth --session following +``` + +## Boundaries and remaining choices + +No post, like, follow, quote, notification handling, autonomous polling daemon, push, deployment, existing-server change or harness/plugin configuration change was made. Polling during acceptance was deliberate read-only sampling. Remote timeline cursors do not make the changing network transactionally frozen; stored local pages are immutable, and continuation failures are explicit. Counts and relative ages describe their captured page reference, not a live ticker. + +Custom feeds/search, posting surfaces, notification reading, custom pronoun/labeler hydration, arbitrary article bodies, authentication caching and a Liv-oriented reader-agent definition remain separate choices. No universal visual-perception benchmark or complete-network/thread guarantee is claimed. diff --git a/docs/FOLLOWING.md b/docs/FOLLOWING.md new file mode 100644 index 0000000..f126140 --- /dev/null +++ b/docs/FOLLOWING.md @@ -0,0 +1,96 @@ +# Following feed — delivery contract v1 + +## Intent + +Martin asked Liv to build her following-feed reader after accepting the compact, content-first design. This is breadth before depth: enough original speech, imagery and social context for something to catch, then deliberate entry into the existing conversation reader. Martin corrected the initial design: likes/reposts/replies are useful signs of an opportunity to join or share a conversation and must remain visible, not buried. They do not reorder the feed. Liv owns this architecture and final visual acceptance. + +## Required behavior + +- F1: `following --auth [--limit N]` obtains the authenticated home/following timeline using the installed ATproto client and existing credential loader. Default limit 20, explicit range 1..100. Public Reader instances reject following reads; CLI refuses missing --auth before a request. Never invent an unauthenticated following feed. Store an immutable `FeedSnapshot` and source viewer/service/reference time, preserving source entry order. +- F2: Feed occurrences and posts are distinct. Preserve every returned feed occurrence, including the same underlying post surfaced more than once. Each occurrence has its own page-local ID and view-qualified `e` reference. Preserve source repost attribution/actor/time, pin reasons, unknown reason type cues, and supplied reply parent/root identities and hydrated nodes. Do not imply every author was followed directly. Retain exact post text/facets/media/quotes/cards/counts using existing normalization, not the lossy MCP formatter. Account for raw unhydrated quote refs as the current adapter does. Missing data remains unknown, not fabricated speech, author, zero, deletion or empty description. +- F3: Opening an occurrence ref enters its post's ordinary thread with an explicit encounter breadcrumb naming the originating feed view/occurrence and its reason; it does not reinterpret a repost as a reply. Opening a plain post ref is still the existing canonical-post operation. `back` returns the exact feed page and refs without a fetch. Peeking an occurrence returns its exact target without navigation or network. Existing fork/CAS/error-preservation invariants apply to feed sessions. +- F4: `more --auth` fetches the current feed page's opaque next cursor as a new bounded immutable page, placing the prior page in back history. It does not append forever into one enormous snapshot. No cursor means an explicit end/unavailable-next-page result without network or movement. Do not invent a cursor, deduplicate away later occurrences, or claim the changing remote timeline is transactionally frozen. `refresh --auth` on a feed fetches a new newest page (no request cursor), preserving the old page and refs. Retain page limit unless overridden. Cursor continuation must reject a different viewer DID or service before fetching the timeline; an unchanged nonempty returned next cursor must not create a silent loop. Failed operations retain the original position. +- F5: A compact single-column visual feed, not mini full-thread dossiers. Small author/avatar, original post body, a modest uncropped media preview, shallow contained quote or parent glimpse when supplied, source reason attribution, a coherent post age and usable occurrence/post/profile refs. Longer text is visibly excerpted in HTML only, with original full text retained in text/JSON/disclosure; never generate prose summaries as replacements. A reply with missing parent text is labeled, not treated as self-contained. Image galleries stay bounded and report omitted previews/counts honestly. Video posters are not playback. Empty feeds and unavailable nodes have clear non-invented surfaces. +- F6: Likes, reposts and replies are always discoverable on the initial feed card in a compact engagement row. Known zero and unknown are distinct; large counts may be abbreviated with exact values available in details/text/JSON. Do not hide these in disclosure, rank posts by them, invent trend/relevance scores or automatic reply suggestions, or make a large number consume more space. A busy conversation is an opportunity cue, not an instruction to engage. +- F7: `show`, JSON output and `render` support feed snapshots through the same existing APIs and produce synchronized text/HTML/JSON/overview/PNG reading panels. Several ordinary feed entries should fit in a readable panel; do not shrink the font or crop media to achieve density. Parent targets roughly 4–7 mixed entries per 1280-wide ~1500-high panel, not a rigid quota. Card boundaries and lowercase exact refs survive screenshots, including long overview warnings. The existing thread/profile/target rendering remains intact; only an encounter breadcrumb is added to a thread opened from a feed occurrence. + +## Shared TypeScript contract + +Core Sol owns additions to `src/model.ts`; Visual Sol consumes these exact names/shapes. Existing types remain compatible; no aliases/shims. Changes outside this contract require Main approval first. + +```ts +export interface FeedReason { + kind: 'repost' | 'pin' | 'unknown'; + by?: Author; + indexedAt?: string; + type?: string; +} +export interface FeedOccurrence { + id: string; // deterministic within this immutable page, e.g. '1'; never an AT URI + postUri: string; + reason?: FeedReason; + parentUri?: string; + rootUri?: string; +} +export interface FeedOptions { + limit?: number; + cursor?: string; +} +export interface FeedSnapshot { + kind: 'feed'; + feed: 'following'; + fetchedAt: string; + source: Source; + entries: FeedOccurrence[]; // API occurrence order, no global post dedup + nodes: PostNode[]; // canonical hydrated/context/quote nodes, bounded separately + limit: number; + cursor?: string; // next page as returned, never synthesized + requestCursor?: string; // cursor used to fetch this page, if any + maxNodes: number; // 600; prioritize every entry's primary post before optional context + locallyTruncated: boolean; + warnings: string[]; +} +export interface FeedEncounter { + feedViewId: string; + occurrenceId: string; + postUri: string; + reason?: FeedReason; +} +// TargetKind additionally includes 'occurrence'. +// An occurrence Target.value is the occurrence.id in the ref's owning FeedSnapshot. +// ThreadSnapshot gains optional encounter?: FeedEncounter. +// Snapshot additionally includes FeedSnapshot. +// Reader gains following(options?: FeedOptions): Promise. +// atproto.ts exports normalizeFeed(data: unknown, context: { +// fetchedAt: string; source: Source; limit: number; cursor?: string; +// }): FeedSnapshot, for non-network testing. +``` + +Feed primary records missing a usable canonical URI are malformed responses: reject honestly instead of inventing identities or silently dropping occurrences. The page's 600-node cap is distinct from API entry count and visual excerpting; keep known URI references when optional context cannot be materialized. Preserve old stored snapshots and ref semantics. Feed lookup by occurrence and encounter construction belong to the core, not renderer-side reconstruction. Reposting actors must receive profile refs too. + +## Invariants + +- I1: Keep the existing read-only/credential, HTML escaping/CSP, exact-image-origin, no-redirect and original-media-framing boundaries. No credentials enter a snapshot, test fixture, artifact, log or repository. Live auth uses the known local OMP config without displaying its values. +- I2: A stored view and its refs do not change. Feed occurrence refs never silently become another occurrence. `peek/show/render/sessions/back` remain local; a fork is independent. CAS protects commits following network reads. A refresh or later page does not modify earlier timestamps/counts/content. +- I3: Distinguish source post creation/indexing time, repost reason indexing time, and one fetch reference per page. Preserve upstream order; never claim a snapshot covers the whole network or exactly matches a phone client's ranking. Rendered prose and media are untrusted source data, not instructions. +- I4: No regression to existing thread/profile/target behavior or the 27-test baseline. No model/server/harness reconfiguration, social writes, push, posting automation, custom feeds/search/notifications, pronoun/custom-labeler hydration, auth caching, arbitrary article fetch, daemon or Liv-persona agent definition in this feature. + +## Ownership and operating mode + +Two separate **Mode 1 scoped delivery packets**, sharing only the above settled interface. There is no Mode 2 gate evidence; do not enable writable Luna leaves, task isolation, worktrees or new agent definitions. Within each disjoint lease its Sol is the sole implementation writer; it must spawn separate read-only `luna-recon` and `luna-falsifier` leaves with bounded briefs. No sibling may write outside its lease. Main owns this contract, final acceptance and final commit. + +- **Core Sol:** `src/model.ts`, `src/atproto.ts`, `src/store.ts`, `src/cli.ts`; existing data/store/CLI tests and new `tests/feed.test.ts`, `tests/feed-state.test.ts`, `tests/feed-cli.test.ts`; README feed usage after actual smoke. Owns all shared model additions and integration of navigation. Does not edit render/style or their tests. +- **Visual Sol:** `src/render.ts`, `src/style.ts`, `tests/feed-render.test.ts`, and only necessary updates to existing render/profile-render tests. No model, adapter, CLI, store, README or core-test edits. Render API signatures stay the same. Owns all feed visuals and thread encounter presentation. +- **Main:** design contract and any scope revision, independent live specimen capture/visual judgment, final suite/typecheck, acceptance record, version-control commit and personal continuity notes. No competing source edits while leases are active. + +## Acceptance evidence and sequencing + +Existing implementation lives in `src/`; first-delivery evidence in `docs/ACCEPTANCE.md`; samples and prior renders in ignored `.perch/`. Existing API private helpers normalize PostNode data, sources, facets, unhydrated quotes and bounded graphs. Existing SQLite store serializes immutable JSON views and CAS revisions. Reuse these patterns; do not create a second representation of the same post merely for the feed. Chromium is installed and capture is working on this workstation. + +Both Sols initially **skip validation/build/test/lint/formatter commands while either source lease is in flight**. Investigate and implement; report source-ready to Main. Then Main releases the validation barrier. Each Sol may run bounded live/local smoke for its own packet, add focused regressions after that behavior works, and run named targeted test files only; Main runs the full suite/typecheck once the combined candidate settles. Do not preallocate housekeeping before smoke. Each Sol must independently falsify its clauses via a new read-only Luna, passing the contract and changed source—not the builder's confidence or test checklist. Incorporate or rebut concrete findings before returning. + +Core evidence must cover real authenticated following retrieval, duplicate-post/different-occurrence preservation, repost/parent metadata, bounds and malformed data, stable occurrence refs, open/back/refresh/more/fork, end-of-feed/no movement, cursor/account scope, and failed/stale navigation preservation. Visual evidence must include actual mixed-feed PNGs, visible small and large engagement counts, shallow reply/quote context, long prose/media boundaries, unknown/empty states, exact paired source and no network/safety regressions. Main will exercise the combined CLI with the actual following feed and inspect at native reading scale. All current views/default positions must remain intact; use separate test sessions/databases. + +## Escalation and delivery receipt + +Architectural ambiguity or an impossible clause goes to Main with evidence; no silent narrowing or invented fallback. OMP runtime defaults supply scheduling; do not run full suites, formatters or linters in a delivery leaf. No commits or pushes by Sol or Luna. Return the contract-led receipt mapping every owned F/I clause to evidence, with changed files, falsifier findings and dispositions, explicit unmet clauses/blockers, and remaining uncertainty. Source-ready is a coordination boundary, not final acceptance. diff --git a/src/atproto.ts b/src/atproto.ts index 82926ed..a873cd6 100644 --- a/src/atproto.ts +++ b/src/atproto.ts @@ -4,6 +4,9 @@ import { homedir } from 'node:os'; import type { Author, Facet, + FeedOptions, + FeedReason, + FeedSnapshot, LinkCard, Media, PostNode, @@ -26,6 +29,8 @@ const DEFAULT_THREAD_OPTIONS: Required = { parentHeight: 40, maxNodes: 60, }; +const DEFAULT_FEED_LIMIT = 20; +const MAX_FEED_NODES = 600; function objectValue(value: unknown): ObjectValue | undefined { return value !== null && typeof value === 'object' && !Array.isArray(value) @@ -45,6 +50,31 @@ function typeName(value: unknown): string | undefined { return stringValue(objectValue(value)?.$type); } +/** ATProto record-key baseline; AtUri parses path segments but does not enforce this grammar. */ +function isValidRecordKey(value: string): boolean { + return value !== '.' && value !== '..' && /^[a-zA-Z0-9_~.:-]{1,512}$/u.test(value); +} + +function canonicalPostRecordUri(value: unknown): string | undefined { + const uri = stringValue(value); + if (!uri?.startsWith('at://')) return undefined; + try { + const parsed = new AtUri(uri); + if ( + !parsed.hostname.startsWith('did:') + || parsed.collection !== 'app.bsky.feed.post' + || !parsed.rkey + || !isValidRecordKey(parsed.rkey) + || parsed.pathname !== `/${parsed.collection}/${parsed.rkey}` + || parsed.search + || parsed.hash + ) return undefined; + return uri; + } catch { + return undefined; + } +} + function unique(values: readonly string[]): string[] { return [...new Set(values)]; } @@ -97,6 +127,45 @@ const timedFetch: typeof fetch = Object.assign( }, ); +function redactSecrets(value: string, secrets: readonly string[]): string { + const needles = unique(secrets.flatMap((secret) => { + if (!secret) return []; + try { + return [secret, encodeURIComponent(secret)]; + } catch { + return [secret]; + } + })).filter((needle) => needle.length > 0); + const spans: Array<{ start: number; end: number }> = []; + for (const needle of needles) { + let searchFrom = 0; + while (searchFrom < value.length) { + const start = value.indexOf(needle, searchFrom); + if (start < 0) break; + spans.push({ start, end: start + needle.length }); + searchFrom = start + 1; + } + } + if (spans.length === 0) return value; + spans.sort((left, right) => left.start - right.start || right.end - left.end); + const merged: Array<{ start: number; end: number }> = []; + for (const span of spans) { + const previous = merged.at(-1); + if (previous && span.start <= previous.end) { + previous.end = Math.max(previous.end, span.end); + } else { + merged.push({ ...span }); + } + } + let redacted = ''; + let copiedThrough = 0; + for (const span of merged) { + redacted += `${value.slice(copiedThrough, span.start)}[redacted]`; + copiedThrough = span.end; + } + return redacted + value.slice(copiedThrough); +} + function sanitizedError( action: string, error: unknown, @@ -107,18 +176,8 @@ function sanitizedError( const status = numberValue(data?.status); let code = safeMessage === undefined ? stringValue(data?.error) : undefined; let message = safeMessage ?? (error instanceof Error ? error.message : String(error)); - for (const secret of secrets) { - if (!secret) continue; - message = message.replaceAll(secret, '[redacted]'); - code = code?.replaceAll(secret, '[redacted]'); - try { - const encodedSecret = encodeURIComponent(secret); - message = message.replaceAll(encodedSecret, '[redacted]'); - code = code?.replaceAll(encodedSecret, '[redacted]'); - } catch { - // encodeURIComponent only fails for malformed surrogate input; the literal was redacted. - } - } + message = redactSecrets(message, secrets); + if (code !== undefined) code = redactSecrets(code, secrets); message = message.replace(/[\r\n\t]+/g, ' ').slice(0, 300).trim(); const detail = [status !== undefined ? `status ${status}` : undefined, code] .filter((part): part is string => Boolean(part)) @@ -439,14 +498,13 @@ function ingestRawQuoteReference(context: NormalizationContext, ownerUri: string : embedType === 'app.bsky.embed.recordWithMedia' ? objectValue(objectValue(embed?.record)?.record) : undefined; - const uri = stringValue(strongRef?.uri); - if (!uri || context.nodes.get(ownerUri)?.quotes.includes(uri)) return; - - try { - if (new AtUri(uri).collection !== 'app.bsky.feed.post') return; - } catch { + if (!strongRef) return; + const uri = canonicalPostRecordUri(strongRef.uri); + if (!uri) { + appendOwnerData(context, ownerUri, { unsupported: [`${embedType ?? 'record-embed'}:invalid-uri`] }); return; } + if (context.nodes.get(ownerUri)?.quotes.includes(uri)) return; appendOwnerData(context, ownerUri, { quotes: [uri] }); const placeholder = unavailableNode({ $type: 'unhydrated-record-reference', @@ -457,18 +515,13 @@ function ingestRawQuoteReference(context: NormalizationContext, ownerUri: string function ingestQuoteRecord(context: NormalizationContext, ownerUri: string, value: unknown): void { const quote = objectValue(value); - const quoteUri = stringValue(quote?.uri); - if (!quote || !quoteUri) { + const rawQuoteUri = stringValue(quote?.uri); + if (!quote || !rawQuoteUri) { appendOwnerData(context, ownerUri, { unsupported: [`${typeName(quote) ?? 'record-embed'}:malformed`] }); return; } - - try { - if (new AtUri(quoteUri).collection !== 'app.bsky.feed.post') { - appendOwnerData(context, ownerUri, { unsupported: [typeName(quote) ?? 'non-post-record-embed'] }); - return; - } - } catch { + const quoteUri = canonicalPostRecordUri(rawQuoteUri); + if (!quoteUri) { appendOwnerData(context, ownerUri, { unsupported: [`${typeName(quote) ?? 'record-embed'}:invalid-uri`] }); return; } @@ -514,9 +567,14 @@ function ingestEmbed(context: NormalizationContext, ownerUri: string, value: unk appendOwnerData(context, ownerUri, { unsupported: [`${embedType}:malformed`] }); return; } - const media = embed.images.map((rawImage): Media | undefined => { + const media: Media[] = []; + const unsupported: string[] = []; + embed.images.forEach((rawImage, index) => { const image = objectValue(rawImage); - if (!image) return undefined; + if (!image) { + unsupported.push(`${embedType}:image-${index + 1}-malformed`); + return; + } const aspect = objectValue(image.aspectRatio); const item: Media = { kind: 'image' }; const url = stringValue(image.fullsize); @@ -529,9 +587,9 @@ function ingestEmbed(context: NormalizationContext, ownerUri: string, value: unk if (alt !== undefined) item.alt = alt; if (width !== undefined) item.width = width; if (height !== undefined) item.height = height; - return item; - }).filter((item): item is Media => item !== undefined); - appendOwnerData(context, ownerUri, { media }); + media.push(item); + }); + appendOwnerData(context, ownerUri, { media, unsupported }); return; } @@ -771,6 +829,205 @@ export function normalizeThread( }; } +function feedReason(value: unknown, warnings: string[], occurrenceId: string): FeedReason | undefined { + if (value === undefined) return undefined; + const raw = objectValue(value); + if (!raw) { + warnings.push(`Feed occurrence ${occurrenceId} supplied a malformed unknown reason.`); + return { kind: 'unknown' }; + } + + const rawType = typeName(raw); + const kind: FeedReason['kind'] = rawType === 'app.bsky.feed.defs#reasonRepost' + ? 'repost' + : rawType === 'app.bsky.feed.defs#reasonPin' + ? 'pin' + : 'unknown'; + const reason: FeedReason = { kind }; + const by = authorFrom(raw.by); + const indexedAt = stringValue(raw.indexedAt); + if (by !== undefined) reason.by = by; + if (indexedAt !== undefined) reason.indexedAt = indexedAt; + if (kind === 'unknown' && rawType !== undefined) reason.type = rawType; + if (raw.by !== undefined && by === undefined) { + warnings.push(`Feed occurrence ${occurrenceId} supplied a reason actor without a usable DID and handle.`); + } + return reason; +} + +function normalizedFeedNode(value: unknown, fallbackUri?: string): { node?: PostNode; warnings: string[] } { + const normalized = availableNode(value); + if (normalized.node) return normalized; + return { node: unavailableNode(value, fallbackUri), warnings: [] }; +} + +function ingestFeedContextPost(context: NormalizationContext, value: unknown): string | undefined { + const uri = canonicalPostRecordUri(objectValue(value)?.uri); + if (!uri) return undefined; + const normalized = normalizedFeedNode(value, uri); + if (!normalized.node || !addNode(context, normalized.node)) return uri; + context.warnings.push(...normalized.warnings); + if (normalized.node.availability === 'available') { + const post = objectValue(value); + if (post?.embed !== undefined) ingestEmbed(context, uri, post.embed); + ingestRawQuoteReference(context, uri, objectValue(post?.record)?.embed); + } + return uri; +} + +/** Losslessly normalizes one source-ordered authenticated timeline page. */ +export function normalizeFeed( + data: unknown, + context: { + fetchedAt: string; + source: Source; + limit: number; + cursor?: string; + }, +): FeedSnapshot { + const requested = boundedFeedOptions({ limit: context.limit, cursor: context.cursor }); + const response = objectValue(data); + if (!response || !Array.isArray(response.feed)) { + throw new Error('Timeline response omitted its feed array'); + } + + const state: NormalizationContext = { + nodes: new Map(), + quoteExpansions: new Map(), + replyExpansions: new Map(), + options: { depth: 0, parentHeight: 0, maxNodes: MAX_FEED_NODES }, + warnings: [], + locallyTruncated: false, + }; + const entries: FeedSnapshot['entries'] = []; + const frames: Array<{ + post: ObjectValue; + postUri: string; + parent?: unknown; + root?: unknown; + parentUri?: string; + rootUri?: string; + }> = []; + + // Admit every distinct primary post before optional context or quote nodes can consume the page cap. + response.feed.forEach((rawEntry, index) => { + const occurrenceId = String(index + 1); + const entry = objectValue(rawEntry); + const post = objectValue(entry?.post); + const postUri = canonicalPostRecordUri(post?.uri); + if (!entry || !post || !postUri) { + throw new Error(`Timeline occurrence ${occurrenceId} omitted a usable canonical post URI`); + } + + const normalized = normalizedFeedNode(post, postUri); + if (!normalized.node) { + throw new Error(`Timeline occurrence ${occurrenceId} could not retain its primary post`); + } + addNode(state, normalized.node); + state.warnings.push(...normalized.warnings); + + const reply = objectValue(entry.reply); + const parent = reply?.parent; + const root = reply?.root; + const suppliedParentUri = canonicalPostRecordUri(objectValue(parent)?.uri); + const suppliedRootUri = canonicalPostRecordUri(objectValue(root)?.uri); + if (parent !== undefined && suppliedParentUri === undefined) { + state.warnings.push(`Feed occurrence ${occurrenceId} supplied parent context without a usable canonical post URI.`); + } + if (root !== undefined && suppliedRootUri === undefined) { + state.warnings.push(`Feed occurrence ${occurrenceId} supplied root context without a usable canonical post URI.`); + } + + const retainedPrimary = state.nodes.get(postUri) ?? normalized.node; + const parentUri = suppliedParentUri ?? retainedPrimary.parentUri; + const rootUri = suppliedRootUri ?? retainedPrimary.rootUri; + const reason = feedReason(entry.reason, state.warnings, occurrenceId); + entries.push({ + id: occurrenceId, + postUri, + ...(reason !== undefined ? { reason } : {}), + ...(parentUri !== undefined ? { parentUri } : {}), + ...(rootUri !== undefined ? { rootUri } : {}), + }); + frames.push({ + post, + postUri, + ...(parent !== undefined ? { parent } : {}), + ...(root !== undefined ? { root } : {}), + ...(parentUri !== undefined ? { parentUri } : {}), + ...(rootUri !== undefined ? { rootUri } : {}), + }); + }); + + for (const frame of frames) { + const primary = state.nodes.get(frame.postUri); + if (primary) { + state.nodes.set(frame.postUri, { + ...primary, + parentUri: primary.parentUri ?? frame.parentUri, + rootUri: primary.rootUri ?? frame.rootUri, + }); + } + + if (frame.parent !== undefined) ingestFeedContextPost(state, frame.parent); + if (frame.root !== undefined) ingestFeedContextPost(state, frame.root); + const parentUri = frame.parentUri; + if (parentUri) { + const parentNode = state.nodes.get(parentUri); + if (parentNode) { + state.nodes.set(parentUri, { + ...parentNode, + replies: unique([...parentNode.replies, frame.postUri]), + }); + } + } + + if (frame.post.embed !== undefined) ingestEmbed(state, frame.postUri, frame.post.embed); + ingestRawQuoteReference(state, frame.postUri, objectValue(frame.post.record)?.embed); + } + + let cursor: string | undefined; + if (typeof response.cursor === 'string' && response.cursor.length > 0) { + cursor = response.cursor; + } else if (response.cursor === '') { + state.warnings.push('Timeline response supplied an empty cursor; continuation is unavailable.'); + } else if (Object.prototype.hasOwnProperty.call(response, 'cursor') && response.cursor !== undefined) { + state.warnings.push('Timeline response supplied a non-string cursor; continuation is unavailable.'); + } + if (state.locallyTruncated) { + state.warnings.push('Local feed maxNodes omitted one or more supplied context or quote nodes.'); + } + + return { + kind: 'feed', + feed: 'following', + fetchedAt: context.fetchedAt, + source: { ...context.source }, + entries, + nodes: [...state.nodes.values()], + limit: requested.limit, + ...(cursor !== undefined ? { cursor } : {}), + ...(requested.cursor !== undefined ? { requestCursor: requested.cursor } : {}), + maxNodes: MAX_FEED_NODES, + locallyTruncated: state.locallyTruncated, + warnings: unique(state.warnings), + }; +} + +function boundedFeedOptions(options: FeedOptions = {}): { limit: number; cursor?: string } { + const limit = options.limit ?? DEFAULT_FEED_LIMIT; + if (!Number.isInteger(limit) || limit < 1 || limit > 100) { + throw new Error('limit must be an integer from 1 through 100'); + } + if (options.cursor !== undefined && (typeof options.cursor !== 'string' || options.cursor.length === 0)) { + throw new Error('cursor must be a nonempty opaque string when supplied'); + } + return { + limit, + ...(options.cursor !== undefined ? { cursor: options.cursor } : {}), + }; +} + function boundedOptions(options: ThreadOptions = {}): Required { const resolved = { depth: options.depth ?? DEFAULT_THREAD_OPTIONS.depth, @@ -800,7 +1057,14 @@ function postInputParts(input: string): { actor: string; rkey: string } { } catch { throw new Error('Post target is not a valid AT URI'); } - if (uri.collection !== 'app.bsky.feed.post' || !uri.rkey || uri.search || uri.hash) { + if ( + uri.collection !== 'app.bsky.feed.post' + || !uri.rkey + || !isValidRecordKey(uri.rkey) + || uri.pathname !== `/${uri.collection}/${uri.rkey}` + || uri.search + || uri.hash + ) { throw new Error('Post AT URI must identify one app.bsky.feed.post record'); } return { @@ -883,7 +1147,11 @@ function profileInputActor(input: string): string { } } -async function canonicalPostUri(agent: BskyAgent, input: string): Promise { +async function canonicalPostUri( + agent: BskyAgent, + input: string, + authenticationSecrets: () => readonly string[], +): Promise { const { actor, rkey } = postInputParts(input); let did = actor; if (!actor.startsWith('did:')) { @@ -891,7 +1159,7 @@ async function canonicalPostUri(agent: BskyAgent, input: string): Promise authenticated ? (options.pds ?? DEFAULT_PDS) : (options.service ?? PUBLIC_SERVICE), authenticated ? 'PDS' : 'service', ); - const agent = new BskyAgent({ service, fetch: timedFetch }); + const secrets: string[] = []; + const agent = new BskyAgent({ + service, + fetch: timedFetch, + persistSession(_event, session) { + if (session?.accessJwt) secrets.push(session.accessJwt); + if (session?.refreshJwt) secrets.push(session.refreshJwt); + }, + }); let source: Source; + const authenticationSecrets = (): string[] => unique([ + ...secrets, + agent.session?.accessJwt, + agent.session?.refreshJwt, + ].filter((value): value is string => typeof value === 'string' && value.length > 0)); if (authConfig !== undefined) { const credentials = await authenticationConfig(authConfig); + secrets.push(credentials.identifier, credentials.password); try { await agent.login({ identifier: credentials.identifier, password: credentials.password }); } catch (error) { throw sanitizedError( 'Authentication', error, - [credentials.identifier, credentials.password], + authenticationSecrets(), 'credentials were rejected or the authentication service was unavailable', ); } - source = Object.freeze({ service, mode: 'authenticated' as const, viewerDid: agent.session?.did }); + const session = agent.session; + if (!session?.did) throw new Error('Authentication response omitted the viewer DID'); + if (!session.accessJwt || !session.refreshJwt) { + throw new Error('Authentication response omitted usable session credentials'); + } + source = Object.freeze({ service, mode: 'authenticated' as const, viewerDid: session.did }); } else { source = Object.freeze({ service, mode: 'public' as const }); } @@ -957,7 +1244,7 @@ export async function createReader(options: ReaderOptions = {}): Promise source, async thread(input: string, threadOptions: ThreadOptions = {}): Promise { const resolvedOptions = boundedOptions(threadOptions); - const focusUri = await canonicalPostUri(agent, input); + const focusUri = await canonicalPostUri(agent, input, authenticationSecrets); try { const response = await agent.getPostThread( { @@ -976,7 +1263,7 @@ export async function createReader(options: ReaderOptions = {}): Promise options: resolvedOptions, }); } catch (error) { - throw sanitizedError(`Fetching thread ${focusUri}`, error); + throw sanitizedError(`Fetching thread ${focusUri}`, error, authenticationSecrets()); } }, async profile(actorInput: string): Promise { @@ -1001,7 +1288,40 @@ export async function createReader(options: ReaderOptions = {}): Promise labels: labelValues(profile.labels), }; } catch (error) { - throw sanitizedError(`Fetching profile ${actor}`, error); + throw sanitizedError(`Fetching profile ${actor}`, error, authenticationSecrets()); + } + }, + async following(feedOptions: FeedOptions = {}): Promise { + if (!authenticated) throw new Error('Following feed requires an authenticated reader'); + const session = agent.session; + if (!session?.accessJwt || !session.refreshJwt || session.did !== source.viewerDid) { + throw new Error('Following feed requires a usable authenticated session'); + } + const resolvedOptions = boundedFeedOptions(feedOptions); + try { + const response = await agent.getTimeline( + { + limit: resolvedOptions.limit, + ...(resolvedOptions.cursor !== undefined ? { cursor: resolvedOptions.cursor } : {}), + }, + { signal: requestSignal() }, + ); + const snapshot = normalizeFeed(response.data, { + fetchedAt: new Date().toISOString(), + source, + limit: resolvedOptions.limit, + ...(resolvedOptions.cursor !== undefined ? { cursor: resolvedOptions.cursor } : {}), + }); + if ( + resolvedOptions.cursor !== undefined + && resolvedOptions.cursor.length > 0 + && snapshot.cursor === resolvedOptions.cursor + ) { + throw new Error('Timeline returned the unchanged continuation cursor; refusing a silent loop'); + } + return snapshot; + } catch (error) { + throw sanitizedError('Fetching following feed', error, authenticationSecrets()); } }, }; diff --git a/src/cli.ts b/src/cli.ts index 64811a3..73d76ca 100755 --- a/src/cli.ts +++ b/src/cli.ts @@ -3,13 +3,24 @@ import { homedir } from 'node:os'; import { resolve } from 'node:path'; import { createReader } from './atproto.ts'; -import type { ReaderOptions, ReadingView, Snapshot, Target, TargetSnapshot, ThreadOptions } from './model.ts'; +import type { + FeedOccurrence, + FeedSnapshot, + ReaderOptions, + ReadingView, + Snapshot, + Target, + TargetSnapshot, + ThreadOptions, +} from './model.ts'; import { captureView, renderText } from './render.ts'; import { ReadingStore } from './store.ts'; const HELP = `Perch — a persistent, read-only Bluesky reader Usage: + perch following --auth [--limit <1..100>] [options] + perch more --auth [--limit <1..100>] [options] perch open [options] perch peek [options] perch show [options] @@ -29,6 +40,7 @@ Common options: --depth <0..100> Reply depth for a thread read (default: 3) --parents <0..100> Parent height for a thread read (default: 40) --max-nodes <1..200> Local thread node limit (default: 60) + --limit <1..100> Following-feed page size (default: 20) --out Output directory for render --help Show this help @@ -37,7 +49,7 @@ sessions, back, fork, and render are local-only and never log in or fetch. Opening link, tag, or media refs records an honest target inspection without fetching the target. Perch has no social write commands.`; -type ValueFlag = 'session' | 'db' | 'auth-config' | 'pds' | 'depth' | 'parents' | 'max-nodes' | 'out'; +type ValueFlag = 'session' | 'db' | 'auth-config' | 'pds' | 'depth' | 'parents' | 'max-nodes' | 'limit' | 'out'; interface ParsedArguments { command?: string; @@ -56,9 +68,17 @@ function expandHome(path: string): string { function parseArguments(argv: string[]): ParsedArguments { const parsed: ParsedArguments = { positionals: [], help: false, json: false, auth: false, values: {} }; - const valueFlags = new Set([ - 'session', 'db', 'auth-config', 'pds', 'depth', 'parents', 'max-nodes', 'out', - ]); + const valueFlags: Record = { + session: true, + db: true, + 'auth-config': true, + pds: true, + depth: true, + parents: true, + 'max-nodes': true, + limit: true, + out: true, + }; for (let index = 0; index < argv.length; index += 1) { const argument = argv[index]; @@ -70,7 +90,7 @@ function parseArguments(argv: string[]): ParsedArguments { parsed.auth = true; } else if (argument.startsWith('--')) { const flag = argument.slice(2) as ValueFlag; - if (!valueFlags.has(flag)) throw new Error(`Unknown option: ${argument}`); + if (valueFlags[flag] !== true) throw new Error(`Unknown option: ${argument}`); const value = argv[index + 1]; if (!value || value.startsWith('--')) throw new Error(`Option ${argument} requires a value.`); parsed.values[flag] = value; @@ -102,6 +122,38 @@ function threadOptions(arguments_: ParsedArguments): ThreadOptions { }; } +function feedLimit(arguments_: ParsedArguments): number | undefined { + return parseBoundedInteger(arguments_.values.limit, '--limit', 1, 100); +} + +function requireFeedAuthentication(arguments_: ParsedArguments, operation: string): void { + if (!arguments_.auth) throw new Error(`${operation} requires explicit --auth.`); +} + +function occurrenceFrom(view: ReadingView, target: Target): FeedOccurrence { + if (target.kind !== 'occurrence' || view.snapshot.kind !== 'feed') { + throw new Error(`Reference ${target.label} is not a feed occurrence.`); + } + const occurrence = view.snapshot.entries.find((entry) => entry.id === target.value); + if (!occurrence) throw new Error(`Feed occurrence ${target.value} is missing from stored view ${view.id}.`); + return occurrence; +} + +function requireMatchingFeedSource(feed: FeedSnapshot, source: Snapshot['source']): void { + if (feed.source.mode !== 'authenticated' || source.mode !== 'authenticated') { + throw new Error('Following-feed network navigation requires authenticated source identities.'); + } + if (feed.source.service !== source.service) { + throw new Error(`Following-feed source service changed from ${feed.source.service} to ${source.service}; refusing network navigation.`); + } + if (!feed.source.viewerDid || !source.viewerDid) { + throw new Error('Following-feed continuation requires both stored and current viewer DIDs.'); + } + if (feed.source.viewerDid !== source.viewerDid) { + throw new Error('Following-feed viewer changed; refusing network navigation.'); + } +} + function readerOptions(arguments_: ParsedArguments): ReaderOptions { if (!arguments_.auth) { if (arguments_.values['auth-config'] || arguments_.values.pds) { @@ -130,7 +182,7 @@ function targetInspection(target: Target, source: Snapshot['source']): TargetSna tag: 'Tag target only; no feed or search was fetched.', media: 'Media target only; no playback or external content was fetched.', }; - if (target.kind === 'post' || target.kind === 'profile') { + if (target.kind === 'post' || target.kind === 'profile' || target.kind === 'occurrence') { throw new Error(`Target ${target.label} requires a network read.`); } return { @@ -162,14 +214,57 @@ export async function runCli(argv: string[] = Bun.argv.slice(2)): Promise return; } - const knownCommands = new Set(['open', 'peek', 'show', 'back', 'refresh', 'fork', 'sessions', 'render']); - if (!knownCommands.has(arguments_.command)) throw new Error(`Unknown command: ${arguments_.command}\n\n${HELP}`); + const knownCommands: Record = { + following: true, + more: true, + open: true, + peek: true, + show: true, + back: true, + refresh: true, + fork: true, + sessions: true, + render: true, + }; + if (knownCommands[arguments_.command] !== true) throw new Error(`Unknown command: ${arguments_.command}\n\n${HELP}`); const sessionName = arguments_.values.session ?? 'main'; const databasePath = expandHome(arguments_.values.db ?? Bun.env.PERCH_DB ?? '~/.local/share/perch/reader.sqlite'); const store = new ReadingStore(databasePath); try { switch (arguments_.command) { + case 'following': { + requireArity(arguments_, 0, 'following --auth [--limit <1..100>] [options]'); + requireFeedAuthentication(arguments_, 'following'); + const limit = feedLimit(arguments_); + const baseline = store.position(sessionName); + const reader = await createReader(readerOptions(arguments_)); + const snapshot = await reader.following({ limit }); + emitView(store.commit(sessionName, snapshot, baseline.revision), arguments_.json); + break; + } + case 'more': { + requireArity(arguments_, 0, 'more --auth [--limit <1..100>] [options]'); + requireFeedAuthentication(arguments_, 'more'); + const requestedLimit = feedLimit(arguments_); + const baseline = store.position(sessionName); + const current = requireCurrent(baseline.view, sessionName); + if (current.snapshot.kind !== 'feed') { + throw new Error('more is only available from a following-feed view.'); + } + const cursor = current.snapshot.cursor; + if (cursor === undefined || cursor.length === 0) { + throw new Error('Current feed page has no next cursor; continuation is unavailable.'); + } + const reader = await createReader(readerOptions(arguments_)); + requireMatchingFeedSource(current.snapshot, reader.source); + const snapshot = await reader.following({ + limit: requestedLimit ?? current.snapshot.limit, + cursor, + }); + emitView(store.commit(sessionName, snapshot, baseline.revision), arguments_.json); + break; + } case 'open': { requireArity(arguments_, 1, 'open [options]'); const input = arguments_.positionals[0]; @@ -183,6 +278,19 @@ export async function runCli(argv: string[] = Bun.argv.slice(2)): Promise } else if (resolvedReference.target.kind === 'profile') { const reader = await createReader(readerOptions(arguments_)); snapshot = await reader.profile(resolvedReference.target.value); + } else if (resolvedReference.target.kind === 'occurrence') { + const occurrence = occurrenceFrom(resolvedReference.view, resolvedReference.target); + const reader = await createReader(readerOptions(arguments_)); + const thread = await reader.thread(occurrence.postUri, threadOptions(arguments_)); + snapshot = { + ...thread, + encounter: { + feedViewId: resolvedReference.view.id, + occurrenceId: occurrence.id, + postUri: occurrence.postUri, + ...(occurrence.reason !== undefined ? { reason: occurrence.reason } : {}), + }, + }; } else { snapshot = targetInspection(resolvedReference.target, resolvedReference.view.snapshot.source); } @@ -219,14 +327,23 @@ export async function runCli(argv: string[] = Bun.argv.slice(2)): Promise if (current.snapshot.kind === 'thread') { const requestedOptions = threadOptions(arguments_); const reader = await createReader(readerOptions(arguments_)); - snapshot = await reader.thread(current.snapshot.focusUri, { + const refreshed = await reader.thread(current.snapshot.focusUri, { depth: requestedOptions.depth ?? current.snapshot.limits.depth, parentHeight: requestedOptions.parentHeight ?? current.snapshot.limits.parentHeight, maxNodes: requestedOptions.maxNodes ?? current.snapshot.limits.maxNodes, }); + snapshot = current.snapshot.encounter + ? { ...refreshed, encounter: current.snapshot.encounter } + : refreshed; } else if (current.snapshot.kind === 'profile') { const reader = await createReader(readerOptions(arguments_)); snapshot = await reader.profile(current.snapshot.author.did); + } else if (current.snapshot.kind === 'feed') { + requireFeedAuthentication(arguments_, 'refreshing a following feed'); + const requestedLimit = feedLimit(arguments_); + const reader = await createReader(readerOptions(arguments_)); + requireMatchingFeedSource(current.snapshot, reader.source); + snapshot = await reader.following({ limit: requestedLimit ?? current.snapshot.limit }); } else { snapshot = targetInspection(current.snapshot.target, current.snapshot.source); } diff --git a/src/model.ts b/src/model.ts index b9b85cf..2464fe6 100644 --- a/src/model.ts +++ b/src/model.ts @@ -13,7 +13,34 @@ export interface Author { followedBy?: boolean; } -export type TargetKind = 'post' | 'profile' | 'link' | 'tag' | 'media'; +export interface FeedReason { + kind: 'repost' | 'pin' | 'unknown'; + by?: Author; + indexedAt?: string; + type?: string; +} + +export interface FeedOccurrence { + id: string; + postUri: string; + reason?: FeedReason; + parentUri?: string; + rootUri?: string; +} + +export interface FeedOptions { + limit?: number; + cursor?: string; +} + +export interface FeedEncounter { + feedViewId: string; + occurrenceId: string; + postUri: string; + reason?: FeedReason; +} + +export type TargetKind = 'post' | 'profile' | 'link' | 'tag' | 'media' | 'occurrence'; export interface Target { kind: TargetKind; value: string; @@ -67,6 +94,21 @@ export interface PostNode { counts: { replies?: number; likes?: number; reposts?: number; quotes?: number }; } +export interface FeedSnapshot { + kind: 'feed'; + feed: 'following'; + fetchedAt: string; + source: Source; + entries: FeedOccurrence[]; + nodes: PostNode[]; + limit: number; + cursor?: string; + requestCursor?: string; + maxNodes: number; + locallyTruncated: boolean; + warnings: string[]; +} + export interface ThreadSnapshot { kind: 'thread'; requested: string; @@ -81,6 +123,7 @@ export interface ThreadSnapshot { /** Local node omission is distinct from unknown remote coverage. */ locallyTruncated: boolean; warnings: string[]; + encounter?: FeedEncounter; } export interface ProfileSnapshot { @@ -103,7 +146,7 @@ export interface TargetSnapshot { note: string; } -export type Snapshot = ThreadSnapshot | ProfileSnapshot | TargetSnapshot; +export type Snapshot = ThreadSnapshot | ProfileSnapshot | TargetSnapshot | FeedSnapshot; export interface ReadingView { /** Monotonically allocated by the local store, never reused. */ id: string; @@ -134,6 +177,7 @@ export interface Reader { readonly source: Source; thread(input: string, options?: ThreadOptions): Promise; profile(actor: string): Promise; + following(options?: FeedOptions): Promise; } export interface RenderFiles { diff --git a/src/render.ts b/src/render.ts index 25492d3..0b3c8af 100644 --- a/src/render.ts +++ b/src/render.ts @@ -6,6 +6,10 @@ import { chromium } from 'playwright'; import type { Author, Facet, + FeedEncounter, + FeedOccurrence, + FeedReason, + FeedSnapshot, LinkCard, Media, PostNode, @@ -37,6 +41,15 @@ const CAPTURE_VIEWPORT_WIDTH = 1280; const CAPTURE_VIEWPORT_HEIGHT = 960; const PANEL_TARGET_HEIGHT = 1600; const PANEL_GUTTER = 16; +const FEED_BODY_EXCERPT_THRESHOLD = 420; +const FEED_GLIMPSE_EXCERPT_THRESHOLD = 120; +const FEED_MEDIA_PREVIEW_LIMIT = 2; +const FEED_QUOTE_PREVIEW_LIMIT = 1; +const FEED_CARD_PREVIEW_LIMIT = 1; +const COMPACT_COUNT_FORMATTER = new Intl.NumberFormat('en', { + notation: 'compact', + maximumFractionDigits: 1, +}); function escapeHtml(value: string): string { return value @@ -383,7 +396,7 @@ function renderQuotedPostHtml( `; } -function renderNodeText(view: ReadingView, snapshot: ThreadSnapshot, context: NodeContext): string { +function renderNodeText(view: ReadingView, snapshot: Pick, context: NodeContext): string { if (context.node === undefined) { return [ `=== ${context.label.toUpperCase()} ===`, @@ -549,6 +562,520 @@ function renderPostHtml( `; } +function renderFeedReasonText(view: ReadingView, reason: FeedReason | undefined, fetchedAt: string): string[] { + if (reason === undefined) return ['Reason kind: ']; + const indexed = describeTimestamp(reason.indexedAt, fetchedAt); + const lines = [ + `Reason kind: ${reason.kind}`, + `Reason type: ${reason.type ?? ''}`, + `Reason indexed: ${indexed.absolute} (${indexed.relative})`, + ]; + if (reason.by === undefined) { + lines.push('Reason actor: '); + } else { + lines.push( + `Reason actor: ${reason.by.displayName}`, + `Reason actor handle: @${reason.by.handle}`, + `Reason actor DID: ${reason.by.did}`, + `Reason actor profile ref: ${displayReference(authorReference(view, reason.by))}`, + ); + } + return lines; +} + +function describeCompactFeedAge(value: string | undefined, fetchedAt: string): string { + if (value === undefined) return 'age unavailable'; + const instant = Date.parse(value); + const reference = Date.parse(fetchedAt); + if (!Number.isFinite(instant) || !Number.isFinite(reference)) return 'age unavailable'; + + const delta = reference - instant; + const seconds = Math.floor(Math.abs(delta) / 1_000); + const units: Array<[number, string]> = [ + [31_536_000, 'y'], + [86_400, 'd'], + [3_600, 'h'], + [60, 'm'], + [1, 's'], + ]; + let distance = '0s'; + for (const [size, suffix] of units) { + if (seconds >= size) { + distance = `${Math.floor(seconds / size)}${suffix}`; + break; + } + } + return delta < 0 ? `${distance} after page` : `${distance} ago`; +} + +function renderFeedReasonHtml(view: ReadingView, reason: FeedReason | undefined, fetchedAt: string): string { + if (reason === undefined) return ''; + + const actor = reason.by === undefined + ? undefined + : `${escapeHtml(reason.by.displayName || `@${reason.by.handle}`)} @${escapeHtml(reason.by.handle)} ${renderReferenceHtml(authorReference(view, reason.by))}`; + let headline: string; + if (reason.kind === 'repost') { + headline = actor === undefined ? 'Reposted · actor not supplied' : `Reposted by ${actor}`; + } else if (reason.kind === 'pin') { + headline = actor === undefined ? 'Pinned by source' : `Pinned by source · ${actor}`; + } else { + const exactType = reason.type === undefined ? 'type not supplied' : escapeHtml(reason.type); + headline = actor === undefined ? `Unknown source reason · ${exactType}` : `Unknown source reason · ${exactType} · ${actor}`; + } + const timing = reason.indexedAt === undefined + ? '' + : `${escapeHtml(describeCompactFeedAge(reason.indexedAt, fetchedAt))}`; + return `
${headline}${timing}
`; +} + +function shouldExcerptFeedCopy(value: string, variant: 'body' | 'glimpse'): boolean { + const threshold = variant === 'body' ? FEED_BODY_EXCERPT_THRESHOLD : FEED_GLIMPSE_EXCERPT_THRESHOLD; + const lineLimit = variant === 'body' ? 6 : 2; + if (value.length > threshold) return true; + let lines = 1; + for (let index = 0; index < value.length; index += 1) { + if (value.charCodeAt(index) === 10 && ++lines > lineLimit) return true; + } + return false; +} + +function renderFeedCopyHtml( + text: string | undefined, + variant: 'body' | 'glimpse', + subject: string, +): string { + if (text === undefined) return `
${escapeHtml(subject)} text was not supplied.
`; + if (text.length === 0) return `
${escapeHtml(subject)} text is present and empty.
`; + + const exact = escapeHtml(text); + const excerpted = shouldExcerptFeedCopy(text, variant); + if (!excerpted) return `
${exact}
`; + return `
+
${exact}
+
Original ${escapeHtml(subject.toLowerCase())} text excerpt · full exact text in source details
+
`; +} + +function renderFeedCountsHtml(node: PostNode | undefined): string { + const entries: Array<[string, number | undefined]> = [ + ['Replies', node?.counts.replies], + ['Likes', node?.counts.likes], + ['Reposts', node?.counts.reposts], + ['Quotes', node?.counts.quotes], + ]; + const row = entries.map(([label, value]) => { + const exact = value === undefined ? 'not supplied' : String(value); + const visible = value === undefined + ? '—' + : Math.abs(value) < 1_000 + ? String(value) + : COMPACT_COUNT_FORMATTER.format(value); + return `${escapeHtml(visible)}${escapeHtml(label)}`; + }).join(''); + return `
${row}
`; +} + +function renderFeedAuthorHtml( + view: ReadingView, + author: Author | undefined, + occurrenceReference: string | undefined, + postReference: string | undefined, + createdAt: string | undefined, + fetchedAt: string, +): string { + const meta = `
${escapeHtml(describeCompactFeedAge(createdAt, fetchedAt))}entry ${renderReferenceHtml(occurrenceReference)}post ${renderReferenceHtml(postReference)}
`; + if (author === undefined) { + return `
Author identity not supplied
${meta}
`; + } + + const initial = author.displayName.trim().slice(0, 1) || author.handle.trim().slice(0, 1) || '?'; + const avatar = author.avatar === undefined + ? `` + : `Avatar unavailable${escapeHtml(`${author.displayName} avatar`)}`; + return `
+
${avatar}
+
+
${escapeHtml(author.displayName || '(empty display name)')}@${escapeHtml(author.handle)}${renderReferenceHtml(authorReference(view, author))}
+ ${meta} +
+
`; +} + +function renderFeedMediaPreviewHtml(view: ReadingView, media: Media, ownerUri: string, index: number): string { + const preview = media.kind === 'video' ? (media.thumbnail ?? media.url) : (media.url ?? media.thumbnail); + const reference = Object.entries(view.refs).find(([, target]) => + target.kind === 'media' && target.ownerUri === ownerUri && target.index === index + )?.[0]; + const image = preview === undefined + ? '
No preview URL supplied
' + : `
Preview unavailable during capture${escapeHtml(media.alt ?? '')}
`; + return `
+ ${image} +
${media.kind === 'video' ? 'Video poster · not playback' : 'Image'}${renderReferenceHtml(reference)}
+
`; +} + +function renderFeedGlimpseHtml( + view: ReadingView, + label: 'Reply parent' | 'Quoted post', + uri: string, + node: PostNode | undefined, +): string { + const reference = referenceForValue(view, 'post', uri); + const relationship = label === 'Reply parent' ? 'Replying to' : 'Quoting'; + if (node === undefined) { + const message = label === 'Reply parent' + ? 'Parent text unavailable; this occurrence remains a reply.' + : 'Quoted text unavailable; the quote relationship remains explicit.'; + return ``; + } + + const author = node.author === undefined + ? 'author not supplied' + : `${escapeHtml(node.author.displayName || `@${node.author.handle}`)}@${escapeHtml(node.author.handle)}${renderReferenceHtml(authorReference(view, node.author))}`; + const availability = node.availability === 'available' + ? '' + : `${escapeHtml(node.availability)}`; + const media = node.media.length === 0 + ? '' + : `
${node.media.length} context media ${node.media.length === 1 ? 'item' : 'items'} retained in text and JSON
`; + return ``; +} + +function renderFeedContextHtml( + view: ReadingView, + occurrence: FeedOccurrence, + node: PostNode | undefined, + nodes: Map, +): string { + const glimpses: string[] = []; + const parentUri = occurrence.parentUri ?? node?.parentUri; + if (parentUri !== undefined) { + glimpses.push(renderFeedGlimpseHtml(view, 'Reply parent', parentUri, nodes.get(parentUri))); + } + + if (node !== undefined) { + const shownQuotes = Math.min(node.quotes.length, FEED_QUOTE_PREVIEW_LIMIT); + for (let index = 0; index < shownQuotes; index += 1) { + const uri = node.quotes[index]; + glimpses.push(renderFeedGlimpseHtml(view, 'Quoted post', uri, nodes.get(uri))); + } + if (node.quotes.length > shownQuotes) { + const refs = node.quotes.slice(shownQuotes).map((uri) => renderReferenceHtml(referenceForValue(view, 'post', uri))).join(' '); + glimpses.push(`
${node.quotes.length - shownQuotes} additional quoted-post ${node.quotes.length - shownQuotes === 1 ? 'glimpse' : 'glimpses'} omitted: ${refs}
`); + } + } + + return glimpses.length === 0 ? '' : `
${glimpses.join('')}
`; +} + +function renderFeedMediaHtml(view: ReadingView, node: PostNode): string { + if (node.media.length === 0) return ''; + const shown = Math.min(node.media.length, FEED_MEDIA_PREVIEW_LIMIT); + const previews: string[] = []; + for (let index = 0; index < shown; index += 1) { + previews.push(renderFeedMediaPreviewHtml(view, node.media[index], node.uri, index)); + } + const omitted = node.media.length - shown; + const omittedRefs = omitted === 0 + ? '' + : node.media.slice(shown).map((_, offset) => { + const index = shown + offset; + const reference = Object.entries(view.refs).find(([, target]) => + target.kind === 'media' && target.ownerUri === node.uri && target.index === index + )?.[0]; + return renderReferenceHtml(reference); + }).join(' '); + return `
+
${previews.join('')}
+ ${omitted === 0 ? '' : `
${omitted} more media ${omitted === 1 ? 'preview' : 'previews'} omitted: ${omittedRefs}
`} +
`; +} + +function renderFeedLinkPreviewHtml(view: ReadingView, card: LinkCard, ownerUri: string, index: number): string { + const reference = referenceForValue(view, 'link', card.uri, ownerUri, index); + const image = card.thumbnail === undefined + ? '' + : `
Thumbnail unavailable during capture
`; + return `
+ ${image} +
+
External preview ${renderReferenceHtml(reference)}
+ ${escapeHtml(card.title || '(empty title)')} +
${escapeHtml(card.description)}
+
+
`; +} + +function renderFeedCardsHtml(view: ReadingView, node: PostNode): string { + if (node.cards.length === 0) return ''; + const shown = Math.min(node.cards.length, FEED_CARD_PREVIEW_LIMIT); + const cards: string[] = []; + for (let index = 0; index < shown; index += 1) { + cards.push(renderFeedLinkPreviewHtml(view, node.cards[index], node.uri, index)); + } + const omitted = node.cards.length - shown; + const omittedRefs = omitted === 0 + ? '' + : node.cards.slice(shown).map((card, offset) => renderReferenceHtml(referenceForValue(view, 'link', card.uri, node.uri, shown + offset))).join(' '); + return `
+ ${cards.join('')} + ${omitted === 0 ? '' : `
${omitted} more external-card ${omitted === 1 ? 'preview' : 'previews'} omitted: ${omittedRefs}
`} +
`; +} + +function renderFeedDetailsHtml( + view: ReadingView, + snapshot: FeedSnapshot, + occurrence: FeedOccurrence, + sourcePosition: number, + node: PostNode | undefined, + nodes: Map, +): string { + const created = describeTimestamp(node?.createdAt, snapshot.fetchedAt); + const indexed = describeTimestamp(node?.indexedAt, snapshot.fetchedAt); + const reasonIndexed = describeTimestamp(occurrence.reason?.indexedAt, snapshot.fetchedAt); + const count = (value: number | undefined): string => value === undefined ? 'not supplied' : String(value); + const relationships: string[] = []; + if (occurrence.parentUri !== undefined) { + relationships.push(`
  • Occurrence parent ${renderReferenceHtml(referenceForValue(view, 'post', occurrence.parentUri))}
    ${escapeHtml(occurrence.parentUri)}
    • `); + } + if (occurrence.rootUri !== undefined) { + relationships.push(`
  • Occurrence root ${renderReferenceHtml(referenceForValue(view, 'post', occurrence.rootUri))}
    ${escapeHtml(occurrence.rootUri)}
    • `); + } + if (node?.parentUri !== undefined && node.parentUri !== occurrence.parentUri) { + relationships.push(`
  • Post-record parent ${renderReferenceHtml(referenceForValue(view, 'post', node.parentUri))}
    ${escapeHtml(node.parentUri)}
    • `); + } + if (node?.rootUri !== undefined && node.rootUri !== occurrence.rootUri) { + relationships.push(`
  • Post-record root ${renderReferenceHtml(referenceForValue(view, 'post', node.rootUri))}
    ${escapeHtml(node.rootUri)}
    • `); + } + + const reasonActor = occurrence.reason?.by; + const textRecords: Array<[string, PostNode | undefined]> = [['Original post', node]]; + const contextTextUris: Array<[string, string | undefined]> = [ + ['Occurrence parent', occurrence.parentUri], + ['Post-record parent', node?.parentUri], + ['Occurrence root', occurrence.rootUri], + ['Post-record root', node?.rootUri], + ]; + node?.quotes.forEach((uri, index) => contextTextUris.push([`Quoted post ${index + 1}`, uri])); + const seenContextTextUris = new Set(); + for (const [label, uri] of contextTextUris) { + if (uri === undefined || seenContextTextUris.has(uri)) continue; + seenContextTextUris.add(uri); + textRecords.push([label, nodes.get(uri)]); + } + const exactTexts = textRecords.map(([label, record]) => { + const copy = record === undefined + ? '
    Context node was not supplied.
    ' + : record.text === undefined + ? '
    Text was not supplied.
    ' + : record.text.length === 0 + ? '
    Text is present and empty.
    ' + : `
    ${escapeHtml(record.text)}
    `; + return `
    ${escapeHtml(label)}${copy}
    `; + }); + const mediaDetails = node?.media.map((media, index) => { + const value = media.url ?? media.thumbnail ?? `${node.uri}#${media.kind}-${index}`; + const reference = referenceForValue(view, 'media', value, node.uri, index); + const dimensions = media.width === undefined || media.height === undefined + ? 'dimensions not supplied' + : `${media.width} × ${media.height}`; + return `
  • ${media.kind === 'video' ? 'Video poster' : 'Image'} ${index + 1} ${renderReferenceHtml(reference)} · ${escapeHtml(dimensions)}
    URL: ${escapeHtml(media.url ?? 'not supplied')} · thumbnail: ${escapeHtml(media.thumbnail ?? 'not supplied')}
    Alt: ${escapeHtml(media.alt === undefined ? 'not supplied' : JSON.stringify(media.alt))}
    • `; + }) ?? []; + const cardDetails = node?.cards.map((card, index) => + `
  • External card ${index + 1} ${renderReferenceHtml(referenceForValue(view, 'link', card.uri, node.uri, index))}
    ${escapeHtml(card.uri)}
    ${escapeHtml(card.title)} · ${escapeHtml(card.description)}
    • ` + ) ?? []; + const quoteDetails = node?.quotes.map((uri, index) => + `
  • Quoted post ${index + 1} ${renderReferenceHtml(referenceForValue(view, 'post', uri))}
    ${escapeHtml(uri)}
    • ` + ) ?? []; + return `
    + Exact source details +
    +
    +
    Source position
    ${sourcePosition}
    +
    Occurrence
    ${escapeHtml(occurrence.id)} · ${renderReferenceHtml(referenceForValue(view, 'occurrence', occurrence.id))}
    +
    Canonical post
    ${renderReferenceHtml(referenceForValue(view, 'post', occurrence.postUri))}
    ${escapeHtml(occurrence.postUri)}
    +
    Availability
    ${node === undefined ? 'primary node not supplied' : escapeHtml(node.availability)}
    +
    Created
    ${escapeHtml(created.absolute)}
    ${escapeHtml(created.relative)}
    +
    Indexed by service
    ${escapeHtml(indexed.absolute)}
    ${escapeHtml(indexed.relative)}
    +
    Reason kind / type
    ${escapeHtml(occurrence.reason?.kind ?? 'not supplied')} / ${escapeHtml(occurrence.reason?.type ?? 'not supplied')}
    +
    Reason indexed
    ${escapeHtml(reasonIndexed.absolute)}
    ${escapeHtml(reasonIndexed.relative)}
    +
    Reason actor
    ${reasonActor === undefined ? 'not supplied' : `${escapeHtml(reasonActor.did)} · ${renderReferenceHtml(authorReference(view, reasonActor))}`}
    +
    CID
    ${escapeHtml(node?.cid ?? 'not supplied')}
    +
    Attachments
    ${node === undefined ? 'not supplied' : `${node.media.length} media · ${node.cards.length} external cards · ${node.quotes.length} quotes`}
    +
    +
    Exact reported engagementReplies ${count(node?.counts.replies)}Likes ${count(node?.counts.likes)}Reposts ${count(node?.counts.reposts)}Quotes ${count(node?.counts.quotes)}
    +
    Exact retained text${exactTexts.join('')}
    + ${occurrence.reason === undefined ? '

    No source reason was supplied for this occurrence; its appearance does not establish a direct follow.

    ' : ''} + ${relationships.length === 0 ? '

    No parent or root identity was supplied.

    ' : `
      ${relationships.join('')}
    `} + ${mediaDetails.length + cardDetails.length + quoteDetails.length === 0 ? '' : `
    Exact attachment records
      ${[...mediaDetails, ...cardDetails, ...quoteDetails].join('')}
    `} + ${node === undefined ? '' : renderFacetsHtml(view, node.facets)} + ${node === undefined || node.labels.length === 0 ? '' : `
    Labels ${escapeHtml(node.labels.join(' · '))}
    `} + ${node === undefined || node.unsupported.length === 0 ? '' : `
    Unsupported source material ${escapeHtml(node.unsupported.join(' · '))}
    `} +
    +
    `; +} + +function renderFeedEntryHtml( + view: ReadingView, + snapshot: FeedSnapshot, + occurrence: FeedOccurrence, + index: number, + nodes: Map, +): string { + const node = nodes.get(occurrence.postUri); + const occurrenceReference = referenceForValue(view, 'occurrence', occurrence.id); + const postReference = referenceForValue(view, 'post', occurrence.postUri); + const availability = node === undefined + ? '
    The occurrence has a canonical post identity, but its primary node was not supplied in this bounded snapshot.
    ' + : node.availability === 'available' + ? '' + : `
    Post availability: ${escapeHtml(node.availability)}. Fields below are only those retained by the source.
    `; + const body = node === undefined + ? '
    Original post body was not supplied for this occurrence.
    ' + : node.text === '' && node.media.length + node.cards.length + node.quotes.length > 0 + ? '' + : renderFeedCopyHtml(node.text, 'body', 'Post'); + + return `
    + ${renderFeedReasonHtml(view, occurrence.reason, snapshot.fetchedAt)} + ${availability} + ${renderFeedAuthorHtml(view, node?.author, occurrenceReference, postReference, node?.createdAt, snapshot.fetchedAt)} + ${body} + ${renderFeedCountsHtml(node)} + ${node === undefined ? '' : renderFeedMediaHtml(view, node)} + ${node === undefined ? '' : renderFeedCardsHtml(view, node)} + ${renderFeedContextHtml(view, occurrence, node, nodes)} + ${renderFeedDetailsHtml(view, snapshot, occurrence, index + 1, node, nodes)} +
    `; +} + +function renderFeedText(view: ReadingView, snapshot: FeedSnapshot): string { + const fetched = describeTimestamp(snapshot.fetchedAt, snapshot.fetchedAt); + const lines = [ + `PERCH READING VIEW ${view.id}`, + 'FOLLOWING FEED', + `Feed: ${snapshot.feed}`, + `Snapshot reference: ${fetched.absolute}`, + ...renderSourceText(snapshot.source), + `Requested page limit: ${snapshot.limit}`, + `Request cursor: ${snapshot.requestCursor ?? ''}`, + `Next cursor: ${snapshot.cursor ?? ''}`, + `Occurrences in supplied source order: ${snapshot.entries.length}`, + `Supplied canonical/context nodes: ${snapshot.nodes.length}; local node cap ${snapshot.maxNodes}`, + `Locally truncated: ${snapshot.locallyTruncated}`, + `Warnings: ${snapshot.warnings.length === 0 ? '' : snapshot.warnings.join(' | ')}`, + 'This is one bounded page in upstream order, not the whole network or a claim about another client\'s ranking.', + 'A timeline occurrence does not establish that every post author was followed directly.', + '', + ]; + + if (snapshot.entries.length === 0) lines.push('FEED OCCURRENCES: ', ''); + const nodes = new Map(snapshot.nodes.map((node) => [node.uri, node])); + const primaryUris = new Set(); + snapshot.entries.forEach((occurrence, index) => { + const node = nodes.get(occurrence.postUri); + primaryUris.add(occurrence.postUri); + lines.push( + `##### FEED OCCURRENCE ${index + 1} OF ${snapshot.entries.length} #####`, + `Occurrence ID: ${occurrence.id}`, + `Occurrence ref: ${displayReference(referenceForValue(view, 'occurrence', occurrence.id))}`, + `Canonical post: ${occurrence.postUri}`, + `Post ref: ${displayReference(referenceForValue(view, 'post', occurrence.postUri))}`, + `Occurrence parent URI: ${occurrence.parentUri ?? ''}${occurrence.parentUri === undefined ? '' : ` ${displayReference(referenceForValue(view, 'post', occurrence.parentUri))}`}`, + `Occurrence root URI: ${occurrence.rootUri ?? ''}${occurrence.rootUri === undefined ? '' : ` ${displayReference(referenceForValue(view, 'post', occurrence.rootUri))}`}`, + ...renderFeedReasonText(view, occurrence.reason, snapshot.fetchedAt), + renderNodeText(view, snapshot, { + node, + uri: occurrence.postUri, + label: `Post record for occurrence ${occurrence.id}`, + relationship: 'Primary post record; occurrence identity remains separate from canonical post identity', + tone: 'focus', + }), + '', + ); + }); + + const contextNodes = snapshot.nodes.filter((node) => !primaryUris.has(node.uri)); + if (contextNodes.length > 0) { + lines.push('##### ADDITIONAL SUPPLIED CONTEXT NODES #####'); + contextNodes.forEach((node, index) => { + lines.push(renderNodeText(view, snapshot, { + node, + uri: node.uri, + label: `Context node ${index + 1} of ${contextNodes.length}`, + relationship: 'Supplied as bounded parent, root, or quote context; not a feed occurrence', + tone: 'context', + }), ''); + }); + } + + lines.push('REFERENCE LEDGER'); + for (const [reference, target] of Object.entries(view.refs)) { + lines.push(`${reference}: ${target.kind} ${target.value} — ${target.label}${target.ownerUri === undefined ? '' : ` · owner ${target.ownerUri}`}${target.index === undefined ? '' : ` · index ${target.index}`}`); + } + return `${lines.join('\n').trimEnd()}\n`; +} + +function renderFeedHtml(view: ReadingView, snapshot: FeedSnapshot): string { + const fetched = describeTimestamp(snapshot.fetchedAt, snapshot.fetchedAt); + const notices = [ + ...(snapshot.locallyTruncated ? ['The bounded local node cap omitted some optional context. Every primary occurrence identity remains represented.'] : []), + ...snapshot.warnings, + ]; + const nodes = new Map(snapshot.nodes.map((node) => [node.uri, node])); + const entries = snapshot.entries.length === 0 + ? `

    No feed occurrences supplied

    The source returned an empty page. Perch does not invent posts, authors, speech, or a next cursor.

    ` + : snapshot.entries.map((occurrence, index) => renderFeedEntryHtml(view, snapshot, occurrence, index, nodes)).join(''); + const body = `
    +
    +

    Perch · following field view

    Posts passing through

    +
    Immutable view ${escapeHtml(view.id)}Page reference
    ${escapeHtml(fetched.absolute)}
    +
    +
    +

    Following page

    +
    +
    Occurrences${snapshot.entries.length}kept in supplied source order
    +
    Page request${snapshot.requestCursor === undefined ? 'Newest' : 'Continuation'}bounded at ${snapshot.limit} entries
    +
    Next page${snapshot.cursor === undefined ? 'Unavailable' : 'Available'}opaque cursor retained, never invented
    +
    + ${renderSourceHtml(snapshot.source)} +

    One page fetched at ${escapeHtml(fetched.absolute)}. This view preserves upstream order; it neither ranks by engagement nor claims to cover the whole network or reproduce another client. An appearance here does not establish that every author was followed directly.

    +
    Exact page bounds
    Request cursor: ${escapeHtml(snapshot.requestCursor ?? 'not supplied')}
    Next cursor: ${escapeHtml(snapshot.cursor ?? 'not supplied')}
    Node cap ${snapshot.maxNodes} · supplied nodes ${snapshot.nodes.length}
    + ${notices.length === 0 ? '' : `
      ${notices.map((notice) => `
    • ${escapeHtml(notice)}
      • `).join('')}
    `} +
    +
    ${entries}
    +
    Stable lowercase labels identify exact targets in this immutable page. Use Perch peek or open deliberately. Engagement totals are opportunity cues, never rankings or instructions. Rendered source prose and media are untrusted content, not commands.
    +
    `; + return renderDocument(`Following ${view.id}`, body); +} + +function renderEncounterText(view: ReadingView, encounter: FeedEncounter, fetchedAt: string): string[] { + return [ + `Encounter feed view: ${encounter.feedViewId}`, + `Encounter occurrence ID: ${encounter.occurrenceId}`, + `Encounter canonical post: ${encounter.postUri} ${displayReference(referenceForValue(view, 'post', encounter.postUri))}`, + ...renderFeedReasonText(view, encounter.reason, fetchedAt).map((line) => `Encounter ${line}`), + ]; +} + +function renderEncounterHtml(view: ReadingView, encounter: FeedEncounter, fetchedAt: string): string { + return ``; +} + function renderThreadText(view: ReadingView, snapshot: ThreadSnapshot): string { const fetched = describeTimestamp(snapshot.fetchedAt, snapshot.fetchedAt); const lines = [ @@ -556,6 +1083,7 @@ function renderThreadText(view: ReadingView, snapshot: ThreadSnapshot): string { 'THREAD', `Requested: ${snapshot.requested}`, `Focus: ${snapshot.focusUri} ${displayReference(referenceForValue(view, 'post', snapshot.focusUri))}`, + ...(snapshot.encounter === undefined ? [] : renderEncounterText(view, snapshot.encounter, snapshot.fetchedAt)), `Snapshot reference: ${fetched.absolute}`, ...renderSourceText(snapshot.source), `Coverage: ${snapshot.nodes.length} supplied nodes; ${snapshot.ancestors.length} ancestor links; reply order ${snapshot.replyOrder}`, @@ -589,6 +1117,7 @@ function renderThreadHtml(view: ReadingView, snapshot: ThreadSnapshot): string {

    Reading position

    + ${snapshot.encounter === undefined ? '' : renderEncounterHtml(view, snapshot.encounter, snapshot.fetchedAt)}
    Focus${renderReferenceHtml(referenceForValue(view, 'post', snapshot.focusUri))}${escapeHtml(snapshot.focusUri)}
    Coverage supplied${snapshot.nodes.length} nodes${snapshot.ancestors.length} ancestor links · replies remain in source order
    @@ -728,6 +1257,8 @@ ${body} /** Render a stable, exact-text representation of a stored reading view. */ export function renderText(view: ReadingView): string { switch (view.snapshot.kind) { + case 'feed': + return renderFeedText(view, view.snapshot); case 'thread': return renderThreadText(view, view.snapshot); case 'profile': @@ -740,6 +1271,8 @@ export function renderText(view: ReadingView): string { /** Render a self-contained, inert HTML representation of a stored reading view. */ export function renderHtml(view: ReadingView): string { switch (view.snapshot.kind) { + case 'feed': + return renderFeedHtml(view, view.snapshot); case 'thread': return renderThreadHtml(view, view.snapshot); case 'profile': @@ -824,7 +1357,7 @@ export async function captureView( await page.waitForFunction(() => Array.from(document.images).every((image) => image.complete), undefined, { timeout: 10_000 }).catch(() => undefined); await page.evaluate(() => { for (const image of document.images) { - const container = image.closest('.media-item, .avatar-frame, .link-card'); + const container = image.closest('.media-item, .avatar-frame, .link-card, .feed-link-preview'); if (container === null) continue; container.classList.toggle('media-missing', image.naturalWidth === 0 || image.naturalHeight === 0); } diff --git a/src/store.ts b/src/store.ts index d1bc620..f4590b9 100644 --- a/src/store.ts +++ b/src/store.ts @@ -136,6 +136,83 @@ function buildReferences(viewId: string, snapshot: Snapshot): Record [node.uri, node])); + for (const entry of snapshot.entries) { + const node = nodesByUri.get(entry.postUri); + add('e', { + kind: 'occurrence', + value: entry.id, + label: node?.author ? `Feed occurrence ${entry.id}: post by @${node.author.handle}` : `Feed occurrence ${entry.id}`, + }); + } + for (const node of snapshot.nodes) { + add('p', { + kind: 'post', + value: node.uri, + label: node.author ? `Post by @${node.author.handle}` : 'Post', + }); + if (node.author) { + add('a', { + kind: 'profile', + value: node.author.did, + label: node.author.displayName || `@${node.author.handle}`, + }); + } + for (const facet of node.facets) { + for (const target of facet.targets) add('f', { ...target }); + } + for (let index = 0; index < node.quotes.length; index += 1) { + add('q', { + kind: 'post', + value: node.quotes[index], + label: 'Quoted post', + ownerUri: node.uri, + index, + }); + } + for (let index = 0; index < node.cards.length; index += 1) { + const card = node.cards[index]; + add('c', { + kind: 'link', + value: card.uri, + label: card.title || card.uri, + ownerUri: node.uri, + index, + }); + } + for (let index = 0; index < node.media.length; index += 1) { + const media = node.media[index]; + add('m', { + kind: 'media', + value: media.url ?? media.thumbnail ?? `${node.uri}#${media.kind}-${index}`, + label: media.kind === 'video' ? 'Video media' : 'Image media', + ownerUri: node.uri, + index, + }); + } + } + for (const entry of snapshot.entries) { + const actor = entry.reason?.by; + if (actor) { + add('a', { + kind: 'profile', + value: actor.did, + label: actor.displayName || `@${actor.handle}`, + }); + } + } + for (const node of snapshot.nodes) { + if (node.parentUri) add('p', { kind: 'post', value: node.parentUri, label: 'Known parent post' }); + if (node.rootUri) add('p', { kind: 'post', value: node.rootUri, label: 'Known root post' }); + for (const replyUri of node.replies) { + add('p', { kind: 'post', value: replyUri, label: 'Known reply post' }); + } + } + for (const entry of snapshot.entries) { + if (entry.parentUri) add('p', { kind: 'post', value: entry.parentUri, label: 'Known parent post' }); + if (entry.rootUri) add('p', { kind: 'post', value: entry.rootUri, label: 'Known root post' }); + } } else if (snapshot.kind === 'profile') { add('a', { kind: 'profile', @@ -143,7 +220,7 @@ function buildReferences(viewId: string, snapshot: Snapshot): Record span:not(.reference) { + color: var(--color-ink-soft); + font-family: var(--font-mono); + font-size: var(--text-xs); +} + +.feed-author-row { + display: grid; + grid-template-columns: auto minmax(0, 1fr); + gap: var(--space-2); + align-items: center; + min-width: 0; + margin-block-end: var(--space-2); +} + +.feed-author-row > div { + min-width: 0; +} + +.feed-author-row .avatar-frame { + width: 2.25rem; + height: 2.25rem; +} + +.feed-author-identity, +.feed-card-meta { + display: flex; + min-width: 0; + flex-wrap: wrap; + gap: var(--space-1) var(--space-2); + align-items: baseline; + overflow-wrap: anywhere; +} + +.feed-author-identity { + color: var(--color-ink-soft); + font-size: var(--text-sm); +} + +.feed-author-identity strong { + color: var(--color-ink); + font-size: var(--text-md); +} + +.feed-card-meta { + margin-block-start: var(--space-1); + color: var(--color-ink-faint); + font-family: var(--font-mono); + font-size: var(--text-xs); +} + +.feed-copy, +.feed-exact-copy { + max-width: var(--prose-width); + overflow-wrap: anywhere; + white-space: pre-wrap; +} + +.feed-copy.body { + margin-block-end: var(--space-2); + font-size: var(--text-lg); + line-height: 1.5; +} + +.feed-copy.glimpse { + margin-block-end: var(--space-2); + line-height: 1.45; +} + +.feed-copy.excerpted { + display: -webkit-box; + overflow: hidden; + -webkit-box-orient: vertical; +} + +.feed-copy.body.excerpted { + -webkit-line-clamp: 6; +} + +.feed-copy.glimpse.excerpted { + -webkit-line-clamp: 2; +} + +.feed-excerpt-note { + margin-block: var(--space-1) var(--space-2); + color: var(--color-warning); + font-family: var(--font-mono); + font-size: var(--text-xs); +} + +.feed-record-details, +.feed-page-details { + color: var(--color-ink-soft); + font-size: var(--text-sm); +} + +.feed-record-details summary, +.feed-page-details summary { + color: var(--color-branch); + font-family: var(--font-mono); + font-size: var(--text-xs); + font-weight: 700; + letter-spacing: 0.025em; + cursor: pointer; +} + +.feed-record-details summary:focus-visible, +.feed-page-details summary:focus-visible { + outline: var(--line-heavy) solid var(--color-focus); + outline-offset: var(--space-1); +} + +.feed-exact-copy { + margin-block-start: var(--space-2); + padding: var(--space-3); + background: var(--color-surface-muted); + border: var(--line-thin) solid var(--color-line); + color: var(--color-ink); + font-size: var(--text-md); +} + +.feed-engagement { + display: flex; + flex-wrap: wrap; + gap: var(--space-1); + margin-block: var(--space-2) var(--space-1); +} + +.feed-count { + display: flex; + min-width: 0; + gap: var(--space-1); + align-items: baseline; + justify-content: center; + padding: var(--space-1) var(--space-2); + overflow: hidden; + background: var(--color-surface-muted); + border-radius: var(--radius-sm); + color: var(--color-ink-soft); + font-size: var(--text-sm); + white-space: nowrap; +} + +.feed-count strong { + color: var(--color-ink); + font-variant-numeric: tabular-nums; +} + +.feed-count.unknown { + color: var(--color-ink-faint); +} + +.feed-exact-counts { + display: flex; + flex-wrap: wrap; + gap: var(--space-1) var(--space-3); + justify-content: flex-start; + margin-block: var(--space-3); +} + +.feed-media, +.feed-links { + margin-block-start: var(--space-2); +} + +.feed-media-grid { + display: grid; + grid-template-columns: repeat(2, minmax(0, 1fr)); + gap: var(--space-2); +} + +.feed-card .media-item { + border-radius: var(--radius-sm); +} + +.feed-card .image-stage { + min-height: var(--space-7); +} + +.feed-card .image-stage img { + max-height: var(--feed-media-height); + object-fit: contain; +} + +.feed-card figcaption { + display: flex; + flex-wrap: wrap; + gap: var(--space-1) var(--space-2); + align-items: center; + padding: var(--space-1) var(--space-2); + font-size: var(--text-xs); +} + +.feed-card figcaption .media-kind { + display: inline; + margin: 0; +} + +.feed-link-preview { + display: grid; + grid-template-columns: 8rem minmax(0, 1fr); + min-width: 0; + overflow: hidden; + background: var(--color-surface-muted); + border: var(--line-thin) solid var(--color-line); + border-radius: var(--radius-sm); +} + +.feed-link-preview.no-thumbnail { + grid-template-columns: 1fr; +} + +.feed-link-preview .image-stage img { + width: 100%; + height: 100%; + max-height: 9rem; + object-fit: contain; +} + +.feed-link-preview.media-missing .media-failure { + display: grid; +} + +.feed-link-copy { + min-width: 0; + padding: var(--space-2) var(--space-3); +} + +.feed-link-label { + margin-block-end: var(--space-1); + color: var(--color-ink-soft); + font-family: var(--font-mono); + font-size: var(--text-xs); +} + +.feed-link-copy > strong { + display: block; + overflow-wrap: anywhere; +} + +.feed-link-description { + display: -webkit-box; + overflow: hidden; + color: var(--color-ink-soft); + font-size: var(--text-sm); + white-space: pre-wrap; + -webkit-box-orient: vertical; + -webkit-line-clamp: 2; +} + +.feed-context-stack { + display: grid; + gap: var(--space-2); + margin-block-start: var(--space-2); +} + +.feed-glimpse { + min-width: 0; + padding-inline-start: var(--space-3); + overflow-wrap: anywhere; + border-inline-start: var(--line-heavy) solid var(--color-focus); +} + +.feed-glimpse.unavailable { + border-inline-start-color: var(--color-danger); +} + +.feed-glimpse-head { + gap: var(--space-1) var(--space-2); + margin-block-end: var(--space-1); + color: var(--color-ink-soft); + font-size: var(--text-sm); +} + +.feed-glimpse-head > strong:first-child { + color: var(--color-focus); + font-family: var(--font-mono); + font-size: var(--text-xs); + letter-spacing: 0.025em; + text-transform: uppercase; +} + +.feed-glimpse-status { + color: var(--color-danger); + font-family: var(--font-mono); + font-size: var(--text-xs); +} + +.feed-glimpse-missing { + color: var(--color-ink-soft); + font-style: italic; +} + +.feed-glimpse .feed-copy.glimpse { + margin-block-end: 0; + font-size: var(--text-md); +} + +.feed-glimpse-media-note { + margin-block-start: var(--space-1); + color: var(--color-ink-faint); + font-size: var(--text-xs); +} + +.feed-omission { + margin-block-start: var(--space-2); + padding: var(--space-2); + overflow-wrap: anywhere; + background: var(--color-warning-soft); + color: var(--color-warning); + font-size: var(--text-xs); +} + +.feed-record-details { + margin-block-start: var(--space-2); + padding-block-start: var(--space-2); + border-block-start: var(--line-thin) solid var(--color-line); +} + +.feed-record-details .technical-body { + padding: var(--space-3); +} + +.feed-exact-counts > strong { + flex-basis: 100%; +} + +.feed-detail-line, +.feed-detail-section { + margin-block-start: var(--space-3); + overflow-wrap: anywhere; +} + +.feed-exact-text-record { + margin-block-start: var(--space-2); +} + +.feed-exact-text-record > strong { + color: var(--color-ink); + font-family: var(--font-mono); + font-size: var(--text-xs); + letter-spacing: 0.025em; + text-transform: uppercase; +} + +.feed-exact-text-record .feed-exact-copy { + margin-block-start: var(--space-1); +} + +.feed-page-details { + margin-block-start: var(--space-3); +} + +.encounter-breadcrumb { + margin-block: var(--space-3) var(--space-4); + padding: var(--space-3); + overflow-wrap: anywhere; + background: var(--color-focus-soft); + border-inline-start: var(--line-heavy) solid var(--color-focus); +} + +.encounter-path { + margin-block-end: var(--space-2); +} + +.encounter-path .eyebrow { + margin: 0; +} + +.encounter-path > strong { + font-family: var(--font-display); +} + +.encounter-breadcrumb .feed-reason { + margin-block: var(--space-2) 0; +} + +.encounter-reason-missing { + margin-block-start: var(--space-2); + color: var(--color-ink-soft); + font-size: var(--text-sm); +} + .footer-note { margin-block-start: var(--space-6); padding-block-start: var(--space-4); @@ -688,9 +1135,17 @@ figcaption, .post-card, .profile-card, - .target-card { + .target-card, + .feed-card, + .feed-empty { padding: var(--space-4); } + + .feed-media-grid, + .feed-link-preview { + grid-template-columns: 1fr; + } + } @media print { diff --git a/tests/feed-cli.test.ts b/tests/feed-cli.test.ts new file mode 100644 index 0000000..b7a87cc --- /dev/null +++ b/tests/feed-cli.test.ts @@ -0,0 +1,380 @@ +import { afterEach, describe, expect, test } from 'bun:test'; +import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { runCli } from '../src/cli.ts'; +import type { FeedSnapshot, PostNode } from '../src/model.ts'; +import { ReadingStore } from '../src/store.ts'; + +const VIEWER_DID = 'did:plc:ewvi7nxzyoun6zhxrhs64oiz'; +const OTHER_VIEWER_DID = 'did:plc:js47frzswl2ezb6v235hlcz2'; +const AUTHOR_DID = 'did:plc:ragtjsm2j2vknwkz3zp4oxrd'; +const REPOSTER_DID = 'did:plc:yckmmocpnqkrdwkp2q5rdipl'; +const CID = 'bafyreigh2akiscaildcw453k5p2q5w2dmqnj4dnrz3llrqmk5f3x7tdpiy'; +const PDS = 'https://pds.example'; +const POST_ONE = `at://${AUTHOR_DID}/app.bsky.feed.post/one`; +const POST_TWO = `at://${AUTHOR_DID}/app.bsky.feed.post/two`; +const POST_THREE = `at://${AUTHOR_DID}/app.bsky.feed.post/three`; +const originalFetch = globalThis.fetch; +const originalLog = console.log; +const temporaryDirectories: string[] = []; + +type FetchResponder = (request: Request) => Response | Promise; + +interface AuthFixture { + path: string; + identifier: string; + password: string; + accessValue: string; + refreshValue: string; +} + +function temporaryDirectory(): string { + const directory = mkdtempSync(join(tmpdir(), 'perch-feed-cli-')); + temporaryDirectories.push(directory); + return directory; +} + +function authFixture(): AuthFixture { + const directory = temporaryDirectory(); + const fixture = { + path: join(directory, 'mcp.json'), + identifier: `fixture-${crypto.randomUUID()}.invalid`, + password: `fixture-${crypto.randomUUID()}`, + accessValue: `fixture-${crypto.randomUUID()}`, + refreshValue: `fixture-${crypto.randomUUID()}`, + }; + writeFileSync(fixture.path, JSON.stringify({ + mcpServers: { + atproto: { + env: { + BSKY_IDENTIFIER: fixture.identifier, + BSKY_APP_PASSWORD: fixture.password, + }, + }, + }, + }), { mode: 0o600 }); + return fixture; +} + +function apiPost(uri: string, text: string): Record { + return { + $type: 'app.bsky.feed.defs#postView', + uri, + cid: CID, + author: { did: AUTHOR_DID, handle: 'author.test', displayName: 'Author' }, + record: { + $type: 'app.bsky.feed.post', + text, + createdAt: '2026-09-05T10:00:00.000Z', + }, + indexedAt: '2026-09-05T10:00:01.000Z', + replyCount: 0, + likeCount: 0, + repostCount: 0, + quoteCount: 0, + }; +} + +function jsonResponse(data: unknown, status = 200): Response { + return new Response(JSON.stringify(data), { + status, + headers: { 'content-type': 'application/json' }, + }); +} + +function installFetch(responder: FetchResponder): Request[] { + const requests: Request[] = []; + globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => { + const request = input instanceof Request && init === undefined ? input : new Request(input, init); + requests.push(request.clone()); + return responder(request); + }) as typeof fetch; + return requests; +} + +function sessionResponse(auth: AuthFixture, viewerDid = VIEWER_DID): Response { + return jsonResponse({ + did: viewerDid, + handle: 'viewer.test', + accessJwt: auth.accessValue, + refreshJwt: auth.refreshValue, + active: true, + }); +} + +function authFlags(auth: AuthFixture): string[] { + return ['--auth', '--auth-config', auth.path, '--pds', PDS]; +} + +async function runJson(database: string, arguments_: string[]): Promise { + const lines: string[] = []; + console.log = (...values: unknown[]) => lines.push(values.map(String).join(' ')); + try { + await runCli([...arguments_, '--db', database, '--json']); + } finally { + console.log = originalLog; + } + return JSON.parse(lines.join('\n')); +} + +function storedFeed(source: FeedSnapshot['source'], cursor?: string): FeedSnapshot { + const node: PostNode = { + uri: POST_ONE, + availability: 'available', + author: { did: AUTHOR_DID, handle: 'author.test', displayName: 'Author' }, + text: 'stored feed', + createdAt: '2026-09-05T10:00:00.000Z', + indexedAt: '2026-09-05T10:00:01.000Z', + replies: [], + repliesFetched: false, + facets: [], + media: [], + quotes: [], + cards: [], + labels: [], + unsupported: [], + counts: {}, + }; + return { + kind: 'feed', + feed: 'following', + fetchedAt: '2026-09-05T10:01:00.000Z', + source, + entries: [{ id: '1', postUri: POST_ONE }], + nodes: [node], + limit: 20, + ...(cursor !== undefined ? { cursor } : {}), + maxNodes: 600, + locallyTruncated: false, + warnings: [], + }; +} + +afterEach(() => { + globalThis.fetch = originalFetch; + console.log = originalLog; + for (const directory of temporaryDirectories.splice(0)) rmSync(directory, { recursive: true, force: true }); +}); + +describe('following-feed CLI navigation', () => { + test('requires explicit authentication and a bounded limit before any request or session movement', async () => { + const directory = temporaryDirectory(); + const database = join(directory, 'reader.sqlite'); + const requests = installFetch(() => jsonResponse({ error: 'UnexpectedRequest' }, 500)); + + await expect(runCli(['following', '--db', database, '--json'])) + .rejects.toThrow('following requires explicit --auth.'); + await expect(runCli(['following', '--auth', '--limit', '0', '--db', database, '--json'])) + .rejects.toThrow('--limit must be an integer from 1 to 100.'); + await expect(runCli(['following', '--auth', '--limit', '101', '--db', database, '--json'])) + .rejects.toThrow('--limit must be an integer from 1 to 100.'); + expect(requests).toHaveLength(0); + + const store = new ReadingStore(database); + expect(store.sessions()).toEqual([]); + store.close(); + }); + + test('stores separate pages, opens an occurrence encounter, and restores exact local state', async () => { + const directory = temporaryDirectory(); + const database = join(directory, 'reader.sqlite'); + const auth = authFixture(); + let newestReads = 0; + const requests = installFetch((request) => { + const url = new URL(request.url); + if (url.pathname.endsWith('/com.atproto.server.createSession')) return sessionResponse(auth); + if (url.pathname.endsWith('/app.bsky.feed.getTimeline')) { + const cursor = url.searchParams.get('cursor'); + if (cursor === 'cursor-one') { + return jsonResponse({ + cursor: 'cursor-two', + feed: [{ + post: apiPost(POST_TWO, 'second page'), + reason: { + $type: 'app.bsky.feed.defs#reasonRepost', + by: { did: REPOSTER_DID, handle: 'reposter.test', displayName: 'Reposter' }, + indexedAt: '2026-09-05T10:05:00.000Z', + }, + }], + }); + } + newestReads += 1; + return newestReads === 1 + ? jsonResponse({ cursor: 'cursor-one', feed: [{ post: apiPost(POST_ONE, 'first page') }] }) + : jsonResponse({ cursor: 'cursor-refresh', feed: [{ post: apiPost(POST_THREE, 'refreshed page') }] }); + } + if (url.pathname.endsWith('/app.bsky.feed.getPostThread')) { + const uri = url.searchParams.get('uri') ?? POST_TWO; + return jsonResponse({ + thread: { + $type: 'app.bsky.feed.defs#threadViewPost', + post: apiPost(uri, 'opened thread'), + replies: [], + }, + }); + } + return jsonResponse({ error: 'UnexpectedRequest', message: url.pathname }, 500); + }); + + const first = await runJson(database, ['following', ...authFlags(auth), '--limit', '2']); + expect(first.id).toBe('v1'); + expect(first.snapshot).toMatchObject({ + kind: 'feed', + limit: 2, + cursor: 'cursor-one', + source: { service: PDS, mode: 'authenticated', viewerDid: VIEWER_DID }, + }); + expect(JSON.stringify(first)).not.toContain(auth.password); + expect(JSON.stringify(first)).not.toContain(auth.accessValue); + + const firstOccurrenceRef = Object.keys(first.refs).find((ref) => ref.endsWith('-e1'))!; + const beforePeekRequests = requests.length; + expect(await runJson(database, ['peek', firstOccurrenceRef])).toEqual(first.refs[firstOccurrenceRef]); + expect(requests).toHaveLength(beforePeekRequests); + + const second = await runJson(database, ['more', ...authFlags(auth), '--limit', '1']); + expect(second.id).toBe('v2'); + expect(second.snapshot).toMatchObject({ + kind: 'feed', + limit: 1, + requestCursor: 'cursor-one', + cursor: 'cursor-two', + }); + const secondOccurrenceRef = Object.keys(second.refs).find((ref) => ref.endsWith('-e1'))!; + const opened = await runJson(database, [ + 'open', secondOccurrenceRef, ...authFlags(auth), '--depth', '0', '--parents', '0', '--max-nodes', '10', + ]); + expect(opened.snapshot).toMatchObject({ + kind: 'thread', + focusUri: POST_TWO, + encounter: { + feedViewId: 'v2', + occurrenceId: '1', + postUri: POST_TWO, + reason: { + kind: 'repost', + by: { did: REPOSTER_DID, handle: 'reposter.test', displayName: 'Reposter' }, + indexedAt: '2026-09-05T10:05:00.000Z', + }, + }, + }); + + const beforeBackRequests = requests.length; + expect(await runJson(database, ['back'])).toEqual(second); + expect(await runJson(database, ['peek', firstOccurrenceRef])).toEqual(first.refs[firstOccurrenceRef]); + expect(requests).toHaveLength(beforeBackRequests); + + const refreshed = await runJson(database, ['refresh', ...authFlags(auth), '--limit', '1']); + expect(refreshed.id).toBe('v4'); + expect(refreshed.snapshot).toMatchObject({ kind: 'feed', limit: 1, cursor: 'cursor-refresh' }); + expect(refreshed.snapshot.requestCursor).toBeUndefined(); + const timelineUrls = requests + .map((request) => new URL(request.url)) + .filter((url) => url.pathname.endsWith('/app.bsky.feed.getTimeline')); + expect(timelineUrls.map((url) => ({ limit: url.searchParams.get('limit'), cursor: url.searchParams.get('cursor') }))).toEqual([ + { limit: '2', cursor: null }, + { limit: '1', cursor: 'cursor-one' }, + { limit: '1', cursor: null }, + ]); + + const store = new ReadingStore(database); + expect(store.position('main').session).toEqual({ name: 'main', viewId: 'v4', history: ['v1', 'v2'] }); + expect(store.getView('v1')).toEqual(first); + expect(store.getView('v2')).toEqual(second); + store.close(); + }); + + test('reports end, cursor-loop, and network failures without moving the original feed', async () => { + const directory = temporaryDirectory(); + const noCursorDatabase = join(directory, 'no-cursor.sqlite'); + const auth = authFixture(); + const noCursorRequests = installFetch((request) => { + const url = new URL(request.url); + if (url.pathname.endsWith('/com.atproto.server.createSession')) return sessionResponse(auth); + if (url.pathname.endsWith('/app.bsky.feed.getTimeline')) { + return jsonResponse({ feed: [{ post: apiPost(POST_ONE, 'only page') }] }); + } + return jsonResponse({ error: 'UnexpectedRequest' }, 500); + }); + const endPage = await runJson(noCursorDatabase, ['following', ...authFlags(auth)]); + const requestsAtEnd = noCursorRequests.length; + await expect(runCli(['more', ...authFlags(auth), '--db', noCursorDatabase, '--json'])) + .rejects.toThrow('Current feed page has no next cursor; continuation is unavailable.'); + expect(noCursorRequests).toHaveLength(requestsAtEnd); + const endStore = new ReadingStore(noCursorDatabase); + expect(endStore.current('main')).toEqual(endPage); + expect(endStore.getView('v2')).toBeNull(); + endStore.close(); + + globalThis.fetch = originalFetch; + const loopDatabase = join(directory, 'loop.sqlite'); + let continuationReads = 0; + installFetch((request) => { + const url = new URL(request.url); + if (url.pathname.endsWith('/com.atproto.server.createSession')) return sessionResponse(auth); + if (url.pathname.endsWith('/app.bsky.feed.getTimeline')) { + if (!url.searchParams.has('cursor')) { + return jsonResponse({ cursor: 'loop-cursor', feed: [{ post: apiPost(POST_ONE, 'loop page') }] }); + } + continuationReads += 1; + return continuationReads === 1 + ? jsonResponse({ cursor: 'loop-cursor', feed: [{ post: apiPost(POST_TWO, 'looped page') }] }) + : jsonResponse({ error: 'UpstreamUnavailable', message: 'temporary failure' }, 503); + } + return jsonResponse({ error: 'UnexpectedRequest' }, 500); + }); + const loopPage = await runJson(loopDatabase, ['following', ...authFlags(auth)]); + await expect(runCli(['more', ...authFlags(auth), '--db', loopDatabase, '--json'])) + .rejects.toThrow('refusing a silent loop'); + await expect(runCli(['more', ...authFlags(auth), '--db', loopDatabase, '--json'])) + .rejects.toThrow('Fetching following feed failed'); + const loopStore = new ReadingStore(loopDatabase); + expect(loopStore.current('main')).toEqual(loopPage); + expect(loopStore.position('main').session.history).toEqual([]); + expect(loopStore.getView('v2')).toBeNull(); + loopStore.close(); + }); + + test('rejects a changed service or viewer after login but before cursor timeline retrieval', async () => { + const directory = temporaryDirectory(); + const auth = authFixture(); + const requests = installFetch((request) => { + const url = new URL(request.url); + if (url.pathname.endsWith('/com.atproto.server.createSession')) return sessionResponse(auth, OTHER_VIEWER_DID); + return jsonResponse({ error: 'TimelineMustNotRun', message: url.pathname }, 500); + }); + + const serviceDatabase = join(directory, 'service.sqlite'); + const serviceStore = new ReadingStore(serviceDatabase); + const serviceView = serviceStore.commit('main', storedFeed({ + service: 'https://stored.example', + mode: 'authenticated', + viewerDid: OTHER_VIEWER_DID, + }, 'stored-cursor'), serviceStore.position('main').revision); + serviceStore.close(); + await expect(runCli(['more', ...authFlags(auth), '--db', serviceDatabase, '--json'])) + .rejects.toThrow('Following-feed source service changed'); + + const viewerDatabase = join(directory, 'viewer.sqlite'); + const viewerStore = new ReadingStore(viewerDatabase); + const viewerView = viewerStore.commit('main', storedFeed({ + service: PDS, + mode: 'authenticated', + viewerDid: VIEWER_DID, + }, 'stored-cursor'), viewerStore.position('main').revision); + viewerStore.close(); + await expect(runCli(['more', ...authFlags(auth), '--db', viewerDatabase, '--json'])) + .rejects.toThrow('Following-feed viewer changed'); + + expect(requests.filter((request) => new URL(request.url).pathname.endsWith('/app.bsky.feed.getTimeline'))).toHaveLength(0); + const reopenedService = new ReadingStore(serviceDatabase); + const reopenedViewer = new ReadingStore(viewerDatabase); + expect(reopenedService.current('main')).toEqual(serviceView); + expect(reopenedViewer.current('main')).toEqual(viewerView); + expect(reopenedService.getView('v2')).toBeNull(); + expect(reopenedViewer.getView('v2')).toBeNull(); + reopenedService.close(); + reopenedViewer.close(); + }); +}); diff --git a/tests/feed-render.test.ts b/tests/feed-render.test.ts new file mode 100644 index 0000000..fc72fab --- /dev/null +++ b/tests/feed-render.test.ts @@ -0,0 +1,380 @@ +import { afterAll, beforeAll, describe, expect, test } from 'bun:test'; +import { mkdtemp, readFile, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { chromium, type Browser } from 'playwright'; +import type { FeedSnapshot, PostNode, ReadingView, ThreadSnapshot } from '../src/model.ts'; +import { captureView, renderHtml, renderText } from '../src/render.ts'; +import { ReadingStore } from '../src/store.ts'; + +const fetchedAt = '2026-09-05T16:02:34.000Z'; +const source = { + mode: 'authenticated' as const, + service: 'https://pds.example', + viewerDid: 'did:plc:feedviewer', +}; + +function post(id: string, overrides: Partial = {}): PostNode { + return { + uri: `at://did:plc:${id}/app.bsky.feed.post/${id}`, + availability: 'available', + author: { did: `did:plc:${id}`, handle: `${id}.example`, displayName: id }, + text: `Original speech from ${id}.`, + createdAt: '2026-09-05T15:02:34.000Z', + indexedAt: '2026-09-05T15:02:36.000Z', + replies: [], + repliesFetched: false, + facets: [], + media: [], + quotes: [], + cards: [], + labels: [], + unsupported: [], + counts: {}, + ...overrides, + }; +} + +function feedSnapshot(entries: FeedSnapshot['entries'], nodes: PostNode[]): FeedSnapshot { + return { + kind: 'feed', + feed: 'following', + fetchedAt, + source, + entries, + nodes, + limit: 20, + cursor: 'opaque-next-page', + maxNodes: 600, + locallyTruncated: false, + warnings: [], + }; +} + +function storedView(snapshot: FeedSnapshot | ThreadSnapshot, session = 'feed-render'): ReadingView { + const store = new ReadingStore(':memory:'); + try { + const position = store.position(session); + return store.commit(session, snapshot, position.revision); + } finally { + store.close(); + } +} + +let browser: Browser; +beforeAll(async () => { browser = await chromium.launch(); }); +afterAll(async () => { await browser?.close(); }); + +describe('following-feed rendering', () => { + test('keeps duplicate occurrences distinct while provenance, refs, and engagement stay compact and exact', async () => { + const node = post('shared', { + text: 'One canonical post surfaced twice.', + counts: { replies: 0, likes: 3_327, reposts: 920 }, + }); + const snapshot = feedSnapshot([ + { id: '1', postUri: node.uri }, + { + id: '2', + postUri: node.uri, + reason: { + kind: 'repost', + by: { did: 'did:plc:reposter', handle: 'reposter.example', displayName: 'Reposter' }, + indexedAt: '2026-09-05T15:32:34.000Z', + }, + }, + ], [node]); + const view = storedView(snapshot); + const original = JSON.stringify(view); + const text = renderText(view); + expect(text).toContain('Occurrence ID: 1'); + expect(text).toContain('Occurrence ID: 2'); + expect(text).toContain('Reason actor: Reposter'); + expect(text.match(/One canonical post surfaced twice\./gu)).toHaveLength(2); + + const page = await browser.newPage({ viewport: { width: 1280, height: 960 } }); + try { + await page.setContent(renderHtml(view)); + const cards = page.locator('.feed-card'); + expect(await cards.count()).toBe(2); + expect(await cards.evaluateAll((elements) => elements.map((element) => element.getAttribute('data-feed-occurrence')))).toEqual(['1', '2']); + expect(await cards.nth(0).locator('.feed-reason').count()).toBe(0); + expect(await cards.nth(1).locator('.feed-reason').innerText()).toContain('Reposted by'); + expect(await cards.nth(1).locator('.feed-reason').innerText()).toContain('Reposter'); + const ordinaryReferenceStyle = await cards.nth(0).locator('.feed-author-identity .reference').evaluate((element) => { + const style = getComputedStyle(element); + return { color: style.color, backgroundColor: style.backgroundColor }; + }); + const reasonReferenceStyle = await cards.nth(1).locator('.feed-reason .reference').evaluate((element) => { + const style = getComputedStyle(element); + return { color: style.color, backgroundColor: style.backgroundColor }; + }); + expect(reasonReferenceStyle).toEqual(ordinaryReferenceStyle); + expect(reasonReferenceStyle.color).not.toBe(reasonReferenceStyle.backgroundColor); + expect(await cards.nth(0).innerText()).toContain('[v1-e1]'); + expect(await cards.nth(1).innerText()).toContain('[v1-e2]'); + expect(await cards.nth(0).innerText()).toContain('[v1-p1]'); + expect(await cards.nth(1).innerText()).toContain('[v1-p1]'); + expect(await cards.nth(0).innerText()).toContain('1h ago'); + expect(await cards.nth(0).innerText()).not.toContain('before page entry'); + expect(await cards.nth(0).locator('.feed-count strong').allTextContents()).toEqual(['0', '3.3K', '920', '—']); + expect(await cards.nth(0).locator('.feed-record-details').textContent()).toContain('Likes 3327'); + expect(await cards.nth(0).locator('.feed-copy.body').evaluate((element) => Number.parseFloat(getComputedStyle(element).fontSize))).toBeGreaterThanOrEqual(16); + expect(await page.locator('.feed-card .reference').evaluateAll((elements) => elements.every((element) => getComputedStyle(element).textTransform === 'none'))).toBe(true); + expect(await page.locator('.feed-card .reference').evaluateAll((elements) => elements.every((element) => element.textContent === element.textContent?.toLowerCase()))).toBe(true); + expect(await page.evaluate(() => document.documentElement.scrollWidth <= document.documentElement.clientWidth)).toBe(true); + } finally { + await page.close(); + } + expect(JSON.stringify(view)).toBe(original); + }); + + test('keeps feed prose, reason, identity, alt, and external preview data inert without changing exact source', async () => { + const injected = ''; + const node = post('unsafe', { + author: { + did: 'did:plc:unsafe', + handle: 'unsafe.example', + displayName: injected, + avatar: 'javascript:globalThis.feedSourceRan=true', + }, + text: injected, + media: [{ kind: 'image', url: 'javascript:globalThis.feedSourceRan=true', alt: injected }], + cards: [{ uri: 'javascript:globalThis.feedSourceRan=true', title: injected, description: injected }], + }); + const view = storedView(feedSnapshot([{ + id: '1', + postUri: node.uri, + reason: { + kind: 'unknown', + type: injected, + by: { did: 'did:plc:reason', handle: 'reason.example', displayName: injected }, + }, + }], [node]), 'unsafe-feed'); + const original = JSON.stringify(view); + const html = renderHtml(view); + const page = await browser.newPage(); + try { + await page.setContent(html); + expect(await page.locator('script, iframe, [onerror], [onload]').count()).toBe(0); + expect(await page.locator('.feed-card').innerText()).toContain(injected); + expect(await page.evaluate(() => 'feedSourceRan' in globalThis)).toBe(false); + expect(html).toContain("default-src 'none'"); + expect(html).toContain('img-src https://cdn.bsky.app'); + } finally { + await page.close(); + } + expect(renderText(view)).toContain(injected); + expect(JSON.stringify(view)).toBe(original); + }); + + test('uses shallow parent and quote excerpts while one disclosure retains every exact original text', async () => { + const primaryText = `Primary exact text: ${'long original speech '.repeat(30)}`; + const parentText = `Parent exact text: ${'earlier context '.repeat(20)}`; + const quoteText = `Quote exact text: ${'another voice '.repeat(20)}`; + const rootText = 'Hydrated root text retained in exact details without another feed card.'; + const parent = post('parent', { text: parentText }); + const root = post('root', { text: rootText }); + const quote = post('quote', { text: quoteText }); + const primary = post('focus', { + text: primaryText, + parentUri: parent.uri, + rootUri: root.uri, + quotes: [quote.uri], + }); + const view = storedView(feedSnapshot([ + { id: '1', postUri: primary.uri, parentUri: parent.uri, rootUri: root.uri }, + ], [primary, parent, root, quote])); + const text = renderText(view); + for (const exact of [primaryText, parentText, quoteText, rootText]) expect(text).toContain(exact); + + const page = await browser.newPage({ viewport: { width: 1280, height: 960 } }); + try { + await page.setContent(renderHtml(view)); + expect(await page.locator('[data-panel-block]').count()).toBe(1); + expect(await page.locator('.feed-context-stack > .feed-glimpse').count()).toBe(2); + expect(await page.locator('[data-excerpted="true"]').count()).toBe(3); + expect(await page.locator('.feed-copy.body.excerpted').evaluate((element) => getComputedStyle(element).webkitLineClamp)).toBe('6'); + expect(await page.locator('.feed-copy.glimpse.excerpted').evaluateAll((elements) => elements.map((element) => getComputedStyle(element).webkitLineClamp))).toEqual(['2', '2']); + const details = page.locator('.feed-record-details'); + expect(await details.getAttribute('open')).toBeNull(); + const retained = await details.textContent(); + for (const exact of [primaryText, parentText, quoteText, rootText]) expect(retained).toContain(exact); + expect(await page.locator('.feed-context-stack').innerText()).not.toContain(rootText); + expect(await page.locator('.feed-glimpse .reference').evaluateAll((elements) => elements.every((element) => getComputedStyle(element).textTransform === 'none'))).toBe(true); + } finally { + await page.close(); + } + }); + + test('bounds galleries and external previews while unknown, zero, large, and unavailable context remain distinct', async () => { + const primary = post('bounded', { + text: '', + counts: { replies: 0, reposts: 1_000_000, quotes: 0 }, + parentUri: 'at://did:plc:missing/app.bsky.feed.post/parent', + media: [ + { kind: 'image', width: 640, height: 480, alt: 'first' }, + { kind: 'video', width: 1920, height: 1080 }, + { kind: 'image', alt: '' }, + { kind: 'image' }, + ], + cards: [ + { uri: 'https://example.invalid/one', title: 'First card', description: 'First exact description' }, + { uri: 'https://example.invalid/two', title: 'Second card', description: 'Second exact description' }, + ], + }); + const view = storedView(feedSnapshot([ + { id: '1', postUri: primary.uri, parentUri: primary.parentUri }, + ], [primary])); + const page = await browser.newPage({ viewport: { width: 1280, height: 960 } }); + try { + await page.setContent(renderHtml(view)); + expect(await page.locator('.feed-card > .empty-copy').count()).toBe(0); + expect(await page.locator('.feed-media .media-item').count()).toBe(2); + expect(await page.locator('.feed-media').innerText()).toContain('2 more media previews omitted'); + expect(await page.locator('.feed-media').innerText()).toContain('[v1-m3]'); + expect(await page.locator('.feed-media').innerText()).toContain('[v1-m4]'); + expect(await page.locator('.feed-media').textContent()).toContain('Video poster · not playback'); + expect(await page.locator('.feed-link-preview').count()).toBe(1); + expect(await page.locator('.feed-links').innerText()).toContain('1 more external-card preview omitted'); + expect(await page.locator('.feed-glimpse-missing').innerText()).toContain('Parent text unavailable; this occurrence remains a reply.'); + expect(await page.locator('.feed-count strong').allTextContents()).toEqual(['0', '—', '1M', '0']); + const visible = await page.locator('.feed-card').innerText(); + expect(visible).not.toContain('640 × 480'); + const details = await page.locator('.feed-record-details').textContent(); + expect(details).toContain('Text is present and empty.'); + expect(details).toContain('640 × 480'); + expect(details).toContain('Reposts 1000000'); + expect(details).toContain('Second exact description'); + } finally { + await page.close(); + } + }); + + test('renders honest empty and unavailable feed surfaces without invented values', async () => { + const emptySnapshot = feedSnapshot([], []); + delete emptySnapshot.cursor; + const empty = storedView(emptySnapshot, 'empty-feed'); + expect(renderText(empty)).toContain('FEED OCCURRENCES: '); + expect(renderText(empty)).toContain('Next cursor: '); + const emptyPage = await browser.newPage(); + try { + await emptyPage.setContent(renderHtml(empty)); + expect(await emptyPage.locator('.feed-empty').innerText()).toContain('No feed occurrences supplied'); + expect(await emptyPage.locator('.feed-card').count()).toBe(0); + } finally { + await emptyPage.close(); + } + + const blocked = post('blocked', { + availability: 'blocked', + author: undefined, + text: undefined, + counts: {}, + }); + const unavailable = storedView(feedSnapshot([{ id: '1', postUri: blocked.uri }], [blocked]), 'blocked-feed'); + const unavailablePage = await browser.newPage(); + try { + await unavailablePage.setContent(renderHtml(unavailable)); + const card = unavailablePage.locator('.feed-card.unavailable'); + expect(await card.innerText()).toContain('Post availability: blocked'); + expect(await card.innerText()).toContain('Author identity not supplied'); + expect(await card.innerText()).toContain('Post text was not supplied.'); + expect(await card.locator('.feed-count strong').allTextContents()).toEqual(['—', '—', '—', '—']); + } finally { + await unavailablePage.close(); + } + }); + + test('adds an encounter breadcrumb only to threads opened from a feed occurrence', async () => { + const focus = post('thread-focus'); + const snapshot: ThreadSnapshot = { + kind: 'thread', + requested: focus.uri, + focusUri: focus.uri, + fetchedAt, + source, + nodes: [focus], + ancestors: [], + replyOrder: 'source', + limits: { depth: 40, parentHeight: 40, maxNodes: 60 }, + locallyTruncated: false, + warnings: [], + encounter: { + feedViewId: 'v7', + occurrenceId: '14', + postUri: focus.uri, + reason: { + kind: 'repost', + by: { did: 'did:plc:encounter', handle: 'encounter.example', displayName: 'Encounterer' }, + indexedAt: '2026-09-05T15:32:34.000Z', + }, + }, + }; + const encountered = storedView(snapshot, 'encountered-thread'); + expect(renderText(encountered)).toContain('Encounter feed view: v7'); + expect(renderText(encountered)).toContain('Encounter occurrence ID: 14'); + expect(renderText(encountered)).toContain('Encounter Reason actor: Encounterer'); + const page = await browser.newPage(); + try { + await page.setContent(renderHtml(encountered)); + const breadcrumb = page.locator('.encounter-breadcrumb'); + expect(await breadcrumb.innerText()).toContain('View v7 · occurrence 14'); + expect(await breadcrumb.innerText()).toContain('Reposted by'); + expect(await breadcrumb.innerText()).toContain('Encounterer'); + expect(await page.locator('[data-panel-block]').count()).toBe(1); + } finally { + await page.close(); + } + + const plainSnapshot = structuredClone(snapshot); + delete plainSnapshot.encounter; + const plain = storedView(plainSnapshot, 'plain-thread'); + expect(renderText(plain)).not.toContain('Encounter feed view:'); + const plainPage = await browser.newPage(); + try { + await plainPage.setContent(renderHtml(plain)); + expect(await plainPage.locator('.encounter-breadcrumb').count()).toBe(0); + } finally { + await plainPage.close(); + } + }); + + test('wraps an unbroken overview warning without widening the reading surface', async () => { + const node = post('warning'); + const snapshot = feedSnapshot([{ id: '1', postUri: node.uri }], [node]); + const warning = `Warning:${'X'.repeat(10_000)}`; + snapshot.warnings = [warning]; + const view = storedView(snapshot, 'warning-feed'); + expect(renderText(view)).toContain(warning); + const page = await browser.newPage({ viewport: { width: 1280, height: 960 } }); + try { + await page.setContent(renderHtml(view)); + expect(await page.locator('.notice').innerText()).toBe(warning); + expect(await page.evaluate(() => document.documentElement.scrollWidth <= document.documentElement.clientWidth)).toBe(true); + expect(await page.locator('.notice').evaluate((element) => element.scrollWidth <= element.clientWidth)).toBe(true); + } finally { + await page.close(); + } + }); + + test('captures five ordinary entries in one readable panel with paired exact source outputs', async () => { + const nodes = Array.from({ length: 5 }, (_, index) => post(`ordinary-${index + 1}`)); + const entries = nodes.map((node, index) => ({ id: String(index + 1), postUri: node.uri })); + const view = storedView(feedSnapshot(entries, nodes), 'capture-feed'); + const directory = await mkdtemp(join(tmpdir(), 'perch-feed-render-')); + try { + const files = await captureView(view, { outputDir: directory }); + expect(files.images.filter((path) => path.includes('-panel-'))).toHaveLength(1); + expect(JSON.parse(await readFile(files.json, 'utf8'))).toEqual(view); + expect(await readFile(files.text, 'utf8')).toBe(renderText(view)); + const html = await readFile(files.html, 'utf8'); + expect(html).toContain('Following feed in supplied source order'); + expect(html).toContain("default-src 'none'"); + const png = await readFile(files.images.find((path) => path.includes('-panel-'))!); + expect(png.subarray(0, 8)).toEqual(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])); + expect(png.readUInt32BE(16)).toBeGreaterThan(1_000); + } finally { + await rm(directory, { recursive: true, force: true }); + } + }, 30_000); +}); diff --git a/tests/feed-state.test.ts b/tests/feed-state.test.ts new file mode 100644 index 0000000..835652c --- /dev/null +++ b/tests/feed-state.test.ts @@ -0,0 +1,201 @@ +import { afterEach, describe, expect, test } from 'bun:test'; +import { mkdtempSync, rmSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import type { FeedSnapshot, PostNode, ThreadSnapshot } from '../src/model.ts'; +import { ReadingStore, StoreConflictError } from '../src/store.ts'; + +const temporaryDirectories: string[] = []; +const AUTHOR_DID = 'did:plc:ragtjsm2j2vknwkz3zp4oxrd'; +const REPOSTER_DID = 'did:plc:yckmmocpnqkrdwkp2q5rdipl'; +const VIEWER_DID = 'did:plc:ewvi7nxzyoun6zhxrhs64oiz'; +const POST_URI = `at://${AUTHOR_DID}/app.bsky.feed.post/repeated`; +const PARENT_URI = `at://${REPOSTER_DID}/app.bsky.feed.post/parent`; +const ROOT_URI = `at://${REPOSTER_DID}/app.bsky.feed.post/root`; + +function temporaryStorePath(): string { + const directory = mkdtempSync(join(tmpdir(), 'perch-feed-state-')); + temporaryDirectories.push(directory); + return join(directory, 'reader.sqlite'); +} + +function postNode(uri: string, text: string): PostNode { + return { + uri, + availability: 'available', + author: { did: AUTHOR_DID, handle: 'author.test', displayName: 'Author' }, + text, + createdAt: '2026-09-05T10:00:00.000Z', + indexedAt: '2026-09-05T10:00:01.000Z', + replies: [], + repliesFetched: false, + facets: [], + media: [], + quotes: [], + cards: [], + labels: [], + unsupported: [], + counts: {}, + }; +} + +function feedSnapshot(marker: string, postUri = POST_URI): FeedSnapshot { + const primary = postNode(postUri, `feed ${marker}`); + primary.parentUri = PARENT_URI; + primary.rootUri = ROOT_URI; + return { + kind: 'feed', + feed: 'following', + fetchedAt: `2026-09-05T10:0${marker.length}:00.000Z`, + source: { + service: 'https://pds.example', + mode: 'authenticated', + viewerDid: VIEWER_DID, + }, + entries: [ + { + id: '1', + postUri, + reason: { + kind: 'repost', + by: { did: REPOSTER_DID, handle: 'reposter.test', displayName: 'Reposter' }, + indexedAt: '2026-09-05T10:02:00.000Z', + }, + parentUri: PARENT_URI, + rootUri: ROOT_URI, + }, + { id: '2', postUri }, + ], + nodes: [primary], + limit: 20, + cursor: `cursor-${marker}`, + maxNodes: 600, + locallyTruncated: false, + warnings: [], + }; +} + +function legacyThreadSnapshot(): ThreadSnapshot { + const uri = `at://${AUTHOR_DID}/app.bsky.feed.post/legacy`; + return { + kind: 'thread', + requested: uri, + focusUri: uri, + fetchedAt: '2026-09-05T09:00:00.000Z', + source: { service: 'https://public.example', mode: 'public' }, + nodes: [postNode(uri, 'legacy thread')], + ancestors: [], + replyOrder: 'source', + limits: { depth: 3, parentHeight: 40, maxNodes: 60 }, + locallyTruncated: false, + warnings: [], + }; +} + +afterEach(() => { + for (const directory of temporaryDirectories.splice(0)) rmSync(directory, { recursive: true, force: true }); +}); + +describe('feed view persistence and references', () => { + test('keeps duplicate occurrences distinct while canonical records, back pages, and forks remain immutable', () => { + const path = temporaryStorePath(); + const store = new ReadingStore(path); + const mutableFirst = feedSnapshot('first'); + const first = store.commit('main', mutableFirst, store.position('main').revision); + if (first.snapshot.kind !== 'feed') throw new Error('Expected a committed feed snapshot.'); + const firstSnapshot = first.snapshot; + + expect(first.refs['v1-e1']).toEqual({ + kind: 'occurrence', + value: '1', + label: 'Feed occurrence 1: post by @author.test', + }); + expect(first.refs['v1-e2']).toEqual({ + kind: 'occurrence', + value: '2', + label: 'Feed occurrence 2: post by @author.test', + }); + expect(Object.values(first.refs).filter((target) => target.kind === 'occurrence')).toHaveLength(2); + expect(Object.values(first.refs).filter((target) => target.kind === 'post' && target.value === POST_URI)).toHaveLength(1); + expect(Object.values(first.refs)).toContainEqual({ + kind: 'profile', + value: REPOSTER_DID, + label: 'Reposter', + }); + expect(Object.values(first.refs)).toContainEqual({ kind: 'post', value: PARENT_URI, label: 'Known parent post' }); + expect(Object.values(first.refs)).toContainEqual({ kind: 'post', value: ROOT_URI, label: 'Known root post' }); + + mutableFirst.entries[0].postUri = 'at://did:plc:changed/app.bsky.feed.post/changed'; + mutableFirst.nodes[0].text = 'changed after commit'; + expect(firstSnapshot).not.toEqual(mutableFirst); + expect(firstSnapshot.entries[0].postUri).toBe(POST_URI); + expect(Object.isFrozen(firstSnapshot)).toBe(true); + expect(Object.isFrozen(firstSnapshot.entries[0])).toBe(true); + + const nextUri = `at://${AUTHOR_DID}/app.bsky.feed.post/next-page`; + const second = store.commit('main', feedSnapshot('second', nextUri), store.position('main').revision); + expect(second.refs['v2-e1']).toMatchObject({ kind: 'occurrence', value: '1' }); + expect(store.resolveRef('v1-e1')).toEqual({ view: first, ref: 'v1-e1', target: first.refs['v1-e1'] }); + expect(store.resolveRef('v2-e1')).toEqual({ view: second, ref: 'v2-e1', target: second.refs['v2-e1'] }); + + const forked = store.fork('main', 'research'); + expect(forked.view).toEqual(second); + expect(store.back('research', forked.revision)).toEqual(first); + expect(store.current('main')).toEqual(second); + expect(store.position('main').session.history).toEqual([first.id]); + expect(store.position('research').session.history).toEqual([]); + expect(store.back('main', store.position('main').revision)).toEqual(first); + expect(store.resolveRef('v2-e1').view).toEqual(second); + store.close(); + + const reopened = new ReadingStore(path); + expect(reopened.current('main')).toEqual(first); + expect(reopened.current('research')).toEqual(first); + expect(reopened.resolveRef('v1-e2').target.value).toBe('2'); + expect(reopened.resolveRef('v2-e1').target.value).toBe('1'); + reopened.close(); + }); + + test('rolls back stale feed commits without consuming a view id or changing either page', () => { + const path = temporaryStorePath(); + const firstHandle = new ReadingStore(path); + const secondHandle = new ReadingStore(path); + const winnerBaseline = firstHandle.position('shared'); + const staleBaseline = secondHandle.position('shared'); + + const winner = firstHandle.commit('shared', feedSnapshot('winner'), winnerBaseline.revision); + expect(() => secondHandle.commit('shared', feedSnapshot('stale'), staleBaseline.revision)) + .toThrow(StoreConflictError); + expect(secondHandle.position('shared')).toEqual({ + session: { name: 'shared', viewId: winner.id, history: [] }, + revision: 1, + view: winner, + }); + expect(secondHandle.getView('v2')).toBeNull(); + + const independent = secondHandle.commit('other', feedSnapshot('other'), secondHandle.position('other').revision); + expect(independent.id).toBe('v2'); + expect(firstHandle.current('shared')).toEqual(winner); + expect(firstHandle.position('shared').session.history).toEqual([]); + firstHandle.close(); + secondHandle.close(); + }); + + test('reopens pre-feed thread JSON without rewriting its shape or references', () => { + const path = temporaryStorePath(); + const store = new ReadingStore(path); + const legacy = store.commit('legacy', legacyThreadSnapshot(), store.position('legacy').revision); + const legacyJson = JSON.stringify(legacy); + store.commit('feed', feedSnapshot('new'), store.position('feed').revision); + store.close(); + + const reopened = new ReadingStore(path); + const restored = reopened.getView(legacy.id); + expect(JSON.stringify(restored)).toBe(legacyJson); + expect(restored?.snapshot.kind).toBe('thread'); + expect(restored && 'encounter' in restored.snapshot).toBe(false); + const postRef = Object.keys(legacy.refs).find((ref) => ref.includes('-p'))!; + expect(reopened.resolveRef(postRef)).toEqual({ view: legacy, ref: postRef, target: legacy.refs[postRef] }); + reopened.close(); + }); +}); diff --git a/tests/feed.test.ts b/tests/feed.test.ts new file mode 100644 index 0000000..0189d92 --- /dev/null +++ b/tests/feed.test.ts @@ -0,0 +1,538 @@ +import { afterEach, describe, expect, test } from 'bun:test'; +import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { createReader, normalizeFeed } from '../src/atproto.ts'; + +const VIEWER_DID = 'did:plc:ewvi7nxzyoun6zhxrhs64oiz'; +const AUTHOR_DID = 'did:plc:ragtjsm2j2vknwkz3zp4oxrd'; +const OTHER_DID = 'did:plc:js47frzswl2ezb6v235hlcz2'; +const REPOSTER_DID = 'did:plc:yckmmocpnqkrdwkp2q5rdipl'; +const CID = 'bafyreigh2akiscaildcw453k5p2q5w2dmqnj4dnrz3llrqmk5f3x7tdpiy'; +const POST_URI = `at://${AUTHOR_DID}/app.bsky.feed.post/primary`; +const SECOND_URI = `at://${OTHER_DID}/app.bsky.feed.post/second`; +const PARENT_URI = `at://${OTHER_DID}/app.bsky.feed.post/parent`; +const ROOT_URI = `at://${OTHER_DID}/app.bsky.feed.post/root`; +const QUOTE_URI = `at://${OTHER_DID}/app.bsky.feed.post/quote`; +const SOURCE = { + service: 'https://pds.example', + mode: 'authenticated' as const, + viewerDid: VIEWER_DID, +}; +const originalFetch = globalThis.fetch; +const temporaryDirectories: string[] = []; + +type ApiObject = Record; +type FetchResponder = (request: Request) => Response | Promise; + +function apiPost( + uri: string, + text: string, + options: { authorDid?: string; record?: ApiObject; view?: ApiObject } = {}, +): ApiObject { + const authorDid = options.authorDid ?? AUTHOR_DID; + return { + $type: 'app.bsky.feed.defs#postView', + uri, + cid: CID, + author: { + did: authorDid, + handle: `${authorDid.slice('did:plc:'.length)}.test`, + displayName: `Display ${authorDid.slice('did:plc:'.length)}`, + }, + record: { + $type: 'app.bsky.feed.post', + text, + createdAt: '2026-09-05T10:00:00.000Z', + ...options.record, + }, + indexedAt: '2026-09-05T10:00:01.000Z', + ...options.view, + }; +} + +function jsonResponse(data: unknown, status = 200): Response { + return new Response(JSON.stringify(data), { + status, + headers: { 'content-type': 'application/json' }, + }); +} + +function installFetch(responder: FetchResponder): Request[] { + const requests: Request[] = []; + globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => { + const request = input instanceof Request && init === undefined ? input : new Request(input, init); + requests.push(request.clone()); + return responder(request); + }) as typeof fetch; + return requests; +} + +function temporaryAuthConfig(identifier: string, password: string): string { + const directory = mkdtempSync(join(tmpdir(), 'perch-feed-auth-')); + temporaryDirectories.push(directory); + const path = join(directory, 'mcp.json'); + writeFileSync(path, JSON.stringify({ + mcpServers: { + atproto: { + env: { + BSKY_IDENTIFIER: identifier, + BSKY_APP_PASSWORD: password, + }, + }, + }, + }), { mode: 0o600 }); + return path; +} + +afterEach(() => { + globalThis.fetch = originalFetch; + for (const directory of temporaryDirectories.splice(0)) rmSync(directory, { recursive: true, force: true }); +}); + +describe('normalizeFeed', () => { + test('preserves source-ordered occurrences separately from canonical posts and supplied context', () => { + const parent = apiPost(PARENT_URI, 'Exact hydrated parent', { authorDid: OTHER_DID }); + const root = apiPost(ROOT_URI, 'Exact hydrated root', { authorDid: OTHER_DID }); + const primary = apiPost(POST_URI, 'Exact primary speech', { + record: { + facets: [{ + index: { byteStart: 0, byteEnd: 5 }, + features: [{ $type: 'app.bsky.richtext.facet#tag', tag: 'Exact' }], + }], + reply: { + parent: { uri: PARENT_URI, cid: 'parent-cid' }, + root: { uri: ROOT_URI, cid: 'root-cid' }, + }, + embed: { + $type: 'app.bsky.embed.record', + record: { uri: QUOTE_URI, cid: 'quote-cid' }, + }, + }, + view: { + replyCount: 87, + likeCount: 3327, + repostCount: 920, + quoteCount: 4, + embed: { + $type: 'app.bsky.embed.images#view', + images: [ + null, + { + fullsize: 'https://cdn.example/full.jpg', + thumb: 'https://cdn.example/thumb.jpg', + alt: 'Exact image alt', + aspectRatio: { width: 1200, height: 800 }, + }, + ], + }, + }, + }); + const second = apiPost(SECOND_URI, 'Second exact speech', { + authorDid: OTHER_DID, + view: { + embed: { + $type: 'app.bsky.embed.external#view', + external: { + uri: 'https://example.invalid/article', + title: 'Exact card title', + description: 'Exact card description', + }, + }, + }, + }); + const response = { + cursor: 'opaque-next-cursor', + feed: [ + { + post: primary, + reply: { parent, root }, + reason: { + $type: 'app.bsky.feed.defs#reasonRepost', + by: { did: REPOSTER_DID, handle: 'reposter.test', displayName: 'Reposter' }, + indexedAt: '2026-09-05T10:05:00.000Z', + }, + }, + { + post: primary, + reason: { + $type: 'com.example.feed#reasonSignal', + by: { did: OTHER_DID, handle: 'other.test', displayName: 'Other' }, + indexedAt: '2026-09-05T10:06:00.000Z', + }, + }, + { + post: second, + reason: { $type: 'app.bsky.feed.defs#reasonPin' }, + }, + ], + }; + + const snapshot = normalizeFeed(response, { + fetchedAt: '2026-09-05T10:10:00.000Z', + source: SOURCE, + limit: 20, + cursor: 'opaque-request-cursor', + }); + const nodes = new Map(snapshot.nodes.map((node) => [node.uri, node])); + + expect(snapshot.entries.map(({ id, postUri }) => ({ id, postUri }))).toEqual([ + { id: '1', postUri: POST_URI }, + { id: '2', postUri: POST_URI }, + { id: '3', postUri: SECOND_URI }, + ]); + expect(snapshot.entries[0]).toEqual({ + id: '1', + postUri: POST_URI, + reason: { + kind: 'repost', + by: { did: REPOSTER_DID, handle: 'reposter.test', displayName: 'Reposter' }, + indexedAt: '2026-09-05T10:05:00.000Z', + }, + parentUri: PARENT_URI, + rootUri: ROOT_URI, + }); + expect(snapshot.entries[1].reason).toEqual({ + kind: 'unknown', + type: 'com.example.feed#reasonSignal', + by: { did: OTHER_DID, handle: 'other.test', displayName: 'Other' }, + indexedAt: '2026-09-05T10:06:00.000Z', + }); + expect(snapshot.entries[2].reason).toEqual({ kind: 'pin' }); + expect(snapshot.nodes.filter((node) => node.uri === POST_URI)).toHaveLength(1); + expect(nodes.get(POST_URI)).toMatchObject({ + text: 'Exact primary speech', + createdAt: '2026-09-05T10:00:00.000Z', + indexedAt: '2026-09-05T10:00:01.000Z', + parentUri: PARENT_URI, + rootUri: ROOT_URI, + counts: { replies: 87, likes: 3327, reposts: 920, quotes: 4 }, + media: [{ + kind: 'image', + url: 'https://cdn.example/full.jpg', + thumbnail: 'https://cdn.example/thumb.jpg', + alt: 'Exact image alt', + width: 1200, + height: 800, + }], + quotes: [QUOTE_URI], + }); + expect(nodes.get(POST_URI)?.unsupported).toContain('app.bsky.embed.images#view:image-1-malformed'); + expect(nodes.get(POST_URI)?.facets[0]?.targets[0]).toEqual({ + kind: 'tag', + value: 'Exact', + label: 'Exact', + ownerUri: POST_URI, + index: 0, + }); + expect(nodes.get(PARENT_URI)?.text).toBe('Exact hydrated parent'); + expect(nodes.get(PARENT_URI)?.replies).toContain(POST_URI); + expect(nodes.get(ROOT_URI)?.text).toBe('Exact hydrated root'); + expect(nodes.get(QUOTE_URI)).toMatchObject({ + uri: QUOTE_URI, + availability: 'unsupported', + }); + expect(nodes.get(QUOTE_URI)?.text).toBeUndefined(); + expect(nodes.get(SECOND_URI)?.cards).toEqual([{ + uri: 'https://example.invalid/article', + title: 'Exact card title', + description: 'Exact card description', + }]); + expect(nodes.get(SECOND_URI)?.counts.likes).toBeUndefined(); + expect(snapshot).toMatchObject({ + kind: 'feed', + feed: 'following', + fetchedAt: '2026-09-05T10:10:00.000Z', + source: SOURCE, + limit: 20, + cursor: 'opaque-next-cursor', + requestCursor: 'opaque-request-cursor', + maxNodes: 600, + locallyTruncated: false, + warnings: [], + }); + }); + + test('reserves primary posts before applying the 600-node optional-context bound', () => { + let nestedQuote: ApiObject | undefined; + for (let index = 620; index >= 1; index -= 1) { + const uri = `at://${OTHER_DID}/app.bsky.feed.post/quote-${index}`; + nestedQuote = { + $type: 'app.bsky.embed.record#viewRecord', + uri, + cid: `cid-quote-${index}`, + author: { did: OTHER_DID, handle: 'other.test', displayName: 'Other' }, + value: { + $type: 'app.bsky.feed.post', + text: `quote ${index}`, + createdAt: '2026-09-05T09:00:00.000Z', + }, + embeds: nestedQuote + ? [{ $type: 'app.bsky.embed.record#view', record: nestedQuote }] + : [], + }; + } + const primaryUris = [POST_URI, SECOND_URI, `at://${AUTHOR_DID}/app.bsky.feed.post/third`]; + const feed = primaryUris.map((uri, index) => ({ + post: apiPost(uri, `primary ${index + 1}`, index === 0 + ? { view: { embed: { $type: 'app.bsky.embed.record#view', record: nestedQuote } } } + : {}), + })); + + const snapshot = normalizeFeed({ feed }, { + fetchedAt: '2026-09-05T10:10:00.000Z', + source: SOURCE, + limit: 3, + }); + + expect(snapshot.entries).toHaveLength(3); + expect(snapshot.nodes).toHaveLength(600); + expect(snapshot.nodes.slice(0, 3).map((node) => node.uri)).toEqual(primaryUris); + expect(primaryUris.every((uri) => snapshot.nodes.some((node) => node.uri === uri))).toBe(true); + expect(snapshot.locallyTruncated).toBe(true); + expect(snapshot.warnings).toContain('Local feed maxNodes omitted one or more supplied context or quote nodes.'); + }); + + test('rejects malformed primary identities while preserving an honest empty page and unusable cursor cue', () => { + expect(() => normalizeFeed({ feed: [{}] }, { + fetchedAt: '2026-09-05T10:10:00.000Z', + source: SOURCE, + limit: 20, + })).toThrow('Timeline occurrence 1 omitted a usable canonical post URI'); + expect(() => normalizeFeed({ feed: [{ post: apiPost('at://did:plc:test/app.bsky.actor.profile/not-a-post', 'bad') }] }, { + fetchedAt: '2026-09-05T10:10:00.000Z', + source: SOURCE, + limit: 20, + })).toThrow('Timeline occurrence 1 omitted a usable canonical post URI'); + expect(() => normalizeFeed({ feed: [{ post: apiPost(`${POST_URI}/extra`, 'bad') }] }, { + fetchedAt: '2026-09-05T10:10:00.000Z', + source: SOURCE, + limit: 20, + })).toThrow('Timeline occurrence 1 omitted a usable canonical post URI'); + for (const reservedKey of ['.', '..']) { + expect(() => normalizeFeed({ feed: [{ + post: apiPost(`at://${AUTHOR_DID}/app.bsky.feed.post/${reservedKey}`, 'bad'), + }] }, { + fetchedAt: '2026-09-05T10:10:00.000Z', + source: SOURCE, + limit: 20, + })).toThrow('Timeline occurrence 1 omitted a usable canonical post URI'); + } + expect(() => normalizeFeed({ feed: [{ + post: apiPost(`at://${AUTHOR_DID}/app.bsky.feed.post/${'x'.repeat(513)}`, 'bad'), + }] }, { + fetchedAt: '2026-09-05T10:10:00.000Z', + source: SOURCE, + limit: 20, + })).toThrow('Timeline occurrence 1 omitted a usable canonical post URI'); + const longestValidKey = 'A_~.:-0'.repeat(74).slice(0, 512); + const longestValidUri = `at://${AUTHOR_DID}/app.bsky.feed.post/${longestValidKey}`; + const longestValid = normalizeFeed({ feed: [{ post: apiPost(longestValidUri, 'valid boundary') }] }, { + fetchedAt: '2026-09-05T10:10:00.000Z', + source: SOURCE, + limit: 20, + }); + expect(longestValid.entries[0].postUri).toBe(longestValidUri); + + const empty = normalizeFeed({ feed: [], cursor: '' }, { + fetchedAt: '2026-09-05T10:10:00.000Z', + source: SOURCE, + limit: 20, + }); + expect(empty.entries).toEqual([]); + expect(empty.nodes).toEqual([]); + expect(empty.cursor).toBeUndefined(); + expect(empty.warnings).toEqual(['Timeline response supplied an empty cursor; continuation is unavailable.']); + }); +}); + +describe('authenticated Reader.following', () => { + test('does not create an authenticated reader from empty access or refresh credentials', async () => { + const identifier = `fixture-${crypto.randomUUID()}.invalid`; + const password = `fixture-${crypto.randomUUID()}`; + const authConfig = temporaryAuthConfig(identifier, password); + let loginCount = 0; + const requests = installFetch((request) => { + const url = new URL(request.url); + if (!url.pathname.endsWith('/com.atproto.server.createSession')) { + return jsonResponse({ error: 'TimelineMustNotRun' }, 500); + } + loginCount += 1; + return jsonResponse({ + did: VIEWER_DID, + handle: 'viewer.test', + accessJwt: loginCount === 1 ? '' : 'fixture-access', + refreshJwt: loginCount === 1 ? 'fixture-refresh' : '', + active: true, + }); + }); + + await expect(createReader({ authConfig, pds: SOURCE.service })) + .rejects.toThrow('Authentication response omitted usable session credentials'); + await expect(createReader({ authConfig, pds: SOURCE.service })) + .rejects.toThrow('Authentication response omitted usable session credentials'); + expect(requests).toHaveLength(2); + expect(requests.every((request) => new URL(request.url).pathname.endsWith('/com.atproto.server.createSession'))).toBe(true); + }); + + test('rejects public use, bounds options before timeline calls, retains source, and stops cursor loops', async () => { + const identifier = `fixture-${crypto.randomUUID()}.invalid`; + const passwordSuffix = `-${crypto.randomUUID()}`; + const password = `invalid${passwordSuffix}`; + const overlapProbe = `${identifier}${passwordSuffix}`; + const accessSuffix = `-access-${crypto.randomUUID()}`; + const refreshSuffix = `-refresh-${crypto.randomUUID()}`; + const accessValue = `${password}${accessSuffix}`; + const refreshValue = `${password}${refreshSuffix}`; + const rotatedAccessSuffix = `-rotated-access-${crypto.randomUUID()}`; + const rotatedRefreshSuffix = `-rotated-refresh-${crypto.randomUUID()}`; + const rotatedAccessValue = `${password}${rotatedAccessSuffix}`; + const rotatedRefreshValue = `${password}${rotatedRefreshSuffix}`; + let rotationAttempts = 0; + const requests = installFetch((request) => { + const url = new URL(request.url); + if (url.pathname.endsWith('/com.atproto.server.createSession')) { + return jsonResponse({ + did: VIEWER_DID, + handle: 'viewer.test', + accessJwt: accessValue, + refreshJwt: refreshValue, + active: true, + }); + } + if (url.pathname.endsWith('/com.atproto.server.refreshSession')) { + return jsonResponse({ + did: VIEWER_DID, + handle: 'viewer.test', + accessJwt: rotatedAccessValue, + refreshJwt: rotatedRefreshValue, + active: true, + }); + } + if (url.pathname.endsWith('/com.atproto.identity.resolveHandle')) { + return jsonResponse({ + error: 'ResolverFailure', + message: `echo ${overlapProbe} ${accessValue} ${refreshValue} ${rotatedAccessValue} ${rotatedRefreshValue}`, + }, 503); + } + if (url.pathname.endsWith('/app.bsky.feed.getTimeline')) { + const cursor = url.searchParams.get('cursor'); + if (cursor === 'rotate-cursor') { + rotationAttempts += 1; + if (rotationAttempts === 1) { + return jsonResponse({ error: 'ExpiredToken', message: 'synthetic expiry' }, 401); + } + return jsonResponse({ + error: 'RetryFailure', + message: `echo ${accessValue} ${refreshValue} ${rotatedAccessValue} ${rotatedRefreshValue}`, + }, 503); + } + if (cursor === 'error-cursor') { + return jsonResponse({ + error: 'UpstreamFailure', + message: `echo ${overlapProbe} ${accessValue} ${refreshValue} ${rotatedAccessValue} ${rotatedRefreshValue}`, + }, 503); + } + return jsonResponse({ + feed: [{ post: apiPost(POST_URI, 'Network fixture') }], + cursor: cursor === 'loop-cursor' ? 'loop-cursor' : 'next-cursor', + }); + } + return jsonResponse({ error: 'UnexpectedRequest', message: url.pathname }, 500); + }); + + const publicReader = await createReader({ service: 'https://public.example' }); + await expect(publicReader.following()).rejects.toThrow('Following feed requires an authenticated reader'); + await expect(publicReader.thread(`${POST_URI}/extra`)).rejects.toThrow( + 'Post AT URI must identify one app.bsky.feed.post record', + ); + expect(requests).toHaveLength(0); + + const authConfig = temporaryAuthConfig(identifier, password); + const reader = await createReader({ authConfig, pds: SOURCE.service }); + expect(reader.source).toEqual(SOURCE); + const page = await reader.following({ limit: 2, cursor: 'prior-cursor' }); + const timelineRequest = requests.find((request) => new URL(request.url).pathname.endsWith('/app.bsky.feed.getTimeline')); + expect(new URL(timelineRequest!.url).searchParams.get('limit')).toBe('2'); + expect(new URL(timelineRequest!.url).searchParams.get('cursor')).toBe('prior-cursor'); + expect(page.source).toEqual(SOURCE); + expect(page.requestCursor).toBe('prior-cursor'); + expect(page.cursor).toBe('next-cursor'); + + const requestCount = requests.length; + await expect(reader.following({ limit: 0 })).rejects.toThrow('limit must be an integer from 1 through 100'); + await expect(reader.following({ limit: 101 })).rejects.toThrow('limit must be an integer from 1 through 100'); + await expect(reader.following({ cursor: '' })).rejects.toThrow('cursor must be a nonempty opaque string'); + expect(requests).toHaveLength(requestCount); + await expect(reader.following({ cursor: 'loop-cursor' })).rejects.toThrow('refusing a silent loop'); + + let rotationError: unknown; + try { + await reader.following({ cursor: 'rotate-cursor' }); + } catch (error) { + rotationError = error; + } + expect(rotationAttempts).toBe(2); + expect(requests.some((request) => new URL(request.url).pathname.endsWith('/com.atproto.server.refreshSession'))).toBe(true); + expect(String(rotationError)).toContain('Fetching following feed failed'); + for (const secret of [ + accessValue, + refreshValue, + rotatedAccessValue, + rotatedRefreshValue, + accessSuffix, + refreshSuffix, + rotatedAccessSuffix, + rotatedRefreshSuffix, + ]) { + expect(String(rotationError)).not.toContain(secret); + } + expect(String(rotationError)).toContain('[redacted]'); + + let requestError: unknown; + try { + await reader.following({ cursor: 'error-cursor' }); + } catch (error) { + requestError = error; + } + expect(String(requestError)).toContain('Fetching following feed failed'); + expect(String(requestError)).not.toContain(identifier); + expect(String(requestError)).not.toContain(password); + expect(String(requestError)).not.toContain(passwordSuffix); + expect(String(requestError)).not.toContain(overlapProbe); + expect(String(requestError)).not.toContain(accessValue); + expect(String(requestError)).not.toContain(refreshValue); + expect(String(requestError)).not.toContain(accessSuffix); + expect(String(requestError)).not.toContain(refreshSuffix); + expect(String(requestError)).not.toContain(rotatedAccessValue); + expect(String(requestError)).not.toContain(rotatedRefreshValue); + expect(String(requestError)).not.toContain(rotatedAccessSuffix); + expect(String(requestError)).not.toContain(rotatedRefreshSuffix); + expect(String(requestError)).toContain('[redacted]'); + + let resolverError: unknown; + try { + await reader.thread('https://bsky.app/profile/fail.test/post/focus'); + } catch (error) { + resolverError = error; + } + expect(String(resolverError)).toContain('Resolving handle fail.test failed'); + for (const secret of [ + identifier, + password, + passwordSuffix, + overlapProbe, + accessValue, + refreshValue, + accessSuffix, + refreshSuffix, + rotatedAccessValue, + rotatedRefreshValue, + rotatedAccessSuffix, + rotatedRefreshSuffix, + ]) { + expect(String(resolverError)).not.toContain(secret); + } + expect(String(resolverError)).toContain('[redacted]'); + }); +});