ReviewOS

also looking at this

stacks/bench-review

Adopt the hq-apps app conventions

#76
Merged glennmichael123 wants to merge chore/hq-apps-conventions into main
31 files +1656 -395
README.mdmodified+115-373
Changes to README.md
@@ -1,400 +1,142 @@
1![Social Card of Stacks](./public/images/social.png)
1# Bench Review
22
3# Rapid App & Library Development
3[![License: MIT](https://img.shields.io/badge/license-MIT-111827.svg)](./LICENSE.md)
44
5[![npm version](https://img.shields.io/npm/v/stacks?style=flat-square)](https://npmjs.com/package/stacks)
6[![GitHub Actions](https://img.shields.io/github/actions/workflow/status/stacksjs/stacks/ci.yml?style=flat-square&branch=main)](https://github.com/stacksjs/stacks/actions?query=workflow%3Aci)
7[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
8[![npm downloads](https://img.shields.io/npm/dm/stacks?style=flat-square)](https://npmjs.com/package/stacks)
9<!-- [![Codecov][codecov-src]][codecov-href] -->
5A public directory of judges, with first-hand reviews from the attorneys,
6clerks, and court staff who appear before them. Think Yelp, for the bench.
107
11> [!WARNING]
12> Stay tuned. Open Beta coming soon.
13
14Stacks is a rapid development framework, where the goal is to _help you_ create & maintain frontends, backends, and clouds—without having to worry about the boilerplate. _An all-in-one toolkit that meets all your full stack needs._
15
16- Web & Desktop Applications _(including system tray apps)_
17- Serverless & Traditional APIs
18- Cloud Infrastructure Creation & Maintenance
19- Interactive CLIs
20- Framework-agnostic Component & Function Libraries
21- Deployment & Release Manager _(CI & CD)_
22
23## Convention Over Configuration
24
25As a developer, Stacks helps you every step along the way—in beginner & expert-friendly ways, allowing you to focus on the _what & why_ of your project, all while enabling you to stay in control & ownership of your _(& your users’)_ data.
8Built as a [Stacks](https://github.com/stacksjs/stacks) app: `defineModel()`
9for schema, [stx](https://github.com/stacksjs/stx) for views, Crosswind for
10styling, and `buddy` for everything else.
2611
27> “It is the framework’s responsibility to remove patterns that lead to boilerplate code. And Stacks is really good at that.” _- Chris_
28
29<!-- ![Atomic UI & FX Design](./docs/assets/diagram.png) -->
30
31## Get Started
32
33It’s incredibly easy to get started with this framework. Simply run the following command in your terminal:
12> [!WARNING]
13> **Pre-launch.** The application surface is substantially complete, but the
14> directory has no production content yet — building against an empty database
15> produces zero judge and courthouse pages. Content ingestion is the open
16> blocker. See [Status](#status).
17
18## What it does
19
20**The directory** — judges and courthouses, each with a profile, a reviews
21tab, and (for judges) recent rulings. Courthouses carry real building-level
22coordinates and render on a Leaflet/OSM map.
23
24**Reviews** — a rich-text editor with server-side draft autosave (so a draft
25survives a device change), photo upload that strips EXIF and emits a
26three-size resize ladder, 1–5 star ratings, threaded comments, and a
27"helpful" vote with a denormalised counter so public feeds stay `COUNT`-free.
28Reviews can be posted anonymously; the reviewer label is derived through a
29helper built to avoid de-anonymisation.
30
31**Moderation** — an admin surface with queues for flagged reviews, judge
32submissions, and credential claims, plus user suspension (reversible) and
33deletion, and an append-only moderation audit log recording who did what.
34
35**Trust** — reviewers can submit a credential claim (role + state) that an
36admin verifies out of band. Judges can claim their own profile and post an
37official response to a review of them; the same right-of-reply is also
38available admin-mediated.
39
40**Accounts** — registration, login, email verification (with resend),
41password reset, password change, and sign-out-everywhere. Plus data export and
42self-serve account deletion with a full cascade.
43
44**Public hygiene** — a DB-derived sitemap and robots.txt, per-page canonical /
45Open Graph / Twitter tags, a JSON-LD Organization + WebSite + WebPage graph,
46and a Content-Security-Policy with every inline script hashed. Rate limits sit
47on every public and mutating endpoint.
48
49## Stack
50
51| Layer | What |
52|---|---|
53| Framework | [Stacks](https://github.com/stacksjs/stacks) |
54| Views | [stx](https://github.com/stacksjs/stx) — build-time rendered, no frontend render server |
55| Styling | Crosswind (Tailwind-compatible utilities) |
56| Data | `defineModel()` + [bun-query-builder](https://github.com/stacksjs/bun-query-builder); SQLite in dev, Postgres in production |
57| Search | Meilisearch configured; the UI still filters client-side |
58| Images | sharp (EXIF strip + resize) |
59| Storage | `app/Storage/disk.ts` — local disk or Bun-native S3 via `FILESYSTEM_DISK` |
60| Lint | [pickier](https://github.com/stacksjs/pickier) (never eslint directly) |
61
62## Getting started
3463
3564```bash
36curl -Ssf stacksjs.org/install | sh # wip
37
38# alternatively, if Bun >= v1.2.5 is installed already
39# you may also get started via
40bunx buddy new my-project
65bun install
66cp .env.example .env
67./buddy key:generate
68./buddy migrate
69./buddy seed
70./buddy dev
4171```
4272
43## Usage
73Views come up on `:4000`, the API on `:4008`.
4474
45The following list includes some of the most common ways to interact with the Stacks API.
75> `./buddy seed` loads 6 courthouses, 24 judges, and a handful of reviews —
76> enough to exercise every page, not enough to be a product.
4677
47_Meet the toolkit, Buddy:_
78## Layout
4879
49```bash
50buddy install # installs all dependencies
51buddy dev # starts one of the dev servers (frontend, API, components, docs, desktop, etc.)
52buddy share # creates a sharable link of your local project
53buddy build # follow CLI prompts to select which library (or server) to build
54buddy commit # follow CLI prompts for committing changes
55buddy release # creates the releases for the stack & consequently, publishes them to npm
56buddy upgrade # auto-update all deps & the Stacks framework
57
58buddy make:component HelloWorld # scaffolds a Component
59buddy make:function HelloWorld # scaffolds a Function
60buddy make:model Car # scaffolds a Model
61buddy make:action UpdateCar # scaffolds an Action
62buddy make:migration create_cars_table # scaffolds a Migration
63buddy make:view Car # scaffolds a Page (https://my-project.test/car)
64buddy make:command Inspire # scaffolds a Command
65buddy make:job SendEmail # scaffolds a Job
66buddy make:middleware Logger # scaffolds a new Middleware
67buddy make:notification WelcomeEmail # scaffolds a Notification
68buddy make:lang de # scaffolds a language file
69
70buddy list # lists all available commands
71buddy --help
7280```
73
74<details>
75<summary>View the complete Buddy Toolkit</summary>
76
77```bash
78buddy --version # get the Stacks version
79buddy --help # view help menu
80# please note: you may suffix any command with the
81# `command --help` flag to review the help menu
82
83buddy install # installs dependencies
84buddy add # adds a stack or dependency
85buddy fresh # fresh reinstall of all deps
86buddy clean # removes all deps
87buddy setup # sets up the project initially
88buddy setup:oh-my-zsh # optional: sets up Oh My Zsh with auto-completions & "aliases"
89
90buddy upgrade # upgrades all dependencies
91buddy upgrade -i # prompts you to select which updates to apply (wip)
92buddy upgrade:dependencies # auto-upgrades package.json deps
93buddy upgrade:framework # auto-upgrades deps & the Stacks framework
94buddy upgrade:search-engine # auto-upgrades configured search engine
95buddy upgrade:shell # upgrades the shell integration
96buddy upgrade:binary # upgrades the `stacks` binary
97buddy upgrade:bun # upgrades to latest project-defined Bun version
98buddy upgrade:all # auto-upgrades all of the above
99
100# if you need any more info on any command listed here, you may suffix
101# any of them via the "help option", i.e. `buddy ... --help`
102
103buddy dev # starts the frontend dev server
104buddy dev -i # prompts any of the dev servers (components, functions, views, docs, or api)
105buddy dev:api # starts the API dev server
106buddy dev:dashboard # starts the Admin/Dashboard dev server
107buddy dev:desktop # starts the Desktop dev server
108buddy dev:views # starts frontend dev server
109buddy dev:components # starts component dev server
110buddy dev:functions # stubs functions
111buddy dev:docs # starts local docs dev server
112buddy dev docs # also starts the local docs dev server (colon is optional for all commands)
113buddy development # `buddy dev` alias
114
115buddy share # creates a sharable link to your local project
116
117# for Laravel folks, `serve` may ring more familiar than the `dev` name. Hence, we aliased it
118buddy serve
119buddy serve:components
120buddy serve:desktop
121buddy serve:views
122buddy serve:functions
123buddy serve:docs
124
125# building for production (e.g. AWS, Google Cloud, npm, Vercel, Netlify, et al.)
126buddy build # select a specific build (follow CLI prompts)
127buddy build:views # builds SSG views
128buddy build:desktop # builds Desktop application
129buddy build:library # builds any or all libraries
130buddy build:functions # builds function library
131buddy build:components # builds Vue component library & Web Component library
132buddy build:web-components # builds framework agnostic Web Component library (i.e. Custom Elements)
133buddy build:vue-components # builds Vue 2 & 3-ready Component library
134buddy build:all # builds all your code
135
136# `buddy build` aliases
137buddy prod
138buddy prod:components
139buddy prod:desktop
140buddy prod:library
141buddy prod:views
142buddy prod:functions
143buddy prod:vue-components
144buddy prod:web-components
145buddy prod:all
146buddy production # `buddy prod` alias
147
148# sets your application key
149buddy key:generate
150
151buddy make:component HelloWorld # bootstraps a HelloWorld component
152buddy make:function hello-world # bootstraps a hello-world function
153buddy make:view hello-world # bootstraps a hello-word page
154buddy make:model Car # bootstraps a Car model
155buddy make:database cars # creates a cars database
156buddy make:migration create_cars_table # creates a cars migration file
157buddy make:factory cars # creates a Car factory file
158buddy make:table cars # bootstraps a cars data table
159buddy make:notification welcome-email # bootstraps a welcome-email notification
160buddy make:lang de # bootstraps a lang/de.yml language file
161buddy make:stack my-project # shares logic with `bunx --bun stacks new my-project`
162
163buddy migrate # runs database migrations
164buddy migrate:dns # sets the ./config/dns.ts file
165
166buddy dns example.com # list all DNS records for example.com
167buddy dns example.com --type MX # list MX records for example.com (proxies dog)
168
169buddy https httpie.io/hello
170# http [flags] [METHOD] URL [ITEM [ITEM]]
171buddy http --help
172buddy http PUT pie.dev/put X-API-Token:123 name=John # Custom HTTP method, HTTP headers and JSON data
173buddy http -v pie.dev/get # See the request that is being sent using one of the output options
174buddy http -f POST pie.dev/post hello=World # submitting forms
175buddy http --offline pie.dev/post hello=offline
176buddy http -a USERNAME POST https://api.github.com/repos/httpie/cli/issues/83/comments body='HTTPie is awesome! :heart:'
177buddy http pie.dev/post < files/data.json
178buddy http pie.dev/image/png > image.png
179buddy http --download pie.dev/image/png
180buddy http --session=logged-in -a username:password pie.dev/get API-Key:123
181buddy http --session=logged-in pie.dev/headers
182buddy http localhost:8000 Host:example.com
183
184buddy lint # runs linter
185buddy lint:fix # runs linter and fixes issues
186
187buddy commit # follow CLI prompts for committing staged changes
188buddy release # creates the releases for the stack & triggers the Release Action (workflow)
189buddy changelog # generates CHANGELOG.md
190
191# when deploying your app/s to a remote server or cloud provider
192buddy deploy # select a specific deployment (follow CLI prompts)
193# buddy deploy:docs # deploys docs to AWS (or other configured provider)
194# buddy deploy:functions # deploys functions to AWS (or other configured provider)
195# buddy deploy:views # deploys views to AWS (or other configured provider)
196# buddy deploy:all # deploys all your code
197buddy undeploy # be careful: "undeploys" removes/deletes your deployed resources
198
199buddy cloud:remove # removes cloud setup
200buddy cloud:cleanup # removes cloud setup & cleans up all potentially leftover resources
201buddy cloud:add --jump-box # adds a jump box to your cloud setup
202
203# select the example to run (follow CLI prompts)
204buddy example # prompts you to select which example to run
205buddy example:vue # runs the Vue example
206buddy example:web-components # runs the Web Component example
207
208# you likely won’t need to run these commands as they are auto-triggered, but they are available
209buddy generate # prompts you to select which generator to run
210buddy generate:types # generates types for your components, functions, & views
211buddy generate:entries # generates entry files for components, functions, & views
212buddy generate:web-types # generates Web Component types
213buddy generate:vscode-custom-data # generates VSCode custom data
214buddy generate:ide-helpers # generates IDE helpers
215buddy generate:component-meta # generates component meta
216buddy generate:all # runs all generators
217
218# generates your application key
219buddy key:generate # generates your application key
220
221# manage your environment variables
222buddy env:get # get an environment variable
223buddy env:set # set an environment variable
224buddy env:encrypt # encrypt an environment variable
225buddy env:decrypt # decrypt an environment variable
226buddy env:keypair # generate a keypair
227buddy env:rotate # rotate a keypair
228
229# generate your TypeScript declarations
230buddy types:generate # generates types for your components, functions, & views
231buddy types:fix # auto-fixes types for your components, functions, & views
232
233buddy domains # alias for `buddy domains:list`
234buddy domains:add stacksjs.org # adds a domain
235buddy domains:remove stacksjs.org # removes a domain
236buddy domains:list # lists all domains
237buddy domains:update # apply ./config/dns.ts updates
238buddy domains:purchase stacksjs.org # purchase a new domain
239
240# test your stack
241buddy test # runs test suite (unit & e2e)
242buddy test:coverage # runs test coverage
243buddy test:types # runs typecheck
244
245# the CLI may be triggered in any
246# of the following syntax
247stx fresh
248buddy fresh
249bud fresh
81app/
82 Actions/ one file per endpoint, grouped by surface (Reviews, Judges, Admin, Me, …)
83 Models/ defineModel() schema; `useApi.routes` is OPT-OUT — always state it
84 Helpers/ SEO head injection, sitemap, CSP, review photos, storage disk
85 Support/ health endpoint
86resources/
87 views/ one file per route; dynamic routes enumerate via getStaticPaths
88 components/ Bench/* — the real UI lives here
89 stores/ all data access goes through a store, never a fetch in a component
90 layouts/ page shells
91routes/api.ts hand-written API routes (auto-prefixed with /api)
92database/ plain-SQL migrations + idempotent seeders
93scripts/ the validation suite (see below)
94site.config.ts single source of truth for name / url / SEO
95gate.ts 17-check build + SEO conformance gate
25096```
25197
252</details>
253
254Read more here about the Stacks CLI in the documentation.
255
256## Features
257
258The Stacks framework is a harmony of several “engines” to build any web and/or desktop application, in highly scalable & privacy-friendly ways. It consists of the following engines:
259
260### Frontend Development
261
262_Develop dynamic UIs with helpers for atomic design, and much more._
263
264- �� **Components** _primitive to develop user interfaces_
265- �� **Functions** _primitive to develop business logic (and grant your UI superpowers)_
266- �� **UI Kit** _modern & deeply-integrated components_
267- �� **Web** _“a routing & templating engine that makes sense”_
268- ��️ **Desktop** _transforms your web app into a desktop app, plus more_
269- �� **Documentation** _markdown-based documentation, auto-generated_
270- �� **Library** _auto-builds & manages component & function libraries_
271- ⚡️ Powered by Bun, Tauri, UnoCSS, Vite, VitePress and Vue
272
273### Backend Development
274
275_Develop serverless (or server) functions with countless helpers to build scalable & fast APIs._
276
277- �� **AI** _deep AI integrations & foundational model access_
278- �� **APIs** _scalability & maintainability built-in_
279- ��️ **Cache** _unified caching for DynamoDB, Redis and more_
280- ⚙️ **CLIs** _create beautiful CLIs for Linux, Windows, and Mac (dependency-free binaries)_
281- ��️ **Commerce** _own & grow your own online business with ease (SaaS-optimized)_
282- �� **Database** _DynamoDB, SQLite, MySQL, Postgres, and more_
283- �� **Errors** _native type-safe error handling_
284- ��️ **Events** _functional event (front & backend) communication_
285- �� **Notifications** _emails, SMSs, direct, and push notifications & webhooks_
286- ��️ **ORM** _automated schemas for scale & a pretty API_
287- �� **Payments** _unified API for one-off & subscription billing methods for Stripe_
288- ⚙️ **Queues** _run any heavy workload in the background_
289- ��️ **Query Builder** _powerful, type-safe SQL query builder_
290- �� **Realtime** _“everything you need to build dynamic real-time apps”_
291- �� **Router** _smart routing, file-based or Laravel-like_
292- �� **Search Engine** _smart searching, advanced filtering & sorting, pagination, headless UI_
293- �� **Storage** _a secure-by-default File API that feels right_
294- �� **Tinker** _a powerful TypeScript REPL_
295- ��️ **Validation** _e2e type-safety (true frontend & backend harmony)_
296- �� **X-Ray** _all you need to debug, log & analyze_
297
298### Cloud Development
299
300_Develop & maintain cloud infrastructure with ease. “Imagine Vercel, Vapor and Forge having been unified.”_
301
302- ☁️ **Server** _local development server & production-ready servers out-of-the-box_
303- ⛅️ **Serverless** _on-demand, auto-scaling, zero maintenance_
304- ⏰ **Alarms** _built-in cloud infrastructure monitoring to avoid surprises_
305- �� **CDN** _zero-config, low-latency, request life-cycle hooks, optimized request compressions (Brotli & gzip)_
306- �� **Domain** _version-controlled & zero-config domain management (e.g. DNS management)_
307- �� **AI** _fine-tune a foundational model using your application data_
308- �� **Email** _secure & zero-setup <easy-peasy@custom-domains.com> mailboxes_
309- �� **Firewall** _native web application firewall support_
310- �� **Storage** _unlimited cloud storage & automatic backups_
311- �� **Maintenance** _maintain your cloud infrastructure with ease using Buddy & Stacks_
312- �� **Infrastructure as Code** _version-controlled cloud infrastructure (AWS, Google next?)_
313
314### CI/CD
315
316_Focus on coding, not publishing._
317
318- �� **Deployment Manager** _takes the sweat out of production deployments—zero-setup push-to-deploy_
319- 0️⃣ **Zero Downtime** _deploy with confidence using a zero-downtime deployment strategy_
320- �� **Release Manager** _libraries (component & function) auto-published to npm, git helpers, and more_
321
322### Developer Experience (DX)
323
324Convention over configuration, while staying wholly configurable. _No more boilerplate._
325
326- �� **Automated Upgrades** _no need to worry about upgrading to the latest versions, Stacks upgrades you_
327- �� **Pretty Dev URLs** _your-project.localhost instead of localhost:3000_
328- �� **IDE Integration** _auto-completions, inline docs & a powerful IDE setup_
329- �� **Zero-Config** _yet highly configurable—convention over configuration_
330- �� **Linter & Formatter** _auto-configured & built into your IDE_
331- ���� **Type Strong** _built-in e2e type-safety_
332- ✨ **Git Workflows** _committing with ease_
333- �� **Auto Imports** _your components & functions, including date, string, array, & object helpers_
334- ⏩ **Code Snippets** _goodbye to the boilerplate code—thank you Sarah Drasner_
335- �� **Spell Checker** _be notified once there are typos_
336- ��️ **Essential Utilities** _powers at your fingertips. Collections, VueUse, and more_
337- �� **Team Management** _manage your team & their permissions_
338- �� **Streamlined Testing** _unit & e2e tests powered by Bun, Vitest & Playwright_
339
340No matter whether you are a beginner or an expert, the approachable Stacks design allows you to learn at your own pace, using our thorough documentation covering every aspect of the framework. Stacks is extremely beginner & expert-friendly.
341
342Develop beautiful, reactive, composable UIs without learning a new set of languages. HTML, CSS, and minimal JavaScript—that’s all you need to dive in now! _Or TypeScript ✌��_
343
344> _An actual rapid application development framework for all Full Stack needs. Next-level simplicity & DX._
345
346## Testing
98## Quality gates
34799
348100```bash
349./buddy test
101bun run lint # pickier
102bun run typecheck:app # app-owned TypeScript
103bun run gate # build + 17 build/SEO integrity checks
104bun run ui:validate # accessibility lint over resources/
105bun run visual:validate # headless-Chrome contrast / overflow / focus audit
106bun run release:validate # route text contracts, assets, metadata, migrations
107bun run deployment:smoke # post-deploy checks against the live domain
350108```
351109
352## Changelog
353
354Please see our [releases](https://github.com/stacksjs/stacks/releases) page for more information on what has changed recently.
355
356## Contributing
357
358Please see the [Contributing Guide](https://github.com/stacksjs/contributing) for details.
359
360## Community
361
362For help, discussion about best practices, or any other conversation that would benefit from being searchable:
110`release:validate` only passes on a build made with a production `APP_URL` —
111that is the check that catches a dev artifact being shipped.
363112
364[Discussions on GitHub](https://github.com/stacksjs/stacks/discussions)
113## Deploying
365114
366For casual chit-chat with others using this package:
115See [DEPLOY.md](./DEPLOY.md). The short version: the build produces a static
116`dist/` plus an API process, and the host must provide two things the artifact
117cannot — an `/api/*` proxy and a `/verify-email/:id/:token` rewrite.
367118
368[Join the Stacks Discord Server](https://stacksjs.com/discord)
119## Status
369120
370## Postcardware
121Working and verified: the full review lifecycle, moderation, auth, privacy
122export/delete, SEO surface, and rate limiting. `lint`, `typecheck:app`,
123`ui:validate` and `release:validate` are green; `gate` is 16/17.
371124
372“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.
125Open before launch:
373126
374Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States ��
375
376## Sponsors
377
378We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.
379
380- [JetBrains](https://www.jetbrains.com/)
381- [The Solana Foundation](https://solana.com/)
382
383## Credits
384
385- [Laravel](https://laravel.com) _many thanks to their community_
386- [Chris Breuer](https://github.com/chrisbbreuer)
387- [All Contributors](../../contributors)
388
389And a special thanks to [Dan Scanlon](https://twitter.com/danscan) for donating the `stacks` name on npm ✨
1271. **Content ingestion** — the directory is empty, so no entity pages render.
128 This is the one blocker that makes the rest moot.
1292. **A host** — `config/cloud.ts` is still stock Stacks and describes
130 `stacksjs.org`, not this app.
1313. **Production SMTP** — email verification and password reset depend on it.
1324. **`routes: []` on `app/Models/Request.ts`** — it currently declares
133 `useApi: true` with no `routes`, which the ORM generator turns into
134 unauthenticated full CRUD at `/api/requests`.
1355. **`HttpOnly` on the auth cookie** — the token is readable from JS today.
1366. **Tests** — `tests/` is still placeholder stubs.
1377. **`docs/`** — still the inherited Stacks framework documentation; either
138 curate it for this app or remove it.
390139
391140## License
392141
393The MIT License (MIT). Please see [LICENSE](LICENSE.md) for more information.
394
395Made with ��
396
397<!-- Badges -->
398
399<!-- [codecov-src]: https://img.shields.io/codecov/c/gh/stacksjs/stacks/main?style=flat-square
400[codecov-href]: https://codecov.io/gh/stacksjs/buddy -->
142[MIT](./LICENSE.md)