@deepraxis/app-template 0.0.0-stage → 0.1.0-dev.2990b29

package/LICENSE

@@ -0,0 +1,67 @@
+Deepractice Commercial Proprietary License
+
+Copyright (c) 2026 南京深度实践人工智能科技有限公司.
+Unified Social Credit Code: 91430104MAEDATJ09G.
+All rights reserved.
+
+IMPORTANT: THIS IS NOT AN OPEN SOURCE LICENSE.
+
+This repository and its source code, documentation, architecture, tests,
+scripts, configuration, prompts, agent designs, protocols, workflows, and other
+accompanying materials are proprietary commercial assets owned by 南京深度实践
+人工智能科技有限公司 (the "Copyright Holder").
+The Copyright Holder's Unified Social Credit Code is 91430104MAEDATJ09G.
+
+The purpose of this license is to bind this repository and the project code to
+the Copyright Holder as closed-source commercial intellectual property.
+
+No rights are granted by default. Access to this repository, possession of a
+copy of the source code, visibility into commit history, participation in
+business discussions, employment, consulting, shareholder status, investment,
+or cooperation with any related entity does not grant any ownership interest,
+copyright license, patent license, trademark license, trade secret license, or
+other intellectual property right.
+
+Without a separate written commercial agreement signed by the Copyright Holder,
+no person or entity may, directly or indirectly:
+
+1. use, run, deploy, host, or provide the software as a service;
+2. copy, modify, merge, adapt, translate, or create derivative works;
+3. publish, distribute, sublicense, lease, sell, transfer, or disclose the
+   software or any substantial part of it;
+4. reverse engineer, decompile, disassemble, or otherwise attempt to derive
+   source, structure, architecture, protocols, prompts, trade secrets, or
+   implementation details;
+5. use the software, code, documentation, architecture, protocols, prompts, or
+   repository history to train, fine-tune, evaluate, or improve any AI model,
+   coding agent, software-generation system, or competing product;
+6. remove, obscure, or alter copyright, license, ownership, confidentiality, or
+   attribution notices.
+
+All commercial use, internal business use, customer delivery, private
+deployment, SaaS operation, resale, redistribution, integration into another
+product, or access by third parties requires prior written authorization from
+the Copyright Holder.
+
+Contributions are accepted only on the basis that the contributor has the right
+to contribute them and assigns, or agrees to assign, all applicable rights in
+those contributions to the Copyright Holder unless a separate written agreement
+signed by the Copyright Holder states otherwise.
+
+This license applies to this repository as a whole. No part of this repository
+may be treated as public domain, community property, jointly owned project
+property, or an implied asset of any company, shareholder, collaborator,
+customer, investor, or business partner other than the Copyright Holder without
+a separate written agreement signed by the Copyright Holder.
+
+The Chinese legal name "南京深度实践人工智能科技有限公司" is the authoritative
+identity of the Copyright Holder. Any English rendering of that name is for
+identification convenience only and does not create a separate legal entity or
+alter ownership.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING
+FROM OR IN CONNECTION WITH THE SOFTWARE OR THE USE OF OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# @deepraxis/app-template
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The standard Praxis application template: a vinext (Next.js App Router on Workers) app with
+end-user sign-up and sign-in, D1 via drizzle, R2 image upload and an admin area.
+`praxis app create` copies `template/` into a new project and replaces the `<app-name>` placeholder
+in `praxis.jsonc`; an AI agent or a developer then adapts it. See `template/README.md` for the stack.
+It has no runtime code and no private dependency; `spec/` holds the develop proof and is not published.

