@acryldev/create-blends 0.0.0-stage → 1.7.0

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.
Files changed (103) hide show
  1. package/README.md +104 -2
  2. package/bin/create-acrylblends.js +12 -0
  3. package/dist/index.d.ts +94 -0
  4. package/dist/index.js +1069 -0
  5. package/dist/index.js.map +1 -0
  6. package/docs/framework/LICENSE +23 -0
  7. package/docs/framework/README.md +70 -0
  8. package/docs/framework/agents/index.md +59 -0
  9. package/docs/framework/api/acryl.md +247 -0
  10. package/docs/framework/api/context.md +478 -0
  11. package/docs/framework/api/exception.md +80 -0
  12. package/docs/framework/api/index.md +12 -0
  13. package/docs/framework/api/presets.md +62 -0
  14. package/docs/framework/api/request.md +396 -0
  15. package/docs/framework/api/routing.md +303 -0
  16. package/docs/framework/api/summary.md +143 -0
  17. package/docs/framework/concepts/benchmarks.md +26 -0
  18. package/docs/framework/concepts/developer-experience.md +5 -0
  19. package/docs/framework/concepts/middleware.md +21 -0
  20. package/docs/framework/concepts/motivation.md +14 -0
  21. package/docs/framework/concepts/routers.md +63 -0
  22. package/docs/framework/concepts/stacks.md +235 -0
  23. package/docs/framework/concepts/web-standard.md +27 -0
  24. package/docs/framework/cordis/acryl-in-a-cordis-app.md +160 -0
  25. package/docs/framework/cordis/concepts.md +105 -0
  26. package/docs/framework/cordis/middleware.md +8 -0
  27. package/docs/framework/cordis/migration-from-0-3.md +111 -0
  28. package/docs/framework/cordis/migration-from-0-4.md +14 -0
  29. package/docs/framework/cordis/migration-from-dsh-webserver.md +109 -0
  30. package/docs/framework/cordis/migration-to-1-0.md +46 -0
  31. package/docs/framework/cordis/mounting.md +85 -0
  32. package/docs/framework/cordis/node-server.md +100 -0
  33. package/docs/framework/cordis/plugin-lifecycle.md +111 -0
  34. package/docs/framework/cordis/surfaces.md +71 -0
  35. package/docs/framework/cordis/transport-and-cancellation.md +57 -0
  36. package/docs/framework/cordis/validation.md +135 -0
  37. package/docs/framework/getting-started/basic.md +201 -0
  38. package/docs/framework/getting-started/bun.md +219 -0
  39. package/docs/framework/getting-started/deploy.md +133 -0
  40. package/docs/framework/getting-started/desktop.md +80 -0
  41. package/docs/framework/getting-started/nodejs.md +365 -0
  42. package/docs/framework/getting-started/other-runtimes.md +30 -0
  43. package/docs/framework/guides/best-practices.md +231 -0
  44. package/docs/framework/guides/bring-your-own-tool.md +218 -0
  45. package/docs/framework/guides/client-modules.md +210 -0
  46. package/docs/framework/guides/create-acrylblends.md +143 -0
  47. package/docs/framework/guides/data.md +314 -0
  48. package/docs/framework/guides/examples.md +3 -0
  49. package/docs/framework/guides/faq.md +19 -0
  50. package/docs/framework/guides/forms-and-sessions.md +235 -0
  51. package/docs/framework/guides/helpers.md +33 -0
  52. package/docs/framework/guides/jsx-dom.md +301 -0
  53. package/docs/framework/guides/jsx.md +487 -0
  54. package/docs/framework/guides/middleware.md +253 -0
  55. package/docs/framework/guides/production.md +80 -0
  56. package/docs/framework/guides/rpc.md +878 -0
  57. package/docs/framework/guides/testing.md +133 -0
  58. package/docs/framework/guides/validation.md +470 -0
  59. package/docs/framework/helpers/accepts.md +60 -0
  60. package/docs/framework/helpers/adapter.md +57 -0
  61. package/docs/framework/helpers/conninfo.md +77 -0
  62. package/docs/framework/helpers/cookie.md +232 -0
  63. package/docs/framework/helpers/css.md +282 -0
  64. package/docs/framework/helpers/dev.md +64 -0
  65. package/docs/framework/helpers/factory.md +180 -0
  66. package/docs/framework/helpers/html.md +123 -0
  67. package/docs/framework/helpers/jwt.md +184 -0
  68. package/docs/framework/helpers/proxy.md +115 -0
  69. package/docs/framework/helpers/route.md +143 -0
  70. package/docs/framework/helpers/ssg.md +390 -0
  71. package/docs/framework/helpers/streaming.md +224 -0
  72. package/docs/framework/helpers/testing.md +118 -0
  73. package/docs/framework/helpers/websocket.md +208 -0
  74. package/docs/framework/middleware/builtin/basic-auth.md +165 -0
  75. package/docs/framework/middleware/builtin/bearer-auth.md +138 -0
  76. package/docs/framework/middleware/builtin/body-limit.md +71 -0
  77. package/docs/framework/middleware/builtin/cache.md +99 -0
  78. package/docs/framework/middleware/builtin/combine.md +94 -0
  79. package/docs/framework/middleware/builtin/compress.md +59 -0
  80. package/docs/framework/middleware/builtin/context-storage.md +74 -0
  81. package/docs/framework/middleware/builtin/cors.md +134 -0
  82. package/docs/framework/middleware/builtin/csrf.md +105 -0
  83. package/docs/framework/middleware/builtin/etag.md +54 -0
  84. package/docs/framework/middleware/builtin/ip-restriction.md +69 -0
  85. package/docs/framework/middleware/builtin/jsx-renderer.md +283 -0
  86. package/docs/framework/middleware/builtin/jwk.md +192 -0
  87. package/docs/framework/middleware/builtin/jwt.md +145 -0
  88. package/docs/framework/middleware/builtin/language.md +232 -0
  89. package/docs/framework/middleware/builtin/logger.md +74 -0
  90. package/docs/framework/middleware/builtin/loopback-only.md +31 -0
  91. package/docs/framework/middleware/builtin/method-not-allowed.md +48 -0
  92. package/docs/framework/middleware/builtin/method-override.md +80 -0
  93. package/docs/framework/middleware/builtin/mount.md +103 -0
  94. package/docs/framework/middleware/builtin/pretty-json.md +53 -0
  95. package/docs/framework/middleware/builtin/request-id.md +87 -0
  96. package/docs/framework/middleware/builtin/secure-headers.md +247 -0
  97. package/docs/framework/middleware/builtin/timeout.md +98 -0
  98. package/docs/framework/middleware/builtin/timing.md +100 -0
  99. package/docs/framework/middleware/builtin/trailing-slash.md +74 -0
  100. package/docs/framework/middleware/third-party.md +4 -0
  101. package/docs/framework/workshop/README.md +294 -0
  102. package/docs/framework/workshop/facilitator.md +101 -0
  103. package/package.json +54 -3
