Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
867f65f
refactor!: remove Next.js app, Node server, Postgres and observabilit…
SweetRetry Oct 16, 2026
1524aa9
feat: TanStack Start app on Void with Vite+ toolchain
SweetRetry Oct 16, 2026
bea93b8
feat(ui): adopt Retry as the design language
SweetRetry Oct 16, 2026
9b0a12b
refactor(ui): apply Retry deltas to shadcn components (recorded unfre…
SweetRetry Oct 16, 2026
b5cbd36
feat(web): Better Auth on D1 with optional GitHub and Google
SweetRetry Oct 16, 2026
2075d9a
refactor(ui): regenerate shadcn components on Base UI (base-nova)
SweetRetry Oct 16, 2026
90ee7fd
refactor(ui): reapply Retry deltas on Base UI with a codemod (recorde…
SweetRetry Oct 16, 2026
24b80f7
refactor(design): Retry's DESIGN.md becomes the root DESIGN.md
SweetRetry Oct 16, 2026
4f4369c
refactor(ui): extend Retry deltas to AlertDialog and the remaining fl…
SweetRetry Oct 16, 2026
e070e26
feat(web): notes with R2 attachments and AI Gateway summaries
SweetRetry Oct 16, 2026
20919c5
refactor(web): leaner error contract, local migrations before dev
SweetRetry Oct 16, 2026
e2fdeec
docs: English docs, markdownlint gate, Retry files owned by the repo
SweetRetry Oct 16, 2026
e46e831
chore: link Void's agent skill into .agents/skills
SweetRetry Oct 16, 2026
3e30d42
fix(web): commit the generated route tree
SweetRetry Oct 16, 2026
63092b4
fix: install git hooks through a prepare script
SweetRetry Oct 16, 2026
fe2398d
feat(web): name the Worker, explain a missing AI Gateway
SweetRetry Oct 16, 2026
7853355
feat(web): auth layout with artwork, standard sign-in and sign-up
SweetRetry Oct 16, 2026
95d7006
feat(web): replace auth and notes with a Motif chat app
SweetRetry Oct 16, 2026
5aff7ef
fix: deploy through pnpm run, keep workers.dev on
SweetRetry Oct 16, 2026
9664598
feat(web): prerendered blog at /, chats owned by a cookie visitor
SweetRetry Oct 16, 2026
da0b707
feat(web): blog nav on the left, post runs to the header's right edge
SweetRetry Oct 16, 2026
5230137
feat(web): bilingual blog, chat domain in one module, closed workers.…
SweetRetry Oct 16, 2026
c764357
docs: Chinese README, requirements, commands and the closed workers.d…
SweetRetry Oct 17, 2026
8b428b4
docs(agents): Better Auth is the pick for when accounts arrive, not i…
SweetRetry Oct 17, 2026
46107c2
ci: run e2e alongside verify, least-privilege token, current action m…
SweetRetry Oct 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions .agents/skills/verify-web/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
---
name: verify-web
description: Verify Void Starter in a real browser when reproducing a UI bug, checking a changed user journey, or capturing E2E evidence. Covers articles, Chat and attachments, with an executable local smoke suite.
---

# Verify web

Use this project-local entry point from any agent. Commands run at the repository root. Read [features/README.md](features/README.md) and select every entry point affected by the change before driving the app.

## Launch

Requires macOS or Linux, Node 24+ and the workspace's pnpm version. Install workspace dependencies with `pnpm install --frozen-lockfile` if missing. Install Playwright's headless Chromium once per machine. On Linux CI, use `pnpm exec playwright install --with-deps --only-shell chromium` to include system libraries.

```sh
pnpm exec playwright install --only-shell chromium
pnpm e2e
```

The runner copies the current app and packages into a temporary workspace, excluding local env files, connection records and persisted data. It shares installed dependencies but gives Vite its own cache directory. It applies local migrations, forces local Cloudflare bindings and starts the dev server on an available loopback port with `--strictPort`. Empty D1 is the seed for smoke. Readiness requires both the article and an empty Chat loader to render successfully.

Each invocation owns its workspace, port and evidence directory. Concurrent agents can run separately without sharing D1 or R2. Do not install dependencies while a run is active. The smoke suite never submits a turn or calls Workers AI.

The script launches its own headless Chromium with an isolated browser context. It works from a terminal or CI without an agent-specific browser service. Manual journeys in the feature map can use any available browser tool with equivalent controls and evidence capture.

## Doctor

The runner prints `Ready` only after checking the owned server and usable routes. To diagnose that instance while it is running, use its printed URL.

```sh
pnpm e2e --doctor http://127.0.0.1:5173
```

Replace the port with the actual run's port. This read-only check requires HTTP 200 and recognizable rendered content at `/` and a fresh `/c/<uuid>`. It checks local app and database readiness, not AI credentials or build identity. For identity, use the runner's `result.json`, `server.log` and owned PID. Never attach to an unexplained existing server just because the port answers.

## Drive

`scripts/e2e-browser.js` drives actual links and the composer through Playwright. It checks literal headings, URLs and Send state. `pnpm e2e` runs every automated journey in the feature map. A smoke pass covers only those journeys.

For a changed feature beyond smoke, use its map's selectors and expected state. Connected journeys require a dedicated checkout and local database prepared with `pnpm dev`, plus the account and gateway setup in `docs/deployment.md`. Record the exact environment and AI usage. A missing precondition is blocked coverage, not a passing test. Preserve the mapped journey when reporting the blocker.

## Evidence

Every invocation prints `.verification/run-<id>/`. It contains `server.log`, `browser.log`, `result.json`, `journey.json` and numbered DOM snapshots. The journey records action names, timestamps and outcomes. A failed action remains `started` and gets error evidence when the browser is still accessible. Exit 0 requires setup, every smoke assertion and workspace cleanup to succeed. A four-minute watchdog bounds the run.

Use `pnpm e2e --screenshots` to require a PNG after every step. Screenshot failure then fails the run. Default DOM evidence proves interaction results, not visual correctness.

Capture the action and the resulting state. For persisted Chat or attachment changes, reload and verify saved turns or download bytes as well as the screen. Use real user controls. Keep mocks at an existing external boundary and label mocked coverage explicitly. The shipped smoke uses no mocks. Include the evidence path, covered feature names, pass/fail/block status and remaining gaps in the handoff. Read the screenshot when claiming visual correctness.

## Cleanup

The runner terminates only process groups it started and removes its temporary workspace on success or failure. Evidence remains under `.verification/`, outside that workspace. SIGINT and SIGTERM trigger cleanup. An uncatchable kill can leave resources behind. Identify them from the run's recorded paths and PID before removing anything. Never kill by executable name or reset the developer's database.

The driver closes its browser on success and failure. Inspect retained logs, snapshots and requested screenshots after a failure. Verify the evidence files still exist after cleanup.

## Helpers and maintenance

- `node scripts/e2e.js --help` lists supported commands. `e2e.js` owns launch, doctor and server cleanup. `e2e-browser.js` runs the browser journeys in a child Node process.
- `pnpm verify` remains the repository's full code gate. Browser E2E is an explicit additional check because Chromium must be installed first.
- Update the relevant feature map and executable journey when routes, labels or behavior change. Keep new automated checks in the existing driver until another independently runnable suite is needed.

Adapted from Cursor's [create-verification-skill](https://github.com/cursor/plugins/blob/main/pstack/skills/create-verification-skill/SKILL.md). Its `/maintain-verification-skill` is an optional upstream workflow, not a command installed in this repository.
10 changes: 10 additions & 0 deletions .agents/skills/verify-web/features/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# Feature map

| Feature | Coverage | Read when |
| :------------------------------ | :--------------------------------------------------------------------------------- | :----------------------------------------------------------------- |
| [Articles](articles.md) | Automated navigation and language smoke. TOC, footer and mobile checks are manual. | Changing blog content, routes or navigation. |
| [Composer](composer.md) | Automated empty Chat and draft checks. Model selection is manual. | Changing Chat launch, composer or model picker. |
| [Answers and sessions](chat.md) | Requires connected AI. Not executed by smoke. | Changing streaming, persistence, retry, stop or visitor ownership. |
| [Attachments](attachments.md) | Requires connected AI and local R2. Not executed by smoke. | Changing file selection, upload, preview or download. |

Select all affected entry points. Record unexecuted cases as gaps. Each feature file defines the expected user-visible result, including side effects where applicable.
19 changes: 19 additions & 0 deletions .agents/skills/verify-web/features/articles.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Articles

## Sub-features

Overview and tooling articles, English and Chinese URLs, header navigation, language switching, footer links and a responsive table of contents.

## How to get to it (user POV)

Start at `/`. Header article links and the footer's Read next link switch articles. The language control keeps the current article. Direct links include `/zh/cloud`, `/en/harness` and `/zh/harness`.

## Driving it with a browser

Run `pnpm e2e` for the automated path. It clicks `a[aria-label="Switch to Chinese"]`, `nav[aria-label="Articles"] a[href="/zh/harness"]` and `a[aria-label="Switch to English"]`. Literal H1 assertions prove translated content. Reloading `/en/harness` proves a direct request renders the article.

For navigation changes, also exercise the footer link and return to Overview from the header. For TOC changes, use a desktop viewport and click a visible heading entry. Observe the destination heading and active entry. On mobile, open On this page or 目录 and repeat. Capture before and after screenshots for scroll or layout claims.

## Gotchas

Desktop and mobile TOCs both exist in the DOM. Use the visible entry from a fresh snapshot. Smoke runs a dev server and does not prove prerendered production assets or responsive layout. Changes to prerendering also require `pnpm build` and inspection of `apps/web/dist/client`.
23 changes: 23 additions & 0 deletions .agents/skills/verify-web/features/attachments.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Attachments

## Sub-features

Selecting and removing a file, submitting it with a turn, loading its saved attachment and downloading the stored bytes.

## How to get to it (user POV)

Open a new Chat and use Attach files in the composer. An attached chip can be removed before sending. Saved attachments appear beside their user turn.

## Driving it with a browser

Use the connected environment from [Answers and sessions](chat.md). Create a small UTF-8 text fixture with a unique marker in the evidence directory and record its SHA-256.

1. Click `button[aria-label="Attach files"]` and select the fixture through the file chooser. With Playwright, arm `page.waitForEvent("filechooser")` before clicking, then call the chooser's `setFiles()` with the fixture's absolute path. Other browser tools may use their equivalent file-upload control.
2. Verify the filename chip. Remove it through the visible remove control and verify it disappears. Select it again.
3. Type a request to quote the marker and submit. Verify the filename on the saved user turn and a completed answer containing the marker.
4. Reload the Chat and verify the attachment remains. Read the rendered attachment link from a snapshot. Download that URL using the same Visitor session. With Playwright, `page.request.get(url)` shares the context's cookies. Require HTTP 200 and save the response body as bytes. Compare the downloaded bytes and SHA-256 with the fixture.
5. For image preview changes, repeat selection and reload with a small image fixture. Capture the visible preview as well as byte equality.

## Gotchas

The chip alone proves only local selection. Successful download after reload proves D1 metadata and R2 bytes are accessible to the Visitor. The route uses `/api/chats/<chatId>/files/<fileId>`; obtain ids from the actual saved link. Missing AI setup blocks the submit path rather than reducing the check to a chip screenshot. File-size and type validation belong to `apps/web/src/lib/chat.ts`; inspect its current limits before testing rejection boundaries.
25 changes: 25 additions & 0 deletions .agents/skills/verify-web/features/chat.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Answers and sessions

## Sub-features

Streaming answers and reasoning, stopping, regenerating, reloading saved turns, session switching and visitor ownership.

## How to get to it (user POV)

Open Playground or New chat. Type a turn and use Send message or Enter. Previous Chats appear in the sidebar, or under Chats on narrow screens.

## Driving it with a browser

Use a dedicated connected development checkout following `docs/deployment.md`. Run `pnpm dev` there and record its URL and PID. This journey calls Workers AI and persists local D1 data. The automated smoke's temporary instance forces local bindings and cannot prove it.

1. Fill the composer with a unique marker and a short question. Click `button[aria-label="Send message"]`. Capture the user turn and in-progress Thinking or Stop state.
2. Wait for a nonempty answer and `button[aria-label="Copy answer"]`. An error toast is a failure, even if the user turn remains visible.
3. Reload the same `/c/<uuid>`. Verify the exact submitted turn and completed answer remain. This proves persistence through the public page loader.
4. Open New chat and select the prior Chat from the visible Chats navigation. Verify the same turns return.
5. For retry changes, click `button[aria-label="Regenerate"]`. Verify a completed replacement answer and reload to check persistence.
6. For stop changes, send a long-output request and click `button[aria-label="Stop"]` while streaming. Verify the composer is usable again and record what survives reload.
7. For visitor ownership changes, open that URL in a separately isolated browser context. Verify the original turns and session list are inaccessible. Another tab in the same profile is the same Visitor.

## Gotchas

A connected Cloudflare account, an existing AI Gateway and model access are required. Missing setup, quota exhaustion or unavailable models block this journey and must be reported. Reasoning is model-dependent. Record the selected model when checking it. Treat failures without automatic resubmission to avoid duplicate paid requests. Preserve screenshots and logs before stopping the owned server. Local test records can remain in the dedicated checkout; deleting data requires separate authorization.
19 changes: 19 additions & 0 deletions .agents/skills/verify-web/features/composer.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Composer

## Sub-features

Starting a fresh Chat, editing a draft, enabling Send and choosing a model.

## How to get to it (user POV)

Use Playground in the site header, New chat in the Chat sidebar, or navigate to `/chat`. Each entry creates a new `/c/<uuid>` URL. A Chat is persisted only on its first submitted turn.

## Driving it with a browser

Smoke clicks `header a[href="/chat"]` and waits for `textarea[placeholder="Ask anything, or drop in a file."]`. It verifies the UUID URL and disabled `button[aria-label="Send message"]`, types `Verification draft`, checks Send becomes enabled, then clears the textarea and checks Send becomes disabled.

For launch changes, repeat through New chat and direct `/chat`, verifying different UUIDs and empty threads. For model picker changes, click `button[aria-label^="Model: "]`, choose a visible `menuitemradio` from the snapshot and verify the trigger displays that model. Submitting with that model belongs to the connected Chat journey.

## Gotchas

The composer becoming usable proves the Chat loader can read migrated D1. It does not prove a saved Chat or an AI answer. Desktop and mobile New chat links coexist. Choose the visible entry.
1 change: 1 addition & 0 deletions .agents/skills/void
10 changes: 10 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# Keep the workflow's actions on current majors. npm dependencies are updated by hand.
version: 2
updates:
- package-ecosystem: github-actions
directory: /
schedule:
interval: monthly
groups:
actions:
patterns: ["*"]
76 changes: 45 additions & 31 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,54 +5,68 @@ on:
branches: [main]
push:
branches: [main]
workflow_dispatch:

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

permissions:
contents: read

jobs:
# The full gate (AGENTS.md › Verification).
verify:
runs-on: ubuntu-latest
timeout-minutes: 15

steps:
- uses: actions/checkout@v7

- uses: pnpm/action-setup@v6

- uses: actions/setup-node@v7
with:
node-version: 24
cache: pnpm

services:
postgres:
image: postgres:17-alpine
env:
POSTGRES_DB: sweet_kit
POSTGRES_PASSWORD: sweet
POSTGRES_USER: sweet
ports:
- 5432:5432
options: >-
--health-cmd "pg_isready -U sweet -d sweet_kit"
--health-interval 2s
--health-timeout 5s
--health-retries 10

env:
DATABASE_URL: postgresql://sweet:sweet@localhost:5432/sweet_kit
BETTER_AUTH_SECRET: ci-test-secret-at-least-32-characters-long
BETTER_AUTH_URL: http://localhost:43111
WEB_URL: http://localhost:43110
SERVER_URL: http://localhost:43111
NEXT_PUBLIC_SERVER_URL: http://localhost:43111
LOG_LEVEL: silent
LOG_PRETTY: "false"
OTEL_METRICS_EXPORTER: none
OTEL_LOGS_EXPORTER: none
- run: pnpm install --frozen-lockfile

- run: pnpm verify

# Browser smoke journeys against a local copy of the app. No AI requests, no Cloudflare account.
e2e:
runs-on: ubuntu-latest
timeout-minutes: 15

steps:
- uses: actions/checkout@v4
- uses: actions/checkout@v7

- uses: pnpm/action-setup@v4
- uses: pnpm/action-setup@v6

- uses: actions/setup-node@v4
- uses: actions/setup-node@v7
with:
node-version: 24
cache: pnpm

- run: pnpm install --frozen-lockfile

- run: pnpm db:migrate
- id: playwright
run: echo "version=$(pnpm exec playwright --version | cut -d' ' -f2)" >> "$GITHUB_OUTPUT"

- run: pnpm verify
- uses: actions/cache@v6
with:
path: ~/.cache/ms-playwright
key: playwright-${{ runner.os }}-${{ steps.playwright.outputs.version }}

- run: pnpm exec playwright install --with-deps --only-shell chromium

- run: pnpm e2e --screenshots

# result.json, server.log, browser.log and one snapshot per step.
- if: failure()
uses: actions/upload-artifact@v7
with:
name: e2e-evidence
path: .verification/
retention-days: 7
40 changes: 14 additions & 26 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,42 +1,30 @@
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.

# Dependencies
node_modules
.pnp
.pnp.js

# Local env files
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
.env.*
!.env.example

# Testing
# Build and tool output
dist
coverage

# Turbo
.verification
.turbo

# Vercel
.vercel

# Build Outputs
.next/
out/
build
dist
*.jsonl

.tanstack
.void
.wrangler
.void-wrangler.jsonc
*.tsbuildinfo

# Lefthook local overrides
lefthook-local.yml

# Debug
npm-debug.log*

# Misc
.DS_Store
*.pem
npm-debug.log*

examples
# Void records your Cloudflare account and resources here. The template must not ship one;
# in your own app, delete this line and commit the file.
apps/web/void.lock.json
20 changes: 20 additions & 0 deletions .markdownlint-cli2.jsonc
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
{
"$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint-cli2/main/schema/markdownlint-cli2-config-schema.json",
// Markdown gates: Oxfmt (`vp fmt`, see vite.config.ts › fmt) owns the shape of a
// document — list bullets, list indent, blank lines around blocks, table padding,
// thematic breaks, trailing whitespace. markdownlint only adds the structural rules
// Oxfmt has no opinion on, such as fence languages, heading structure and links.
// Keep it that way: a rule that overlaps Oxfmt's output causes churn between the two.
"gitignore": true,
"globs": ["**/*.md"],
// .agents/skills links to skills shipped inside dependencies; they are not ours to lint.
"ignores": [".agents/**"],
"config": {
// Prose stays unwrapped. These docs are CJK paragraphs and wide tables; Oxfmt
// preserves the author's line breaks, so a length limit would only force manual
// re-wrapping with no reader benefit.
"MD013": false,
// A repeated heading is worth flagging inside one section, not document-wide.
"MD024": { "siblings_only": true },
},
}
29 changes: 0 additions & 29 deletions .oxlintrc.json

This file was deleted.

Loading
Loading