package/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: build-application
+description: "Required before building, changing, deploying or operating a web application on Praxis: a website, booking or ordering site, store, member area, internal tool, or any app with pages, sign-in, a database or uploads. Uses the standard Praxis stack (Next.js App Router on Workers via vinext, D1, R2) with `praxis app create` and `praxis app deploy`. Never deploy with wrangler and never pick another framework."
+---
+
+# Build an application on Praxis
+
+Use this skill when the user wants a working web application: something with pages people open in a browser, and usually sign-in, stored data or uploads. The result is a live URL on Praxis that the user can open and share.
+
+The stack and the architecture are fixed. Do not compare frameworks, do not ask the user to choose one, and do not deploy any other way. Every app starts from the standard template and is shipped with `praxis app deploy`.
+
+## The standard stack
+
+| Part | What it is | Where it lives in the project |
+|---|---|---|
+| Pages and API | Next.js App Router (v15), run on Cloudflare Workers by vinext | `app/` |
+| Business rules | Plain TypeScript, server-only | `lib/` |
+| Database | D1 (SQLite) with drizzle-orm; SQL migrations applied automatically on the first request | `migrations/`, `lib/migrations.ts`, `lib/schema.ts` |
+| Files | R2 bucket `IMAGES` | `lib/storage.ts` |
+| End-user accounts | Username and password; signed HttpOnly session cookie; the first account to register becomes `admin` | `lib/auth.ts`, `lib/session.ts`, `lib/users.ts`, `lib/guard.ts` |
+| UI | Tailwind CSS with Button, Input, Label and Card in `components/ui/` | `components/ui/` |
+| Validation | zod | in each route handler |
+| Project file | `praxis.jsonc`: name, secrets, health check | project root |
+
+The template already contains sign-up, sign-in, sign-out, an account page with image upload, an admin page and `/api/health`. Build the user's app by changing and extending it, not by starting over.
+
+## Where to run commands
+
+- **You are a Praxis platform agent.** Run `praxis` in your machine's terminal (the Bash tool). The CLI is preinstalled and already signed in through the `PRAXIS_API_TOKEN` environment variable, so never run `praxis login`. For questions about deployed apps (versions, deployments, events, secrets) you can also call the SDK from codemode: `praxis.application.workers.list()`, `praxis.application.workers.deployments.list({ path: { worker_id } })` and so on.
+- **You run elsewhere (Claude Code, Cursor, CI).** Install the CLI with `npm install -g @deepraxis/cli`. Sign in with `praxis login`, or set `PRAXIS_API_KEY`. Use the CLI for everything. Its environment follows the install: `@deepraxis/cli` talks to production, `@deepraxis/cli@dev` to develop; `PRAXIS_ENV=develop|production` overrides it. Use develop only when the user asks for it.
+
+## Steps
+
+### 1. Decide who you are working with, then gather requirements to match
+Read the request once and pick one of three paths. When in doubt, take **Quick build** and say so in one sentence ("I'll build it with sensible defaults; tell me anytime if you want something specific").
+
+| Path | Signals in the request | How much to ask before building |
+|---|---|---|
+| **Quick build** | Describes a business outcome only ("make me a booking site for my pet shop"); no technical terms | Ask at most two questions, and only those whose answer changes the data model (for example "can one customer book several pets in one visit?"). Ask them in one go with the `ask_user_question` tool, offering 2–4 concrete options each. Choose every other detail yourself (names, prices, time slots, colors) and list those defaults in the final report so the user can correct them. |
+| **Build with a developer** | Mentions a stack, tables or fields, an API, a repository or existing code, or asks to see a plan or design first | Before writing code, send a short plan and wait for the user to confirm or edit it. The plan covers: pages; tables with their columns; roles and who may do what; bindings and secrets; anything that departs from the template; and what you will not build. After confirmation, build exactly that, and check back before changing the plan. |
+| **Change an existing app** | There is already a `praxis.jsonc` in the working directory, or the user names an app they have | Skip `praxis app create`. Read the project's `README.md` and `praxis.jsonc`, make the change, then continue at step 4 below. |
+
+Whatever the path, write down for yourself:
+- the pages;
+- the data, which becomes tables and columns;
+- who may do what, as roles (`user` and `admin` already exist);
+- what is uploaded.
+
+A developer who wants a different framework or brings an existing project: say plainly what the platform runs (Workers with D1, KV, R2, vars, secrets and static files; see Limits). Also say that `praxis app deploy` today ships projects with the template's build layout: a vinext build that writes `dist/server/wrangler.json`, `dist/server/*.js` and `dist/client`, plus a `praxis.jsonc`. Offer to move their pages and logic onto the template. Do not claim another layout will deploy.
+
+### 2. Create the project
+```bash
+praxis app create <name>
+cd <name>
+```
+`<name>` becomes part of the public URL: 3–40 lowercase letters, digits or single hyphens. `www`, `api`, `admin`, `app`, `docs`, `console` and `status` are reserved. The command copies the template and installs the dependencies.
+
+Read `README.md` in the new project once. It has the folder map and the recipes below in more detail.
+
+### 3. Develop
+Before you write pages, read the [design guide](references/design.md): it says how to choose the look, which layout fits the kind of app, and how it must work on phones and in Chinese. Before you build anything beyond plain pages, forms and tables (a calendar, charts, maps, rich text, export, payments …), follow [find before you build](references/research.md): look at how others do it, pick an existing library or shadcn/ui component, and prove it with a short spike.
+
+- **Tables**: add `migrations/0002_<what>.sql` using `CREATE TABLE IF NOT EXISTS …`. Import it with `?raw` and append it to the list in `lib/migrations.ts`, then describe the table in `lib/schema.ts`. Migrations run once, in order, on the first request after a deploy. **Never edit a migration that has already been deployed**; add a new one instead.
+- **Rules** (prices, availability, who owns what) go in `lib/`. Pages and route handlers only call them.
+- **Pages**: `app/<path>/page.tsx`. Protect them with `await requireUser("/<path>")` or `await requireAdmin("/<path>")` from `lib/guard.ts`.
+- **Forms**: post to a route handler in `app/api/…/route.ts`. Validate with zod and answer with a 303 redirect (`redirectResponse` in `lib/guard.ts`), the way the sign-in form does.
+- **Uploads**: follow `app/api/images/route.ts` and `lib/storage.ts`. That code checks type and size, stores the file under the owner and records it in D1. For an upload that belongs to a record (a pet photo on a booking, a cover on a book), read the file from the same form, call `checkImage` and `saveImage`, and store the returned `key` in a column of your row. Images are served by `/images/<key>` to their owner and admins only. If something must be public (a gallery, product photos), add a separate route that serves only keys you have marked public in your table, and leave `/images` private.
+- **New bindings**: declare them in `wrangler.jsonc` (`d1_databases`, `kv_namespaces`, `r2_buckets`, `vars`), add the type to `env.d.ts`, and read them with `import { env } from "cloudflare:workers"`.
+- **Secrets**: add them to `praxis.jsonc` `secrets`. `"generate"` creates a random value on the first deploy and keeps it on every later deploy. Never write a secret value into a file.
+- **UI**: use the components in `components/ui/` and the semantic Tailwind classes (`bg-primary`, `text-muted-foreground` …). Change the look through the tokens in `app/globals.css`, never with raw colors in pages. Change the site name, home page, navigation and colors freely; keep the sign-in, sign-up, account and admin pages working.
+
+### 4. Check before deploying
+```bash
+bun run typecheck && bun test && bun run build
+```
+`bun test` runs every test in the project. Fix every error before you deploy. `bun run dev` serves the app locally if you want to look at it first.
+
+### 5. Deploy
+```bash
+praxis app deploy
+```
+It builds, uploads only the changed files, creates a version, deploys it, keeps or creates the secrets and calls the `healthcheck` path. The build log comes first; the result comes last and contains the URL. With `--json` the last line is a JSON object with `url`, `worker_id`, `version_id` and `secrets_created`. A deploy takes about one to two minutes.
+
+### 6. Verify it like a user
+- Open the URL. If the `control-browser` skill is available, use it, and walk through the main flow: register, sign in, do the main task, and check the admin page. Take screenshots at 390 px and 1280 px wide and fix what looks off before you report (design guide, section 8).
+- Without a browser, check over HTTP. Forms post `application/x-www-form-urlencoded` (uploads: `multipart/form-data`) and answer `303` with a `Location`; protected pages answer a redirect to `/login` when signed out.
+  ```bash
+  U=<url>; J=$(mktemp)
+  curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' -c $J -d 'username=admin&password=<password>' $U/api/auth/register
+  curl -s -b $J $U/admin | grep -c '<something only admins see>'
+  curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' $U/admin      # signed out: redirect to /login
+  ```
+  Match on plain words, not on numbers next to markup: React may split "Books (2)" into several text nodes in the HTML.
+- **The first account registered on a fresh app becomes the admin.** Register that account yourself with the username the user asked for (or `admin`) and a strong random password, then hand both to the user. Any test accounts you create after that are ordinary users; mention them so the user can ignore them.
+
+### 7. Report to the user
+Give:
+- the URL;
+- the admin username and password;
+- what the app does, in a few lines;
+- how to ask for changes.
+
+Keep technical words out of the report (no "worker", "D1" or "migration").
+
+## Changing the app later
+Edit the code, then run step 4 and step 5 again. The data in D1 and R2 stays across deploys.
+
+Rollback switches the code, not the data: rows written by the newer version stay in D1 and migrations are not undone. So write migrations that the previous version still works with (add tables and columns; do not rename or drop them in the same release).
+
+If a deploy breaks something, go back to the previous version at once and then fix forward:
+```bash
+praxis app rollback            # the version before the current one
+praxis app rollback --to <version_id>
+```
+
+## Operating the app
+| Question | CLI | Codemode |
+|---|---|---|
+| Which versions exist? | `praxis api application worker version list --worker <worker_id>` | `praxis.application.workers.versions.list({ path: { worker_id } })` |
+| What was deployed, and when? | `praxis api application worker deployment list --worker <worker_id>` | `praxis.application.workers.deployments.list({ path: { worker_id } })` |
+| What happened (deploys, failures)? | `praxis api application worker event list --worker <worker_id>` | `praxis.application.workers.events.list({ path: { worker_id } })` |
+| Which secrets are set? | `praxis api application worker secret list --worker <worker_id>` | `praxis.application.workers.secrets.list({ path: { worker_id } })` |
+| Find the worker id | `praxis api application worker list` | `praxis.application.workers.list()` |
+| Delete the app | `praxis api application worker delete <worker_id> --yes` | `praxis.application.workers.delete({ path: { worker_id } })` |
+
+Deleting takes the URL offline at once. The app, its database and its files are kept for 7 days and can be brought back with `praxis api application worker restore <worker_id>`; after that they are purged. A deleted app still appears in `worker list` with `praxis.status` `deleted` until it is purged. Only delete when the user asks for it.
+
+Runtime logs are not available yet. To find out why a page fails, reproduce the failure, read the error page or the API response, and add clear error messages in the route handler.
+
+## Limits
+- **Not supported**: service bindings, queues, Durable Objects, Workers AI, Analytics Engine. A deploy that declares one fails with `UNSUPPORTED` and names it. Use D1, KV, R2, vars, secrets and static files instead.
+- **Rollout**: there is no gradual rollout. A deploy replaces the live version.
+- **Files**: each file can be at most 25 MiB. The template limits image uploads to 5 MB.
+- **Template parts to leave alone**: `vinext-plugins.ts` and `vite.config.ts`. They make the build deployable; removing them breaks deploys with "No such module".
+
+## When something fails
+| Symptom | Cause | Fix |
+|---|---|---|
+| `praxis: command not found` | The CLI is not installed | `npm install -g @deepraxis/cli` |
+| `NOT_LOGGED_IN`, or 401 on a platform agent's machine | The machine credentials are missing | Run the command again. If it persists, tell the user the machine has no platform credentials. Do not run `praxis login` there. |
+| `UNSUPPORTED … services` (or queues and so on) | A binding the platform does not offer | Remove it from `wrangler.jsonc` and use D1, KV or R2 |
+| Health check failed after the deploy | The app throws on `/api/health`, usually a broken migration | Open the URL to read the error, fix the migration with a NEW migration file, deploy again; `praxis app rollback` meanwhile |
+| Sign-in answers 500 "SESSION_SECRET is not configured" | The secret was removed from `praxis.jsonc` | Put `"SESSION_SECRET": "generate"` back and deploy |
+| A build error about modules or `import.meta.url` | `vinext-plugins.ts` was changed or removed | Restore it from the template |
+| Deploy fails with `Completion token has already been consumed` | A rare platform retry issue | Run `praxis app deploy` again |

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "@deepraxis/app-template",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-dev.2990b29",
+  "description": "The standard Praxis application template: vinext + D1 + R2 + end-user auth + admin area.",
+  "license": "Apache-2.0",
+  "files": [
+    "template",
+    "README.md",
+    "SKILL.md",
+    "references"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/references/design.md

@@ -0,0 +1,113 @@
+# Designing the app's interface
+
+Read this before you build or restyle pages. The people who use these apps are the merchant's own customers and staff, not developers. Most customers arrive on a phone, often inside WeChat's in-app browser. Staff use the admin area on a laptop. The goal is an interface that looks like it was made for this business, works with one thumb, and never makes a customer wonder what to do next.
+
+## 1. Decide the look before writing markup
+
+Write a five-line design brief for yourself, grounded in the business, not in "modern and clean":
+- **Who and where**: for example "pet owners booking on their phone between errands" or "front-desk staff checking today's list on a laptop".
+- **Feel**: two or three adjectives taken from the business itself. A pet groomer is warm and playful, a law office calm and formal, a bakery homemade and appetizing.
+- **Palette**: 4–6 colors with names and hex values. One brand color for the primary action and the current selection, one neutral family for text and surfaces, and the status colors (success, warning, danger). Pick the brand color from the business (its sign, its product, its logo), not purple by default.
+- **Type**: see section 4. Mostly size, weight and spacing; the font family is fixed.
+- **One memorable thing**: choose the single element that carries the personality, such as a big photo on the home page, an illustrated service card, or a bold headline. Keep everything else quiet.
+
+Put the palette into the design tokens in `app/globals.css` and `tailwind.config.ts` (section 2). Never scatter hex values through pages.
+
+### Looks that read as "generated"
+Avoid these unless the user asks for them:
+- a purple-to-blue gradient hero;
+- every section chopped into identical rounded cards with the same grey shadow;
+- a small all-caps label above every heading;
+- one word in a headline highlighted in another color;
+- emoji used as icons;
+- fade-and-slide-up animation on every section;
+- "→" appended to every button.
+
+## 2. Tokens: change the look in one place
+
+The template's colors and radius live as CSS variables in `app/globals.css` (`--background`, `--foreground`, `--muted`, `--muted-foreground`, `--border`, `--primary`, `--primary-foreground`, `--accent`, `--destructive`, `--success`, `--warning`, `--radius`). `tailwind.config.ts` maps them to classes such as `bg-primary`, `text-muted-foreground` and `border-border`.
+
+- Pages and components use only these semantic classes, never raw palette classes such as `bg-slate-900` or `text-pink-500`.
+- To rebrand, edit the variables. A site name, a brand color and a radius change should touch only `globals.css`, `tailwind.config.ts` and `app/layout.tsx`.
+- Every background color has a matching foreground for text on it, with at least 4.5:1 contrast. Check the brand color against white text before you use it on buttons.
+
+## 3. Layouts by kind of app
+
+Pick the pattern that matches the request, then adapt it.
+
+**Booking and services** (groomer, salon, clinic, class, repair):
+- Home: what the business offers, a photo, and one primary button, "Book now".
+- Service list: cards with name, price, duration and a one-line description.
+- Booking flow:
+  1. Choose a service.
+  2. Pick a day from a horizontal strip of the next days, with the weekday shown.
+  3. Pick a time from a grid of tappable time chips. Show full slots as disabled; do not hide them.
+  4. Add details.
+  5. Confirm.
+  Never use a plain `<select>` for dates or times.
+- Confirmation page: a summary of what, when, where and the price, plus what happens next.
+- "My bookings": upcoming first, each with a status badge and the actions that are allowed.
+
+**Store and catalog** (shop, menu, product list):
+- A grid of product cards, two columns on phones, with photo, name and price.
+- A detail page with a large photo and one primary action.
+- The cart or order summary is reachable from every page.
+
+**Membership and content** (club, community, course):
+- A feed or list of items with clear ownership ("added by …").
+- A profile or account page with the member's own items.
+- Creating content is one obvious button.
+
+**Admin area** (every app has one):
+- Laptop first. A left sidebar or top tabs for sections.
+- Up top, the few numbers that matter today (today's bookings, pending, new members), each linking to the filtered list.
+- Tables with filters by status, a search box, status badges, and row actions on the right.
+- Put the next action first: "3 bookings waiting for confirmation" with a button, not just a chart.
+- Destructive actions (cancel, delete) ask for confirmation.
+
+**Lead or registration form** (event sign-up, enquiry):
+- One column with only the fields that are needed.
+- A clear thank-you page that says what happens next.
+
+## 4. Phones and Chinese text
+
+- **Mobile first.** Design at 390 px wide first, then widen. Use one column on phones. The primary action on long forms and booking steps sits in a bar fixed to the bottom of the screen.
+- **Tap targets** are at least 44×44 px, with at least 8 px between them. Nothing may depend on hover.
+- **Inputs** use the right type (`tel`, `email`, `number`, `date`) so phones show the right keyboard. Labels sit above fields, never only as a placeholder.
+- **WeChat in-app browser**: avoid fixed headers taller than 56 px, do not rely on new tabs or pop-ups, and keep pages fast because the network may be slow. Use no web fonts for Chinese (section below) and compress uploaded images.
+- **Chinese type**:
+  - Use the system font stack only: `-apple-system, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans SC", sans-serif`. Chinese web fonts weigh several megabytes, so do not load them.
+  - Body text is 16 px on phones with line height 1.7.
+  - Headings are bold, not huge (20–28 px on phones).
+  - Do not use letter-spacing, italics or all-caps on Chinese text.
+  - Use Chinese punctuation in Chinese sentences.
+- **Language**: write the interface in the user's language. For a Chinese request, every label, button, message and date is Chinese, and `app/layout.tsx` sets `<html lang="zh-CN">`. Show dates as `10月28日 周三`, times as `14:00`, money as `¥228`. Format dates, times and sizes through `lib/format.ts` (set its `LOCALE` and `TIME_ZONE` for the audience), never by printing raw ISO strings or byte counts.
+
+## 5. Every screen has four states
+
+- **Empty**: say why it is empty and offer the next action ("还没有预约 · 去预约第一次洗护"). Never show an empty table with headers only.
+- **Loading**: keep the layout steady; use skeleton blocks for lists.
+- **Error**: say what went wrong and how to fix it, next to the thing that failed. Keep what the user typed: when a form fails validation, re-render the form with the values and the field errors, instead of redirecting to an empty form.
+- **Success**: confirm with the same verb as the button. "确认预约" leads to "预约已确认", followed by where to go next.
+
+Disable a submit button while it is submitting, so a double tap cannot create two bookings.
+
+## 6. Words on the screen
+
+- Name things the way customers say them ("预约", "我的宠物"), not the way the code does ("appointment record", "entity").
+- Buttons say exactly what happens: "确认预约", not "提交".
+- Never show ids, raw status codes, English enum values or stack traces to customers. Map statuses to words and colors: 待确认 (warning), 已确认 (primary), 已完成 (success), 已取消 (muted).
+- No filler paragraphs that explain the interface.
+
+## 7. Quality floor
+
+- Contrast is at least 4.5:1 for text.
+- Focus is visible for keyboard users.
+- Every image has an `alt`.
+- Buttons are `<button>` and links are `<a>`.
+- Forms work without JavaScript, which the template's plain form posts already do.
+- Pages use no horizontal scroll at 360 px.
+
+## 8. Look at it before you report
+
+If the `control-browser` skill is available, take screenshots of the home page, the main flow and the admin area at 390 px and at 1280 px wide, and fix what looks off: overflowing text, cramped buttons, misaligned columns, an empty state that shows nothing. Remove one decoration before you finish. Without a browser, at least fetch every page over HTTP and check that it renders the real content and the Chinese text you expect.

package/references/research.md

@@ -0,0 +1,56 @@
+# Find before you build: research and spike
+
+Before you build anything beyond plain pages, forms and tables, find out how others solve it, pick an existing library or component, and prove it works here with a small spike. Typical cases:
+- a date or time picker, calendar view or scheduling grid;
+- charts;
+- maps or address input;
+- rich text or Markdown editing;
+- drag and drop;
+- image cropping;
+- QR codes;
+- CSV or Excel export;
+- PDF output;
+- search;
+- payments;
+- notifications.
+
+Hand-writing these costs hours and usually ends up worse than an existing library.
+
+## 1. Look for the pattern (5 minutes)
+
+- **How do well-known products present it?** With the `control-browser` skill, open one or two products that do the same job and take screenshots. A booking flow might come from a salon or clinic booking site; an order list from a delivery or shop admin. Note what to copy: step order, which fields, how errors and empty states look. Copy the structure, never the brand.
+- **Is it already in the template?** Check `components/ui/` and `lib/` first, and reuse what is there.
+
+## 2. Pick a candidate (5 minutes)
+
+Prefer, in this order:
+1. **shadcn/ui components and blocks** (ui.shadcn.com). Copy the component source into `components/ui/`. They match the template's Tailwind and token setup. Most rely on Radix UI primitives (`@radix-ui/react-*`); install the ones a component imports.
+2. **A focused, popular npm package** for the job, for example `date-fns` for dates, `react-day-picker` for calendars, `recharts` for charts, `qrcode` for QR codes, `papaparse` for CSV, and `@tiptap/react` for rich text. These names are starting points, not rules: check them with the questions below.
+3. **Your own code**, only when the job is small or nothing passes the checks.
+
+For each candidate, answer these questions. If any answer is "no", drop it:
+
+| Question | How to check |
+|---|---|
+| Does it run on Cloudflare Workers (server parts) or in the browser (client parts)? | No native modules, no `fs` or `child_process` at runtime, no long-lived servers. Browser-only libraries go in `"use client"` components. |
+| Is it maintained? | A release in the last 12 months (`npm view <pkg> time.modified`), and real usage (weekly downloads). |
+| Is the license usable? | MIT, Apache-2.0, BSD or ISC. Avoid GPL and AGPL in the merchant's app. |
+| Is it small enough? | Check the bundle size (bundlephobia, or the build output). The whole Worker must stay well under 10 MB. Prefer libraries that tree-shake. |
+| Does it work for the users' region? | For users in mainland China, avoid anything that loads from Google (Maps, Fonts, reCAPTCHA) or other blocked hosts at runtime. Use regional services instead, for example AMap or Tencent Maps for maps. |
+| Does it support the language? | Chinese labels and locale for dates (`date-fns/locale/zh-CN`), numbers and calendars. |
+
+## 3. Spike it (10–15 minutes)
+
+1. Install only the chosen package.
+2. Build the smallest real use on a scratch page (for example `app/_spike/page.tsx`): the actual component with real data shapes, not a toy.
+3. Run `bun run build`. The build must pass and must not grow by more than you expected; compare the size of `dist/` before and after.
+4. If it has a server part, call it from a route handler and run `bun run dev` to see it work.
+5. If the user gave a deploy target, a spike can go live with `praxis app deploy`, but remove the scratch page before the real release.
+
+If the spike fails, try the next candidate. **Two failed candidates means stop and tell the user** what you tried and what you suggest instead (a simpler feature, or your own code), rather than fighting the platform.
+
+## 4. Adopt and record
+
+- Move the spike into the real feature and delete the scratch page.
+- Add one line per adopted library under "## Libraries" in the project's `README.md`: name, what it is for, and why it was chosen ("react-day-picker: booking calendar; Workers-safe, 12 kB, zh-CN locale").
+- In the report to the user, mention a library only when it affects them, for example a map provider that needs their own key.

package/template/README.md

@@ -0,0 +1,57 @@
+# Praxis app
+
+A Next.js App Router app (run by vinext on Cloudflare Workers) with end-user sign-up and sign-in,
+a D1 database, R2 image upload and an admin area. It deploys through the Praxis Application API only.
+
+## Stack
+
+- **vinext + Next.js 15 App Router**: ordinary `app/` pages and route handlers, built to a Worker.
+- **D1 + drizzle-orm**: queries are typed; schema is plain SQL migrations applied at runtime.
+- **R2**: image storage (binding `IMAGES`).
+- **Auth**: username + password (PBKDF2-SHA256 via WebCrypto), HttpOnly signed session cookie, sessions stored hashed in D1. The first user to register becomes `admin`.
+- **Tailwind CSS 3 + shadcn/ui-style primitives** in `components/ui/`.
+- **zod** for input validation.
+
+## Folder map
+
+```
+praxis.jsonc        project file: kind, name, secrets, healthcheck (read by `praxis app deploy`)
+wrangler.jsonc      bindings the app needs (read at build time; never used to deploy)
+app/                pages and route handlers (/, /login, /register, /account, /admin, /api/*, /images/*)
+lib/                server-only code and business rules
+  db.ts             getDb(): migrates once per isolate, returns the drizzle client
+  migrate.ts        runtime migrator   migrations.ts  bundled migration list   schema.ts  drizzle tables
+  auth.ts           password hashing, cookie signing, validation (no framework imports)
+  session.ts        session rows + cookie strings    users.ts  user rules (first user = admin)
+  guard.ts          getCurrentUser / requireUser / requireAdmin
+  storage.ts        image rules and R2/D1 access
+components/ui/      Button, Input, Label, Card, Badge
+migrations/         numbered SQL files
+```
+
+Keep business rules in `lib/`; pages and route handlers only call them.
+
+## Look
+
+The look lives in the design tokens at the top of `app/globals.css` (colors, radius) and the font stack in `tailwind.config.ts`. Pages and components use only semantic classes (`bg-primary`, `text-muted-foreground`, `text-destructive`), never raw palette classes or hex colors, so restyling means editing the tokens. `bun test` enforces it: `lib/design-tokens.test.ts` fails on a raw color class and on any text/background token pair under 4.5:1 contrast.
+
+## Common changes
+
+- **Add a page**: create `app/<name>/page.tsx`. Call `await requireUser("/<name>")` or `requireAdmin` from `lib/guard.ts` to protect it.
+- **Add a table**: write `migrations/0002_<name>.sql` (idempotent: `CREATE TABLE IF NOT EXISTS`), import it with `?raw` and append it in `lib/migrations.ts`, then add the table to `lib/schema.ts`. It is applied on the first request after deploy.
+- **Add a binding**: declare it in `wrangler.jsonc` (supported: `d1_databases`, `kv_namespaces`, `r2_buckets`, `vars`), add its type to `env.d.ts`, read it with `import { env } from "cloudflare:workers"`. The platform creates worker-owned resources and ignores ids.
+- **Add a secret**: add it to `Cloudflare.Env` in `env.d.ts`, read `env.NAME`, and declare it in `praxis.jsonc` `secrets` (`"generate"` makes `praxis app deploy` create a random value once and keep it). To set your own value: `praxis api application worker secret put`. Secrets are never written in files. `SESSION_SECRET` is required: without it sign-in and sign-up return a 500 naming it.
+
+## Run
+
+- `bun install` then `bun run dev` for local development.
+- `bun run typecheck`, `bun test` (auth and migrator unit tests), `bun run build` (output in `dist/`).
+- `praxis app deploy` builds, uploads and deploys, then checks `healthcheck`. `praxis app rollback` returns to the previous version. Nothing here calls wrangler to deploy.
+
+## Not supported on the platform
+
+Service bindings, queues, Durable Objects, Workers AI, Analytics Engine. Use D1, KV, R2, plain/json/secret values and static assets.
+
+## Not included yet
+
+Rate limiting (comments in `app/api/auth/*/route.ts` mark where it goes), password reset, email verification.

package/template/_gitignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+.wrangler
+.dev.vars
+.next
+next-env.d.ts
+bun.lock

package/template/app/account/page.tsx

@@ -0,0 +1,47 @@
+import { Badge } from "@/components/ui/badge";
+import { formatBytes } from "@/lib/format";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+import { getDb } from "@/lib/db";
+import { requireUser } from "@/lib/guard";
+import { listImages } from "@/lib/storage";
+
+export const dynamic = "force-dynamic";
+
+export default async function Account({ searchParams }: { searchParams: Promise<{ error?: string }> }) {
+  const user = await requireUser("/account");
+  const { error } = await searchParams;
+  const mine = await listImages(await getDb(), user.id);
+  return (
+    <div className="space-y-6">
+      <Card>
+        <CardHeader><CardTitle>{user.username}</CardTitle></CardHeader>
+        <CardContent className="text-sm"><Badge variant={user.role === "admin" ? "default" : "secondary"}>{user.role}</Badge></CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle>Upload an image</CardTitle></CardHeader>
+        <CardContent>
+          <form action="/api/images" method="post" encType="multipart/form-data" className="flex flex-col gap-3 sm:flex-row sm:items-center">
+            <Input name="image" type="file" accept="image/jpeg,image/png,image/webp" required />
+            <Button type="submit">Upload</Button>
+          </form>
+          {error && <p role="alert" className="mt-2 text-sm text-destructive">{error}</p>}
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle>Your images ({mine.length})</CardTitle></CardHeader>
+        <CardContent>
+          <ul className="grid grid-cols-2 gap-3 sm:grid-cols-3">
+            {mine.map(img => (
+              <li key={img.id} className="text-xs">
+                <a href={`/images/${img.key}`}><img src={`/images/${img.key}`} alt="" className="h-32 w-full rounded-md border object-cover" /></a>
+                <span className="text-muted-foreground">{formatBytes(img.size)}</span>
+              </li>
+            ))}
+          </ul>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

package/template/app/admin/page.tsx

@@ -0,0 +1,53 @@
+import { count, desc } from "drizzle-orm";
+import { Badge } from "@/components/ui/badge";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { getDb } from "@/lib/db";
+import { formatBytes, formatDateTime } from "@/lib/format";
+import { requireAdmin } from "@/lib/guard";
+import { images, users } from "@/lib/schema";
+
+export const dynamic = "force-dynamic";
+
+export default async function Admin() {
+  await requireAdmin("/admin");
+  const db = await getDb();
+  const [allUsers, allImages, [userCount], [imageCount]] = await Promise.all([
+    db.select({ id: users.id, username: users.username, role: users.role, createdAt: users.createdAt }).from(users).orderBy(users.createdAt),
+    db.select().from(images).orderBy(desc(images.createdAt)),
+    db.select({ n: count() }).from(users),
+    db.select({ n: count() }).from(images),
+  ]);
+  const nameOf = new Map(allUsers.map(u => [u.id, u.username]));
+  return (
+    <div className="space-y-6">
+      <Card>
+        <CardHeader><CardTitle>Users ({userCount!.n})</CardTitle></CardHeader>
+        <CardContent>
+          <div className="overflow-x-auto"><table className="w-full text-left text-sm [&_td]:py-2 [&_td]:pr-4 [&_th]:pb-2 [&_th]:pr-4 [&_th]:font-medium [&_th]:text-muted-foreground">
+            <thead><tr><th>Username</th><th>Role</th><th>Created</th></tr></thead>
+            <tbody>
+              {allUsers.map(u => (
+                <tr key={u.id}><td>{u.username}</td><td><Badge variant={u.role === "admin" ? "default" : "secondary"}>{u.role}</Badge></td><td className="whitespace-nowrap">{formatDateTime(u.createdAt)}</td></tr>
+              ))}
+            </tbody>
+          </table></div>
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle>Images ({imageCount!.n})</CardTitle></CardHeader>
+        <CardContent>
+          {allImages.length === 0 ? (
+            <p className="text-sm text-muted-foreground">No uploads yet. Members add images from their account page.</p>
+          ) : <div className="overflow-x-auto"><table className="w-full text-left text-sm [&_td]:py-2 [&_td]:pr-4 [&_th]:pb-2 [&_th]:pr-4 [&_th]:font-medium [&_th]:text-muted-foreground">
+            <thead><tr><th>Owner</th><th>Image</th><th>Type</th><th>Size</th></tr></thead>
+            <tbody>
+              {allImages.map(i => (
+                <tr key={i.id}><td>{nameOf.get(i.ownerId) ?? i.ownerId}</td><td><a href={`/images/${i.key}`} aria-label={`Open image from ${nameOf.get(i.ownerId) ?? "a member"}`}><img src={`/images/${i.key}`} alt="" className="h-12 w-12 rounded-md border border-border object-cover" /></a></td><td>{i.contentType}</td><td className="whitespace-nowrap">{formatBytes(i.size)}</td></tr>
+              ))}
+            </tbody>
+          </table></div>}
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

package/template/app/api/auth/login/route.ts

@@ -0,0 +1,30 @@
+import { env } from "cloudflare:workers";
+import { credentialsSchema, hashPassword, MissingSecretError, requireSecret, verifyPassword } from "@/lib/auth";
+import { getDb } from "@/lib/db";
+import { redirectResponse, safeNext } from "@/lib/guard";
+import { createSession, sessionCookie } from "@/lib/session";
+import { findUserByUsername } from "@/lib/users";
+
+// Rate limiting for sign-in (per IP and per username) would go here, before the password check.
+export async function POST(req: Request) {
+  try {
+    requireSecret(env.SESSION_SECRET);
+    const form = await req.formData();
+    const next = String(form.get("next") ?? "");
+    const fail = () => redirectResponse(`/login?error=${encodeURIComponent("Wrong username or password")}${next ? `&next=${encodeURIComponent(next)}` : ""}`);
+    const parsed = credentialsSchema.safeParse({ username: form.get("username"), password: form.get("password") });
+    if (!parsed.success) return fail();
+    const db = await getDb();
+    const user = await findUserByUsername(db, parsed.data.username);
+    if (!user) {
+      await hashPassword(parsed.data.password); // spend the same time as a real check
+      return fail();
+    }
+    if (!(await verifyPassword(parsed.data.password, user.passwordHash))) return fail();
+    const session = await createSession(db, user.id, env.SESSION_SECRET);
+    return redirectResponse(safeNext(next), sessionCookie(session.value, session.expiresAt));
+  } catch (e) {
+    if (e instanceof MissingSecretError) return new Response(e.message, { status: 500 });
+    throw e;
+  }
+}