@@ -0,0 +1,101 @@
1
+ # Facilitator notes: building inside the ACRYL frame
2
+
3
+ Read the handout first (`docs/framework/workshop/README.md`); this page is the room around it. The workshop changed shape again for the frame: the
4
+ app is created, then **opened inside ACRYL's IDE** (projects on the left, the app's page in the canvas, files/changes/terminals on the right), a
5
+ chat model works on the app from inside the frame, and coding agents run in terminal tabs in the same folder. The data layer, the desktop window and
6
+ the panel-first flow of the previous handout are gone.
7
+
8
+ The handout is written for **acrylblends 1.3.0 or newer** (the release whose `create --desktop` makes the framed app). A room on an older release is on the previous handout;
9
+ check with `npx acrylblends@latest --version` before the day.
10
+
11
+ ## Before the room: put this on every machine
12
+
13
+ | What | Why | How |
14
+ | --- | --- | --- |
15
+ | The preflight passing | it checks Node, npm, git, an agent with its login or key, a free port, and on Windows PowerShell and long paths | `npx acrylblends@latest preflight` ends with `Ready for the workshop.` |
16
+ | Node.js 22.19 or newer (24 and 26 tested) | the app runs TypeScript directly | `node -v`; the app's `scripts/check-node.cjs` refuses an older Node with a clear line |
17
+ | git, and a GitHub account with `gh auth login` | the first `npm run dev` makes the folder a git repository (Files and Changes need one); the last block forks the registry | `git --version`, `gh auth status` |
18
+ | One coding agent, logged in | block 5 starts it in a terminal tab; `claude`, `codex` and `pi` all worked | `codex login` once, or run `claude` once, or pi with `DEEPSEEK_API_KEY` in the terminal that starts `npm run dev` |
19
+ | One model key | block 3 adds it in Settings > Models; without it the chat shows a connect card | a DeepSeek key from <https://platform.deepseek.com>, or a Claude/ChatGPT subscription through Sign in with an account |
20
+ | A prepared app with `npm install` done | the first install brings the frame and the chat engine (about 500 MB together); a room on one Wi-Fi should not do it 20 times | run the handout's block 1 once per machine and keep the folder as `~/acryl-workshop/prepared/` |
21
+ | A warm npm cache | the first install dominates block 1 | the prepared app does it |
22
+
23
+ **The agent setting that decides the day.** The agents are configured to act rather than describe. Check on every machine that a plain request
24
+ produces files, not a plan: ask the prepared app's chat "add a line to the app's page" and watch the Changes panel. If it only describes, the model
25
+ is waiting for permission; the handout's sentence is "do it now".
26
+
27
+ **Agent-specific checks.** Codex answering `model_not_found` means the account does not have the default model: pick one it supports (`/model` in
28
+ codex, or `model = "..."` in `~/.codex/config.toml`). pi with DeepSeek needs `DEEPSEEK_API_KEY` in the environment of the terminal that runs `npm
29
+ run dev` (the terminal tabs inherit it); the preflight reports `PASS agent pi (DeepSeek key found)`. The package is
30
+ `@earendil-works/pi-coding-agent`.
31
+
32
+ ## Timings, from the rehearsal (this Mac, packed CLI, isolated HOME)
33
+
34
+ | Minutes | Block | Measured | If late |
35
+ | --- | --- | --- | --- |
36
+ | 0-10 | preflight and setup | preflight ~15 s; the prepared app skips create and install | never cut |
37
+ | 10-20 | create and open the frame | the first `npm install` dominates (the frame and the chat engine); the frame's first page is up in a few seconds after that | use the prepared app and open its frame |
38
+ | 20-25 | the first change at /app | the Files view opens `src/routes.ts`; stop and `npm run dev` reconnects the frame in a few seconds; the page shows the edit | cut `npm test` to the take-home |
39
+ | 25-30 | Settings > Models | the key saves with Apply (`Saved DeepSeek (deepseek-official).`); the page uses it after a reload | paste the key in the first-run card instead, Save and continue |
40
+ | 30-50 | chat builds the board | the chat writes into the app folder and Changes fills; the restart loop shows it at /app/board | if the model is slow, cut the board to one column |
41
+ | 50-65 | a coding agent in a terminal | the agent tab starts in the app folder (its prompt is `my-app`); `.acryl/bin/acryl look` prints the page in the frame's tile | demo one agent and let the room follow |
42
+ | 65-80 | upgrade an older app | `npx acrylblends@latest upgrade` reports every file it changed (the `frame` line is the new layout), then `npm install` and `npm run dev` | keep the report, skip the second app |
43
+ | 80-90 | publish (take-home) | the registry check merges in about two minutes | leave it as the take-home |
44
+
45
+ What the rehearsal verified end to end on this Mac: a packed CLI in an isolated HOME, the app opened by the frame with the app's page in a tab
46
+ (the first-run tile), the Preview Notice dismissed once, Settings > Models saving a key and the chat sending with it (against a local mock), a
47
+ terminal tab running commands in the app folder, the app's page edited and shown after a restart, the door seeing the page (`acryl look`), and an
48
+ app made by the previous release upgraded and opened by the frame.
49
+
50
+ ## What to say in the room
51
+
52
+ - **The frame is the product.** The point is not "an app with a chat sidebar"; it is that ACRYL's IDE hosts the app you are building: the app is
53
+ the page in the middle, its folder is the workspace, and the agents work in that folder.
54
+ - **Settings > Models is the key's home.** The key goes to the frame's own credentials store in the app's data folder (`~/.acryl/apps/<id>/data/`), never the app folder. The
55
+ first-run card writes the same store; either path is fine.
56
+ - **The loop is stop, start, look.** A source change needs `npm run dev` again; the port is stable per app, so the frame reconnects on the same
57
+ address and the app's tab is still there. If a chat tab comes to the front after the restart, press the `my-app` tab.
58
+ - **Two kinds of agent.** The chat (DSH's own, in the frame) and the coding agents in terminal tabs are different hands on the same folder; show
59
+ both and let people pick.
60
+ - **The door.** `.acryl/bin/acryl look` prints the page with refs, `act` clicks and types. In the frame the page is the tile, and the door sees
61
+ it. This is how an agent checks its own work.
62
+ - **Production is unchanged.** The frame, the chat and the agents are development tools; `NODE_ENV=production npm start` serves the app alone.
63
+
64
+ ## Windows
65
+
66
+ Windows PowerShell 5.1 has no `&&` (two lines, or `;`); PowerShell sets variables with `$env:NAME="value"`; cmd.exe's `Ctrl-C` asks `Terminate
67
+ batch job (Y/N)?` (answer `Y`); cmd.exe does not expand `~` (use `%USERPROFILE%`). `npm install` needs the "Desktop development with C++" workload
68
+ of Visual Studio Build Tools for the terminal package; the preflight notes it.
69
+
70
+ ## The no-network fallback
71
+
72
+ 1. Prepared apps with `npm install` done cover blocks 1, 2 and the frame; the models (chat and agents) still need a connection or a demo.
73
+ 2. Block 7's registry needs GitHub; if the venue is offline, publish from your machine on a hotspot at the end, or show the recording.
74
+ 3. Keep one phone hotspot for the room.
75
+
76
+ ## Demo script (five minutes, if the room is behind)
77
+
78
+ 1. Prepared app, frame open on the app's page: press `+`, open **AcrylDSH Chat**, ask for a sentence on the page. Narrate the Changes panel and
79
+ the restart loop.
80
+ 2. Open a **files** tab in the right panel and show the edit the model made.
81
+ 3. `+` → **Pi** (or Claude): the agent starts in the app folder; ask it for a route; run `.acryl/bin/acryl look` in that terminal and show the
82
+ page's snapshot.
83
+ 4. Settings > Models: show where the key lives and that it is not in the app folder.
84
+ 5. Show the registry listing with an app already published.
85
+
86
+ ## Resetting between sessions
87
+
88
+ Everything a person makes lives inside their app folder, its data folder in `~/.acryl/apps/` and `~/acryl-workshop`. To reset a machine, delete the app
89
+ folders and their data folders, and copy the prepared one back without its `.acryl/` folder; nothing is installed globally except the agent, `gh` and Node.
90
+ An app's data, the model key's credentials store included, lives in `~/.acryl/apps/<id>/data/`, outside the app folder. The `<id>` is written once into
91
+ the app folder's `.acryl/app.json` (gitignored): a copy that keeps that file shares the original's data and key, and a copy without it gets its own id
92
+ and an empty data folder.
93
+
94
+ ## What is still open
95
+
96
+ - The frame's chat tab takes the focus when it binds its session after a restart; the app's tab is one click away and the guide says so.
97
+ - The frame's address is stable across restarts: the launcher keeps the token in the app home (owner-only, atomic) and reuses it, so an open page
98
+ comes back by reloading its URL even if the browser lost its cookie. `npx acrylblends open` prints the address of the running frame;
99
+ `npx acrylblends open --new` rotates it (the old address stops working at once and the new one is printed). The frame-side banner that names the
100
+ command is still to come (after the 120 gate work).
101
+ - The one-click WebBoxes.ai deploy and the browser-only section stay TODO(M9) until that workspace is live.
package/package.json CHANGED
@@ -1,6 +1,57 @@
1
1
  {
2
2
  "name": "@acryldev/create-blends",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "1.7.0",
4
+ "description": "Create an Acryl app: npm create @acryldev/blends@latest",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "main": "./dist/index.js",
8
+ "types": "./dist/index.d.ts",
9
+ "bin": {
10
+ "create-blends": "./bin/create-acrylblends.js"
11
+ },
12
+ "exports": {
13
+ ".": {
14
+ "types": "./dist/index.d.ts",
15
+ "default": "./dist/index.js"
16
+ },
17
+ "./package.json": "./package.json"
18
+ },
19
+ "files": [
20
+ "bin",
21
+ "dist",
22
+ "docs"
23
+ ],
24
+ "engines": {
25
+ "node": ">=22.19.0"
26
+ },
27
+ "repository": {
28
+ "type": "git",
29
+ "url": "git+https://github.com/acryldev/acryl.git",
30
+ "directory": "framework/packages/create"
31
+ },
32
+ "homepage": "https://github.com/acryldev/acryl/tree/main/framework/packages/create#readme",
33
+ "keywords": [
34
+ "acryl",
35
+ "create",
36
+ "scaffold"
37
+ ],
38
+ "dependencies": {
39
+ "@acryldev/app-persistence": "^0.1.2",
40
+ "@acryldev/blends": "^1.7.0"
41
+ },
42
+ "publishConfig": {
43
+ "access": "public"
44
+ },
45
+ "devDependencies": {
46
+ "tsdown": "0.23.0",
47
+ "vitest": "5.0.3"
48
+ },
49
+ "bugs": {
50
+ "url": "https://github.com/acryldev/acryl/issues"
51
+ },
52
+ "scripts": {
53
+ "build": "tsdown",
54
+ "clean": "rm -rf dist",
55
+ "test": "vitest run"
56
+ }
6
57
  }