From 4834ac2723156aaa389d48aa698e220f4b53dbfb Mon Sep 17 00:00:00 2001 From: Michael Chernigin Date: Thu, 4 Jun 2026 02:41:46 +0400 Subject: [PATCH] chore: archive initial read-later app spec --- .../.openspec.yaml | 0 .../design.md | 0 .../proposal.md | 0 .../specs/article-cache/spec.md | 40 +++++++++++++ .../specs/atproto-auth/spec.md | 37 ++++++++++++ .../specs/responsive-reading-ui/spec.md | 58 +++++++++++++++++++ .../specs/saved-links/spec.md | 44 ++++++++++++++ .../tasks.md | 2 +- .../specs/article-cache/spec.md | 0 .../specs/atproto-auth/spec.md | 0 .../specs/responsive-reading-ui/spec.md | 0 .../specs/saved-links/spec.md | 0 12 files changed, 180 insertions(+), 1 deletion(-) rename openspec/changes/{initial-read-later-app => archive/2026-06-03-initial-read-later-app}/.openspec.yaml (100%) rename openspec/changes/{initial-read-later-app => archive/2026-06-03-initial-read-later-app}/design.md (100%) rename openspec/changes/{initial-read-later-app => archive/2026-06-03-initial-read-later-app}/proposal.md (100%) create mode 100644 openspec/changes/archive/2026-06-03-initial-read-later-app/specs/article-cache/spec.md create mode 100644 openspec/changes/archive/2026-06-03-initial-read-later-app/specs/atproto-auth/spec.md create mode 100644 openspec/changes/archive/2026-06-03-initial-read-later-app/specs/responsive-reading-ui/spec.md create mode 100644 openspec/changes/archive/2026-06-03-initial-read-later-app/specs/saved-links/spec.md rename openspec/changes/{initial-read-later-app => archive/2026-06-03-initial-read-later-app}/tasks.md (96%) rename openspec/{changes/initial-read-later-app => }/specs/article-cache/spec.md (100%) rename openspec/{changes/initial-read-later-app => }/specs/atproto-auth/spec.md (100%) rename openspec/{changes/initial-read-later-app => }/specs/responsive-reading-ui/spec.md (100%) rename openspec/{changes/initial-read-later-app => }/specs/saved-links/spec.md (100%) diff --git a/openspec/changes/initial-read-later-app/.openspec.yaml b/openspec/changes/archive/2026-06-03-initial-read-later-app/.openspec.yaml similarity index 100% rename from openspec/changes/initial-read-later-app/.openspec.yaml rename to openspec/changes/archive/2026-06-03-initial-read-later-app/.openspec.yaml diff --git a/openspec/changes/initial-read-later-app/design.md b/openspec/changes/archive/2026-06-03-initial-read-later-app/design.md similarity index 100% rename from openspec/changes/initial-read-later-app/design.md rename to openspec/changes/archive/2026-06-03-initial-read-later-app/design.md diff --git a/openspec/changes/initial-read-later-app/proposal.md b/openspec/changes/archive/2026-06-03-initial-read-later-app/proposal.md similarity index 100% rename from openspec/changes/initial-read-later-app/proposal.md rename to openspec/changes/archive/2026-06-03-initial-read-later-app/proposal.md diff --git a/openspec/changes/archive/2026-06-03-initial-read-later-app/specs/article-cache/spec.md b/openspec/changes/archive/2026-06-03-initial-read-later-app/specs/article-cache/spec.md new file mode 100644 index 0000000..cc8e4b4 --- /dev/null +++ b/openspec/changes/archive/2026-06-03-initial-read-later-app/specs/article-cache/spec.md @@ -0,0 +1,40 @@ +## ADDED Requirements + +### Requirement: Extract readable article content +The system SHALL use `defuddle.md` to extract readable article content and metadata from saved URLs. + +#### Scenario: Successful extraction +- **WHEN** article extraction succeeds for a URL +- **THEN** the system stores readable article body content and available metadata such as title, author, canonical URL, excerpt, lead image, language, and extraction timestamp + +#### Scenario: Extraction unavailable +- **WHEN** article extraction fails for a URL +- **THEN** the system records the failure state and keeps the original URL available to open directly + +### Requirement: Cache extracted article snapshots +The system SHALL cache extracted article snapshots so they can be displayed without depending on the source website remaining available. + +#### Scenario: Source website later unavailable +- **WHEN** the user opens a saved article whose source website cannot be reached but a cached snapshot exists +- **THEN** the system displays the cached readable article snapshot + +### Requirement: Render cached article for reading +The system SHALL render cached article body content in a readable article view. + +#### Scenario: Open cached article +- **WHEN** the user opens a saved link with an available cached snapshot +- **THEN** the system displays the readable article body, key metadata, and an action to open the original URL + +### Requirement: Reprocess article snapshots +The system SHALL allow article extraction to be retried for failed or stale snapshots. + +#### Scenario: Retry failed extraction +- **WHEN** the user retries extraction for a URL with a previous failure +- **THEN** the system attempts extraction again and updates the snapshot status and content based on the result + +### Requirement: Safe article rendering +The system MUST render cached article content without executing scripts or unsafe source-site markup. + +#### Scenario: Article contains unsafe markup +- **WHEN** extracted article content includes scripts, event handlers, or unsafe embedded markup +- **THEN** the system removes or neutralizes unsafe content before rendering it in the reader diff --git a/openspec/changes/archive/2026-06-03-initial-read-later-app/specs/atproto-auth/spec.md b/openspec/changes/archive/2026-06-03-initial-read-later-app/specs/atproto-auth/spec.md new file mode 100644 index 0000000..e8df0f1 --- /dev/null +++ b/openspec/changes/archive/2026-06-03-initial-read-later-app/specs/atproto-auth/spec.md @@ -0,0 +1,37 @@ +## ADDED Requirements + +### Requirement: AT Protocol OAuth sign-in +The system SHALL allow human users to sign in with an AT Protocol identity using OAuth. + +#### Scenario: Successful OAuth sign-in +- **WHEN** a visitor completes AT Protocol OAuth successfully +- **THEN** the system creates or updates the local user account linked to that AT Protocol identity and starts an authenticated session + +#### Scenario: Failed OAuth sign-in +- **WHEN** AT Protocol OAuth fails or is denied +- **THEN** the system does not create an authenticated session and shows a recoverable sign-in error + +### Requirement: Local authenticated sessions +The system SHALL maintain local authenticated sessions after AT Protocol OAuth completes. + +#### Scenario: Access protected app while signed in +- **WHEN** an authenticated user opens the app +- **THEN** the system allows access to saved links and reader views for that user + +#### Scenario: Access protected app while signed out +- **WHEN** an unauthenticated visitor opens a protected app route +- **THEN** the system redirects or prompts the visitor to sign in + +### Requirement: User data isolation +The system MUST associate saved links and article snapshots with the authenticated user or an explicit ownership scope. + +#### Scenario: User views app data +- **WHEN** a signed-in user views inbox or article pages +- **THEN** the system only returns data belonging to that user's accessible scope + +### Requirement: Sign-out +The system SHALL allow an authenticated user to sign out. + +#### Scenario: User signs out +- **WHEN** the user chooses to sign out +- **THEN** the system ends the local authenticated session and prevents further protected access without signing in again diff --git a/openspec/changes/archive/2026-06-03-initial-read-later-app/specs/responsive-reading-ui/spec.md b/openspec/changes/archive/2026-06-03-initial-read-later-app/specs/responsive-reading-ui/spec.md new file mode 100644 index 0000000..184b4a7 --- /dev/null +++ b/openspec/changes/archive/2026-06-03-initial-read-later-app/specs/responsive-reading-ui/spec.md @@ -0,0 +1,58 @@ +## ADDED Requirements + +### Requirement: Minimal primary navigation +The system SHALL provide minimal primary navigation for Inbox, Archive, and Reader-oriented flows. + +#### Scenario: Navigate main app areas +- **WHEN** the authenticated user uses primary navigation +- **THEN** the system allows switching between active saved links, archived saved links, and current reading context without exposing unrelated dashboard clutter + +### Requirement: Mobile top bar navigation +The system SHALL use a compact top bar for mobile navigation. + +#### Scenario: Use app on phone viewport +- **WHEN** the user opens the app on a phone-sized viewport +- **THEN** the system presents a compact top bar and keeps the main reading area free from persistent bottom navigation + +### Requirement: Desktop reading layout +The system SHALL provide a desktop layout optimized for reading and managing a simple list. + +#### Scenario: Use app on desktop viewport +- **WHEN** the user opens the app on a desktop-sized viewport +- **THEN** the system presents saved-link and reader surfaces with comfortable line length, readable typography, and persistent access to core actions + +### Requirement: Mobile reading layout +The system SHALL provide a mobile layout optimized for one-column reading and touch interactions. + +#### Scenario: Read on phone viewport +- **WHEN** the user reads an article on a phone-sized viewport +- **THEN** the system presents content in a single-column layout with legible text and touch-accessible actions for saving, reading, archiving, and opening originals + +### Requirement: Reader actions +The system SHALL show essential reader actions without distracting from the article body. + +#### Scenario: Read article +- **WHEN** the user views an article +- **THEN** the system displays the article body prominently and provides access to open original, mark read/unread, archive, and return to the previous list + +### Requirement: shadcn/ui usage +The system SHALL use official shadcn/ui components for core interface primitives and SHALL keep custom visual styling minimal in v1. + +#### Scenario: Render core controls +- **WHEN** the system renders forms, buttons, dialogs, menus, or common controls +- **THEN** it uses official shadcn/ui components or components generated from the shadcn registry + +#### Scenario: Render article body +- **WHEN** the system renders the article reader +- **THEN** custom styling does not distract from reading or reduce text legibility + +### Requirement: Loading and empty states +The system SHALL provide clear empty, loading, and error states for inbox and article extraction views. + +#### Scenario: Empty inbox +- **WHEN** the user has no saved links in the inbox +- **THEN** the system shows an empty state that explains how to add a link + +#### Scenario: Article extraction pending +- **WHEN** the user opens an article whose extraction is still pending +- **THEN** the system shows the pending state and keeps the original URL action available diff --git a/openspec/changes/archive/2026-06-03-initial-read-later-app/specs/saved-links/spec.md b/openspec/changes/archive/2026-06-03-initial-read-later-app/specs/saved-links/spec.md new file mode 100644 index 0000000..23864a2 --- /dev/null +++ b/openspec/changes/archive/2026-06-03-initial-read-later-app/specs/saved-links/spec.md @@ -0,0 +1,44 @@ +## ADDED Requirements + +### Requirement: Save arbitrary URLs +The system SHALL allow an authenticated user to save an arbitrary valid HTTP or HTTPS URL into an inbox. + +#### Scenario: Save a new URL +- **WHEN** the user submits a valid URL that is not already saved in their scope +- **THEN** the system creates a saved-link record in the inbox and begins article metadata/content processing + +#### Scenario: Save an invalid URL +- **WHEN** the user submits a missing, malformed, or unsupported URL +- **THEN** the system rejects the submission with a clear validation message and does not create a saved link + +### Requirement: Avoid duplicate saved links +The system SHALL prevent accidental duplicate saved-link records for the same normalized URL within the same user scope. + +#### Scenario: Save an already-saved URL +- **WHEN** the user submits a URL that normalizes to an existing saved link in their scope +- **THEN** the system returns the existing saved link instead of creating a duplicate + +### Requirement: Inbox listing +The system SHALL show saved links in an inbox sorted with newest saved items first by default. + +#### Scenario: View inbox +- **WHEN** the user opens the inbox +- **THEN** the system displays the user's saved links with title or URL, source domain, save time, read/archive state, and article processing state + +### Requirement: Open original URL +The system SHALL provide a direct action to open the original source URL for every saved link. + +#### Scenario: Open source article +- **WHEN** the user activates the open-original action for a saved link +- **THEN** the system opens or navigates to the saved link's original URL without requiring cached article content to exist + +### Requirement: Saved-link read state +The system SHALL support marking saved links as unread, read, and archived. + +#### Scenario: Mark link as read +- **WHEN** the user marks a saved link as read +- **THEN** the system updates the link state and reflects the new state in inbox filters or grouping + +#### Scenario: Archive link +- **WHEN** the user archives a saved link +- **THEN** the system removes it from the default inbox view while keeping it accessible from an archived or library view diff --git a/openspec/changes/initial-read-later-app/tasks.md b/openspec/changes/archive/2026-06-03-initial-read-later-app/tasks.md similarity index 96% rename from openspec/changes/initial-read-later-app/tasks.md rename to openspec/changes/archive/2026-06-03-initial-read-later-app/tasks.md index 59e4aa7..6585089 100644 --- a/openspec/changes/initial-read-later-app/tasks.md +++ b/openspec/changes/archive/2026-06-03-initial-read-later-app/tasks.md @@ -47,7 +47,7 @@ ## 6. Verification and Documentation - [x] 6.1 Run the full automated test suite and fix failures. -- [ ] 6.2 Verify end-to-end flow: sign in, save link, read cached article, open original, mark read/unread, and archive. +- [x] 6.2 Verify end-to-end flow: sign in, save link, read cached article, open original, mark read/unread, and archive. - [x] 6.3 Verify mobile flow with top bar navigation and readable article layout. - [x] 6.4 Document deployment, required secrets, data backup/export considerations, and article extraction operations. - [x] 6.5 Record deferred roadmap items for RSS, agents/Hermess API, folders, search, import/export, browser extensions, and offline/PWA behavior. diff --git a/openspec/changes/initial-read-later-app/specs/article-cache/spec.md b/openspec/specs/article-cache/spec.md similarity index 100% rename from openspec/changes/initial-read-later-app/specs/article-cache/spec.md rename to openspec/specs/article-cache/spec.md diff --git a/openspec/changes/initial-read-later-app/specs/atproto-auth/spec.md b/openspec/specs/atproto-auth/spec.md similarity index 100% rename from openspec/changes/initial-read-later-app/specs/atproto-auth/spec.md rename to openspec/specs/atproto-auth/spec.md diff --git a/openspec/changes/initial-read-later-app/specs/responsive-reading-ui/spec.md b/openspec/specs/responsive-reading-ui/spec.md similarity index 100% rename from openspec/changes/initial-read-later-app/specs/responsive-reading-ui/spec.md rename to openspec/specs/responsive-reading-ui/spec.md diff --git a/openspec/changes/initial-read-later-app/specs/saved-links/spec.md b/openspec/specs/saved-links/spec.md similarity index 100% rename from openspec/changes/initial-read-later-app/specs/saved-links/spec.md rename to openspec/specs/saved-links/spec.md -- knotmirror 0.0.1