@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
package/README.md CHANGED
@@ -1,3 +1,105 @@
1
- # Temporary Holding Version
1
+ # @acryldev/create-blends
2
2
 
3
- 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.
3
+ Create an Acryl app with one command.
4
+
5
+ ```sh
6
+ npm create @acryldev/blends@latest my-app
7
+ ```
8
+
9
+ It asks which template you want, creates `my-app`, and prints what to run next. Other package managers work the same way: `pnpm create @acryldev/blends@latest`, `yarn create acrylblends`, `bun create acrylblends@latest`.
10
+
11
+ ## Templates
12
+
13
+ Every template is a Cordis app: `blend.yaml` lists the plugins that are mounted and every plugin is a folder in `plugins/`.
14
+
15
+ | Template | What you get |
16
+ | --- | --- |
17
+ | `blank` | the smallest app: the router, a server and one route, with a test |
18
+ | `nodejs` | a web app: routes, a server-rendered JSX page and a client component, with tests; run with Node.js 22.19 or newer |
19
+ | `notes` | a full-stack starter: accounts (scrypt, cookie session), notes in SQLite through the `db` port, validated forms, search, a JSON API with a typed test client, csrf on, a test for every route |
20
+ | `chat` | an AI chat starter: the answer streams token by token (Server-Sent Events) from an OpenAI-compatible API (DeepSeek by default, key only from `DEEPSEEK_API_KEY`), a client component with a Stop button that also stops the request to the model, history in SQLite, tests with a mock model |
21
+ | `todo` | a to-do list on the router and state: CRUD routes, a page, tests |
22
+ | `agent` | the blank app with an offline agent that builds plugins into the running app, through the door (`acryl-app` is the old name for it and still works) |
23
+
24
+ Every template includes `AGENTS.md`, `CLAUDE.md` and a copy of the framework documentation in `docs/framework/`, so a coding agent working in the folder reads the API from the folder.
25
+
26
+ ## Non-interactive use
27
+
28
+ Arguments for the initializer go after `--` with `npm create`:
29
+
30
+ ```sh
31
+ npm create @acryldev/blends@latest my-app -- --template nodejs --install --pm npm
32
+ ```
33
+
34
+ | Option | |
35
+ | --- | --- |
36
+ | `--template <name>` | `blank`, `nodejs`, `notes`, `chat`, `todo` or `agent` (the same list as `acrylblends init`; `acryl-app` still means `agent`; a bare name after the directory means the same: `npm create @acryldev/blends@latest my-app notes`) |
37
+ | `--desktop` | put the app inside the ACRYL frame: `npm run dev` opens it with the chat, the panels and Settings. Not with a starter from a source |
38
+ | `--install` | install the dependencies after creating the app |
39
+ | `--pm <manager>` | `npm`, `pnpm`, `yarn` or `bun` (default: the one that ran the command) |
40
+ | `-y`, `--yes` | ask nothing: template `nodejs`, directory `acrylblends-app` unless given |
41
+
42
+ ## Then
43
+
44
+ ```sh
45
+ cd my-app
46
+ npm install # unless you passed --install
47
+ npm run dev # prints its URL; GET / answers "Acryl!"
48
+ npm test
49
+ ```
50
+
51
+ ```ts
52
+ import { Acryl } from '@acryldev/blends'
53
+
54
+ const app = new Acryl()
55
+ app.get('/', (c) => c.text('Acryl!'))
56
+
57
+ export default app
58
+ ```
59
+
60
+ ## Where an app's shared code comes from
61
+
62
+ An app made here holds two kinds of code that are not its own, and says so in its files:
63
+
64
+ - **The library plugins** (`plugins/door`, `@acryldev/router`, `desktop`, `instance`, `plugin-share` and the others named in
65
+ `plugins/library.json`) are copies of the acrylblends library, from <https://github.com/acrylblends/acrylblends>.
66
+ `plugins/library.lock.json` records the release each came from and a hash of every file. `npx acrylblends upgrade` brings them to the
67
+ newest release; when a file was changed here, it stops, shows the diff and changes nothing (`--force` replaces it and keeps a backup in
68
+ `.acryl/upgrade-backup/`). Fix a library plugin in acrylblends, not here; your own code goes in a plugin of your own under `plugins/`.
69
+ - **The frame and its parts** (`@acryldev/blends-frame`, `@acryldev/settings` and the other `@acryldev/*` packages in
70
+ `package.json`) and the framework (`acrylblends`) come from npm, built from the same repository (`ide/` and `packages/`). `npm install`
71
+ installs them; `npx acrylblends upgrade` moves `package.json` to the release it brings.
72
+
73
+ Everything else (`blend.yaml`, `src/`, your plugins under `plugins/`) is the app's own, and an upgrade never touches it.
74
+
75
+ ## Links
76
+
77
+ - Documentation: https://acrylblends.github.io/docs (mirrored at https://acryl.dev/docs)
78
+ - The framework package: https://www.npmjs.com/package/acrylblends
79
+ - Source and issues: https://github.com/acrylblends/acrylblends
80
+ - Blends registry: https://acrylblends.github.io/blends
81
+ - ACRYL: https://acryl.dev
82
+
83
+ MIT license.
84
+
85
+ ## The `notes` template
86
+
87
+ `npm create @acryldev/blends@latest my-notes -- --template notes` makes a small full-stack app, written to be read and copied:
88
+
89
+ - sign up and log in (scrypt password hashes from `node:crypto`, a random token in an `httpOnly` cookie, sessions in the database);
90
+ - notes in SQLite through the built-in `node:sqlite` (Node.js 22.19 or later, nothing native to install), with create, edit, delete and search forms, server-side validation with messages on the page, and a redirect (303) after each POST;
91
+ - a JSON API under `/api/notes` that shares the validation rules, with a test that uses the typed `testClient`;
92
+ - csrf protection on, a test for every route, and an `AGENTS.md` that describes the files so a coding agent can extend it;
93
+ - a live character counter and an instant filter written as a small script in the page. When the client components of `acrylblends/jsx/dom` can be served without a bundler (planned for 0.7.2), they will replace that script here.
94
+
95
+ `npx acrylblends add desktop` followed by `npm install` and `npm run desktop` runs it as a desktop window (see `docs/framework/getting-started/desktop.md`).
96
+
97
+ ## Templates from a repository or a package
98
+
99
+ ```sh
100
+ npm create @acryldev/blends@latest my-app github:owner/repo[#ref]
101
+ npm create @acryldev/blends@latest my-app @scope/name[@version]
102
+ npm create @acryldev/blends@latest my-app ./template.tgz
103
+ ```
104
+
105
+ The source is downloaded as a tarball (never cloned) or packed with `npm pack --ignore-scripts`, unpacked, and read: it must hold an `acryl.template.json` (`name`, `description`, optional `plugins`), it is checked for secrets, and only then is the folder created. Nothing of the template is installed or run; if its `package.json` defines install scripts they are listed, and `--install` prints what will run before it runs. See the create-acrylblends guide in `docs/framework/guides/`.
@@ -0,0 +1,12 @@
1
+ #!/usr/bin/env node
2
+ // A Node too old to run the package is told so in plain words, before anything is loaded that would fail on it.
3
+ const [major, minor] = process.versions.node.split('.').map(Number)
4
+ if (major < 22 || (major === 22 && minor < 19)) {
5
+ console.error(
6
+ `Node 22.19+ needed, you have ${process.versions.node}: install it from https://nodejs.org or with nvm (nvm install 22).`,
7
+ )
8
+ process.exit(1)
9
+ }
10
+ const { runCreate } = await import('../dist/index.js')
11
+
12
+ process.exitCode = await runCreate(process.argv.slice(2))
@@ -0,0 +1,94 @@
1
+ /**
2
+ * The one place this package names the framework. The templates are written with `__PACKAGE__` and `__RANGE__` (the range is stamped at create time from the framework version this package carries, see `frameworkRange`), and the text of `AGENTS.md` with
3
+ * `__PACKAGE__`, so a rename (for example to `acryl`) is a change here and in `scripts/lib/names.mjs`, which a test keeps equal.
4
+ */
5
+ export declare const PACKAGE = "@acryldev/blends";
6
+ export declare const CLASS = "Acryl";
7
+ export declare const CREATE = "@acryldev/create-blends";
8
+ /** The file that makes a folder a template other people can create apps from (`${CREATE} <name> github:owner/repo`). */
9
+ export declare const TEMPLATE_MANIFEST = "acryl.template.json";
10
+ /** How the bytes of a source are obtained; real by default, replaced in tests. */
11
+ interface Fetchers {
12
+ /** The body at a URL (a GitHub tarball); `headers` carry the person's GitHub token for a private repository. */
13
+ download(url: string, headers?: Readonly<Record<string, string>>): Promise<Uint8Array>;
14
+ /** The person's GitHub token (GITHUB_TOKEN, GH_TOKEN, else `gh auth token`), asked for only when a repository is not public. */
15
+ githubToken?(): string | undefined;
16
+ /** `npm pack <spec> --ignore-scripts` into `dest`; the path of the tarball. */
17
+ pack(spec: string, dest: string): string;
18
+ }
19
+ /**
20
+ * The templates: the same list as acrylblends init (the framework package makes every one of them; @acryldev/create-blends delegates). A test compares this list and its summaries with the
21
+ * framework package's, so they cannot drift.
22
+ */
23
+ export declare const TEMPLATES: readonly ["blank", "nodejs", "notes", "chat", "todo", "agent"];
24
+ export type Template = (typeof TEMPLATES)[number];
25
+ export declare const TEMPLATE_SUMMARY: Record<Template, string>;
26
+ /** Names that were templates once and still work. */
27
+ export declare const TEMPLATE_ALIASES: Record<string, Template>;
28
+ export declare const PACKAGE_MANAGERS: readonly ["npm", "pnpm", "yarn", "bun"];
29
+ export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
30
+ /** The version of this package. */
31
+ export declare const VERSION: string;
32
+ export declare const HELP: string;
33
+ /** A command line mistake. The command prints it with the help text and exits 2. */
34
+ export declare class UsageError extends Error {
35
+ name: string;
36
+ }
37
+ export interface Io {
38
+ stdout: {
39
+ write(text: string): unknown;
40
+ };
41
+ stderr: {
42
+ write(text: string): unknown;
43
+ };
44
+ cwd: string;
45
+ env: Record<string, string | undefined>;
46
+ /** Ask one question; `undefined` when there is no terminal to ask on. */
47
+ ask: ((question: string) => Promise<string>) | undefined;
48
+ /** Run a program, showing its output; resolves to the exit code. */
49
+ run(command: string, args: string[], cwd: string): Promise<number>;
50
+ /** How a template source is fetched; the real network and npm by default. */
51
+ fetchers?: Fetchers;
52
+ }
53
+ export declare function processIo(): Io;
54
+ export interface CreateOptions {
55
+ directory: string | undefined;
56
+ template: Template | undefined;
57
+ install: boolean;
58
+ /**
59
+ * Put the app inside the ACRYL frame, as `acrylblends init --desktop` does. On for a template and a registry blueprint, on for another source only with
60
+ * `--desktop`, off with `--bare`.
61
+ */
62
+ desktop: boolean;
63
+ /** Start the app when it is created and installed (`<pm> run dev`), only when there is a terminal to show it in. Off with `--no-start`. */
64
+ start: boolean;
65
+ pm: PackageManager | undefined;
66
+ yes: boolean;
67
+ /** `github:owner/repo[#ref]`, `@scope/name`, a packed `.tgz`, a folder, or a registry id: a template from outside this package. */
68
+ source: string | undefined;
69
+ /** Where registry ids are read from; the public registry by default. */
70
+ registry: string | undefined;
71
+ }
72
+ export declare function isTemplate(value: string): value is Template;
73
+ /** The template a name means: itself, or what an old name stands for. */
74
+ export declare function resolveTemplate(value: string): Template | undefined;
75
+ export declare function parseCreateOptions(argv: readonly string[]): CreateOptions;
76
+ /** A valid package name from a directory name: lower case letters, digits and dashes. */
77
+ export declare function nameFrom(directory: string): string;
78
+ /**
79
+ * The range a created app asks for: the framework version this package was released with, so a new app depends on the release that made it (and gets what that release's
80
+ * commands can do), never an older one. A caret range, so it also takes the newer patch releases.
81
+ */
82
+ export declare function frameworkRange(): string;
83
+ export declare function replacePlaceholders(text: string, name: string): string;
84
+ /**
85
+ * A new app is a git repository from the start, as `acrylblends init` makes it: the frame's versions, Files and Changes work on it, and its first
86
+ * version is the app as created. A folder that already is a repository, or a machine without git, is left alone.
87
+ */
88
+ export declare function startRepository(directory: string): void;
89
+ /** An app with the extensions row (what plugin-share installs through) and no plugin-share row: a starter older than sharing. */
90
+ export declare function lacksPluginShare(directory: string): boolean;
91
+ /** Create the app. Returns the exit code: 0 done, 1 refused or failed, 2 a usage error. Never calls `process.exit`. */
92
+ export declare function runCreate(argv: readonly string[], io?: Io): Promise<number>;
93
+ export {};
94
+ //# sourceMappingURL=index.d.ts.map