@deepraxis/app-template 0.1.0-dev.378725e → 0.1.0-dev.61eb886
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/SKILL.md +8 -30
- package/package.json +1 -1
package/SKILL.md
CHANGED
|
@@ -27,26 +27,18 @@ The template already contains sign-up, sign-in, sign-out, an account page with i
|
|
|
27
27
|
## Where to run commands
|
|
28
28
|
|
|
29
29
|
- **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.
|
|
30
|
-
- **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.
|
|
30
|
+
- **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.
|
|
31
31
|
|
|
32
32
|
## Steps
|
|
33
33
|
|
|
34
|
-
### 1.
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
| Path | Signals in the request | How much to ask before building |
|
|
38
|
-
|---|---|---|
|
|
39
|
-
| **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. |
|
|
40
|
-
| **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. |
|
|
41
|
-
| **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. |
|
|
42
|
-
|
|
43
|
-
Whatever the path, write down for yourself:
|
|
34
|
+
### 1. Turn the request into a short plan
|
|
35
|
+
Write down, for yourself:
|
|
44
36
|
- the pages;
|
|
45
37
|
- the data, which becomes tables and columns;
|
|
46
38
|
- who may do what, as roles (`user` and `admin` already exist);
|
|
47
39
|
- what is uploaded.
|
|
48
40
|
|
|
49
|
-
|
|
41
|
+
Ask the user only when the answer would change the data model, for example "can a customer book more than one slot?". Otherwise choose a sensible default, say what you chose, and keep going.
|
|
50
42
|
|
|
51
43
|
### 2. Create the project
|
|
52
44
|
```bash
|
|
@@ -62,33 +54,25 @@ Read `README.md` in the new project once. It has the folder map and the recipes
|
|
|
62
54
|
- **Rules** (prices, availability, who owns what) go in `lib/`. Pages and route handlers only call them.
|
|
63
55
|
- **Pages**: `app/<path>/page.tsx`. Protect them with `await requireUser("/<path>")` or `await requireAdmin("/<path>")` from `lib/guard.ts`.
|
|
64
56
|
- **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.
|
|
65
|
-
- **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.
|
|
57
|
+
- **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.
|
|
66
58
|
- **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"`.
|
|
67
59
|
- **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.
|
|
68
|
-
- **UI**: use the components in `components/ui/` and Tailwind classes.
|
|
60
|
+
- **UI**: use the components in `components/ui/` and Tailwind classes. Keep the existing layout and navigation.
|
|
69
61
|
|
|
70
62
|
### 4. Check before deploying
|
|
71
63
|
```bash
|
|
72
64
|
bun run typecheck && bun test && bun run build
|
|
73
65
|
```
|
|
74
|
-
|
|
66
|
+
Fix every error before you deploy. `bun run dev` serves the app locally if you want to look at it first.
|
|
75
67
|
|
|
76
68
|
### 5. Deploy
|
|
77
69
|
```bash
|
|
78
70
|
praxis app deploy
|
|
79
71
|
```
|
|
80
|
-
It builds, uploads only the changed files, creates a version, deploys it, keeps or creates the secrets and calls the `healthcheck` path.
|
|
72
|
+
It builds, uploads only the changed files, creates a version, deploys it, keeps or creates the secrets and calls the `healthcheck` path. It prints the URL. The first deploy takes about one to two minutes.
|
|
81
73
|
|
|
82
74
|
### 6. Verify it like a user
|
|
83
75
|
- 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.
|
|
84
|
-
- 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.
|
|
85
|
-
```bash
|
|
86
|
-
U=<url>; J=$(mktemp)
|
|
87
|
-
curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' -c $J -d 'username=admin&password=<password>' $U/api/auth/register
|
|
88
|
-
curl -s -b $J $U/admin | grep -c '<something only admins see>'
|
|
89
|
-
curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' $U/admin # signed out: redirect to /login
|
|
90
|
-
```
|
|
91
|
-
Match on plain words, not on numbers next to markup: React may split "Books (2)" into several text nodes in the HTML.
|
|
92
76
|
- **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.
|
|
93
77
|
|
|
94
78
|
### 7. Report to the user
|
|
@@ -103,8 +87,6 @@ Keep technical words out of the report (no "worker", "D1" or "migration").
|
|
|
103
87
|
## Changing the app later
|
|
104
88
|
Edit the code, then run step 4 and step 5 again. The data in D1 and R2 stays across deploys.
|
|
105
89
|
|
|
106
|
-
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).
|
|
107
|
-
|
|
108
90
|
If a deploy breaks something, go back to the previous version at once and then fix forward:
|
|
109
91
|
```bash
|
|
110
92
|
praxis app rollback # the version before the current one
|
|
@@ -119,9 +101,6 @@ praxis app rollback --to <version_id>
|
|
|
119
101
|
| What happened (deploys, failures)? | `praxis api application worker event list --worker <worker_id>` | `praxis.application.workers.events.list({ path: { worker_id } })` |
|
|
120
102
|
| Which secrets are set? | `praxis api application worker secret list --worker <worker_id>` | `praxis.application.workers.secrets.list({ path: { worker_id } })` |
|
|
121
103
|
| Find the worker id | `praxis api application worker list` | `praxis.application.workers.list()` |
|
|
122
|
-
| Delete the app | `praxis api application worker delete <worker_id> --yes` | `praxis.application.workers.delete({ path: { worker_id } })` |
|
|
123
|
-
|
|
124
|
-
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.
|
|
125
104
|
|
|
126
105
|
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.
|
|
127
106
|
|
|
@@ -140,4 +119,3 @@ Runtime logs are not available yet. To find out why a page fails, reproduce the
|
|
|
140
119
|
| 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 |
|
|
141
120
|
| Sign-in answers 500 "SESSION_SECRET is not configured" | The secret was removed from `praxis.jsonc` | Put `"SESSION_SECRET": "generate"` back and deploy |
|
|
142
121
|
| A build error about modules or `import.meta.url` | `vinext-plugins.ts` was changed or removed | Restore it from the template |
|
|
143
|
-
| Deploy fails with `Completion token has already been consumed` | A rare platform retry issue | Run `praxis app deploy` again |
|
package/package.json
CHANGED