Skip to main content

SPEC-0001: App Foundation

Overview​

The app foundation is the native macOS shell of Stet: the sign-in experience, the forge integration that populates a pull-request/file inbox, and the reading canvas that renders code and Markdown. It establishes the three-region window (inbox · canvas · Tour rail) and the Liquid Glass design system that the rest of the product lives inside. It realizes ADR-0001 (platform + SwiftUI/Liquid Glass), ADR-0002 (viewer-first, inbox-first posture), and ADR-0007 (forge integration and authentication).

This spec covers reading and navigation only. Review markup and dispatch are specified in SPEC-0002 and SPEC-0003.

Requirements​

Requirement: Platform and Design System​

The application SHALL target macOS 26 (Tahoe) or later on Apple silicon only, and SHALL be built SwiftUI-first using native Liquid Glass materials that adapt to underlying content.

Scenario: Launch on supported hardware​

  • WHEN the app launches on macOS 26+ Apple silicon
  • THEN the main window presents three regions — an inbox (leading), a canvas (center), and a Tour rail (trailing) — rendered with adaptive Liquid Glass materials for chrome (toolbars, sidebars) distinct from content surfaces.

Scenario: Unsupported environment​

  • WHEN the app is run on an unsupported OS or architecture
  • THEN it refuses to run with a clear message stating the macOS 26 + Apple silicon requirement, rather than launching in a degraded state.

Requirement: Sign In With a Forge​

The application SHALL onboard the user via OAuth sign-in to a forge (GitHub or Gitea), storing the resulting token in the macOS Keychain and reusing it across launches. It SHALL NOT require the user to paste a personal access token.

Scenario: First-run GitHub sign-in​

  • WHEN a new user chooses "Sign in with GitHub"
  • THEN an OAuth flow completes (loopback browser flow, or device flow as fallback), the access token is written to the Keychain, and the user lands in a populated inbox.

Scenario: Returning launch​

  • WHEN a previously signed-in user relaunches the app
  • THEN the Keychain-stored token is reused and the inbox loads without re-authentication, unless the token is missing or revoked.

Scenario: Gitea as a first-class forge​

  • WHEN the user configures a Gitea instance and signs in
  • THEN Gitea PRs and files appear in the inbox with the same capabilities as GitHub, through a shared Forge abstraction.

Requirement: Pull-Request and File Inbox​

The application SHALL present an inbox — not a file tree — as the home surface, listing pull requests and files that require the user's attention, and SHALL keep it current as PRs are created or updated.

Scenario: Inbox as home​

  • WHEN the user is signed in
  • THEN the leading region shows a triage-oriented list of PRs awaiting review and flagged files, ordered by relevance/recency, with a file tree available only as a secondary view.

Scenario: Timely updates​

  • WHEN a PR is opened or updated on the forge
  • THEN it appears or updates in the inbox within the adaptive polling window, and promptly if a webhook endpoint is configured.

Requirement: Code Canvas​

The application SHALL render source files with tree-sitter-based syntax highlighting, a minimap, a gutter, and diff view, in a read-optimized posture, without exposing a primary free-text editing surface.

Scenario: Viewing a source file​

  • WHEN the user selects a source file or a file within a PR diff
  • THEN the canvas renders it with syntax highlighting and minimap; when viewing a PR, the diff is shown with additions/deletions.

Scenario: No primary editing surface​

  • WHEN the user interacts with code in the canvas
  • THEN they may select, navigate, and annotate, but there is no primary free-text code-entry mode; human changes are captured as suggestion markup (SPEC-0002).

Requirement: Rendered Markdown​

The application SHALL render Markdown files as rendered documents (GitHub-flavored Markdown), not as raw source, including headings, lists, tables, code blocks, and task lists.

Scenario: Viewing a Markdown document​

  • WHEN the user opens a .md file (README, ADR, spec)
  • THEN it renders as formatted rich text with selectable content and syntax-highlighted fenced code blocks.

Requirement: Local Git Operations​

The application SHALL perform local git operations (clone/worktree, diff, blame) in-process via a libgit2-backed library rather than by shelling out.

Scenario: Producing a diff for a PR​

  • WHEN the app needs the diff for a PR branch against its base
  • THEN it computes the diff via the in-process git library and renders it in the canvas.