create-acrylblends 0.2.8 → 0.3.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.
- package/README.md +5 -4
- package/dist/index.d.ts +1 -3
- package/dist/index.js +20 -198
- package/dist/index.js.map +1 -1
- package/docs/framework/README.md +2 -2
- package/docs/framework/UPSTREAM.md +1 -1
- package/docs/framework/getting-started/basic.md +1 -2
- package/docs/framework/getting-started/desktop.md +1 -1
- package/docs/framework/guides/bring-your-own-tool.md +216 -0
- package/docs/framework/guides/create-acrylblends.md +5 -4
- package/docs/framework/guides/data.md +2 -1
- package/docs/framework/upstream.json +3 -3
- package/package.json +2 -3
- package/templates/bun/gitignore +0 -2
- package/templates/bun/package.json +0 -19
- package/templates/bun/src/index.ts +0 -7
- package/templates/bun/test/app.test.ts +0 -8
- package/templates/bun/tsconfig.json +0 -15
- package/templates/chat/gitignore +0 -7
- package/templates/chat/migrations/001-chat.sql +0 -12
- package/templates/chat/package.json +0 -26
- package/templates/chat/src/app.ts +0 -8
- package/templates/chat/src/chat-app.ts +0 -100
- package/templates/chat/src/client/chat.tsx +0 -115
- package/templates/chat/src/client/tsconfig.json +0 -15
- package/templates/chat/src/db.ts +0 -53
- package/templates/chat/src/index.ts +0 -27
- package/templates/chat/src/llm.ts +0 -42
- package/templates/chat/src/page.tsx +0 -38
- package/templates/chat/test/chat.test.ts +0 -165
- package/templates/chat/test/server.test.ts +0 -59
- package/templates/chat/tsconfig.json +0 -19
- package/templates/nodejs/gitignore +0 -3
- package/templates/nodejs/package.json +0 -23
- package/templates/nodejs/src/app.ts +0 -10
- package/templates/nodejs/src/client/counter.tsx +0 -12
- package/templates/nodejs/src/client/tsconfig.json +0 -15
- package/templates/nodejs/src/index.ts +0 -21
- package/templates/nodejs/src/page.tsx +0 -26
- package/templates/nodejs/src/routes.ts +0 -10
- package/templates/nodejs/test/app.test.ts +0 -40
- package/templates/nodejs/test/server.test.ts +0 -48
- package/templates/nodejs/tsconfig.json +0 -19
- package/templates/notes/gitignore +0 -7
- package/templates/notes/migrations/001-notes.sql +0 -18
- package/templates/notes/package.json +0 -26
- package/templates/notes/src/app.ts +0 -8
- package/templates/notes/src/auth.ts +0 -57
- package/templates/notes/src/client/counter.tsx +0 -21
- package/templates/notes/src/client/tsconfig.json +0 -15
- package/templates/notes/src/db.ts +0 -60
- package/templates/notes/src/index.ts +0 -27
- package/templates/notes/src/notes-app.ts +0 -205
- package/templates/notes/src/schema.ts +0 -38
- package/templates/notes/src/views.tsx +0 -134
- package/templates/notes/test/notes.test.ts +0 -252
- package/templates/notes/test/server.test.ts +0 -59
- package/templates/notes/tsconfig.json +0 -19
package/README.md
CHANGED
|
@@ -10,11 +10,12 @@ It asks which template you want, creates `my-app`, and prints what to run next.
|
|
|
10
10
|
|
|
11
11
|
## Templates
|
|
12
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
|
+
|
|
13
15
|
| Template | What you get |
|
|
14
16
|
| --- | --- |
|
|
15
|
-
| `nodejs` |
|
|
16
|
-
| `
|
|
17
|
-
| `notes` | a full-stack starter: accounts (scrypt, cookie session), notes in SQLite (`node:sqlite`), validated forms, search, a JSON API with a typed test client, csrf on, a test for every route |
|
|
17
|
+
| `nodejs` | a web app: routes, a server-rendered JSX page and a client component, with tests; run with Node.js 22.19 or newer |
|
|
18
|
+
| `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 |
|
|
18
19
|
| `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 |
|
|
19
20
|
| `acryl-app` | a Cordis app built from plugins, with an agent that can extend it while it runs (the same app `npx acrylblends init --template agent` creates) |
|
|
20
21
|
|
|
@@ -30,7 +31,7 @@ npm create acrylblends@latest my-app -- --template nodejs --install --pm npm
|
|
|
30
31
|
|
|
31
32
|
| Option | |
|
|
32
33
|
| --- | --- |
|
|
33
|
-
| `--template <name>` | `nodejs`, `notes`, `chat
|
|
34
|
+
| `--template <name>` | `nodejs`, `notes`, `chat` or `acryl-app` (a bare name after the directory means the same: `npm create acrylblends@latest my-app notes`) |
|
|
34
35
|
| `--install` | install the dependencies after creating the app |
|
|
35
36
|
| `--pm <manager>` | `npm`, `pnpm`, `yarn` or `bun` (default: the one that ran the command) |
|
|
36
37
|
| `-y`, `--yes` | ask nothing: template `nodejs`, directory `acrylblends-app` unless given |
|
package/dist/index.d.ts
CHANGED
|
@@ -19,7 +19,7 @@ interface Fetchers {
|
|
|
19
19
|
}
|
|
20
20
|
//#endregion
|
|
21
21
|
//#region src/index.d.ts
|
|
22
|
-
export declare const TEMPLATES: readonly ["nodejs", "notes", "chat", "
|
|
22
|
+
export declare const TEMPLATES: readonly ["nodejs", "notes", "chat", "acryl-app"];
|
|
23
23
|
export type Template = (typeof TEMPLATES)[number];
|
|
24
24
|
export declare const PACKAGE_MANAGERS: readonly ["npm", "pnpm", "yarn", "bun"];
|
|
25
25
|
export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
|
|
@@ -66,8 +66,6 @@ export declare function nameFrom(directory: string): string;
|
|
|
66
66
|
*/
|
|
67
67
|
export declare function frameworkRange(): string;
|
|
68
68
|
export declare function replacePlaceholders(text: string, name: string): string;
|
|
69
|
-
/** The guide for a coding agent in a created app: where the API is, how to run it, what must pass. */
|
|
70
|
-
export declare function agentsText(template: Exclude<Template, 'acryl-app'>, name: string): string;
|
|
71
69
|
/** Create the app. Returns the exit code: 0 done, 1 refused or failed, 2 a usage error. Never calls `process.exit`. */
|
|
72
70
|
export declare function runCreate(argv: readonly string[], io?: Io): Promise<number>;
|
|
73
71
|
//#endregion
|
package/dist/index.js
CHANGED
|
@@ -18,75 +18,6 @@ const CREATE = "create-acrylblends";
|
|
|
18
18
|
/** The file that makes a folder a template other people can create apps from (`${CREATE} <name> github:owner/repo`). */
|
|
19
19
|
const TEMPLATE_MANIFEST = "acryl.template.json";
|
|
20
20
|
//#endregion
|
|
21
|
-
//#region src/self-knowledge.ts
|
|
22
|
-
/** Where an agent looks for a skill: Claude Code reads `.claude/skills`, Codex and others read `.agents/skills`. The text is the same. */
|
|
23
|
-
const SKILL_FOLDERS = [".claude/skills/app-guide", ".agents/skills/app-guide"];
|
|
24
|
-
/** The defaults of an app made from this template, each with the one place that swaps it. */
|
|
25
|
-
function defaultRows(template, pkg) {
|
|
26
|
-
const rows = [];
|
|
27
|
-
if (template === "notes" || template === "chat") rows.push(`| Records | \`db\` port, SQLite (\`${pkg}/db/sqlite\`) | the opener, \`src/db.ts\`: call another provider there; no route, store or test changes |`);
|
|
28
|
-
rows.push(`| Small state | \`kv\` port, one JSON file (\`${pkg}/kv/json\`) | \`${pkg}/kv/db\` keeps it in the \`db\`; or a provider of your own; the opener is the only file that changes |`);
|
|
29
|
-
rows.push(template === "bun" ? `| Server | Bun | \`${pkg}/node-server\` for Node, or the adapter of another runtime; \`src/index.ts\` is the only file that changes |` : `| Server | Node (\`${pkg}/node-server\`) | the adapter of another runtime (\`${pkg}/bun\`, ...); \`src/index.ts\` is the only file that changes |`);
|
|
30
|
-
rows.push(`| Window | the browser | \`npx ${pkg} add desktop\` adds an Electron window on the same server; the app's code never imports Electron |`);
|
|
31
|
-
if (template === "nodejs" || template === "notes" || template === "chat") rows.push(`| Browser code | \`clientModules\`, no bundler | a bundler (Vite, esbuild) in front of \`src/client\`, wrapped in a plugin of its own |`);
|
|
32
|
-
return rows;
|
|
33
|
-
}
|
|
34
|
-
/** The section every app carries: the framework is a set of defaults, never a rule. */
|
|
35
|
-
function defaultsSection(template, pkg) {
|
|
36
|
-
return `## Defaults you can swap
|
|
37
|
-
|
|
38
|
-
The framework is not rigid. Every choice is a plugin behind a port, and what the app starts with is only a fallback. Name the default before you change it,
|
|
39
|
-
and swap it at the one place that opens it.
|
|
40
|
-
|
|
41
|
-
| Choice | Default | To swap it |
|
|
42
|
-
| --- | --- | --- |
|
|
43
|
-
${defaultRows(template, pkg).join("\n")}
|
|
44
|
-
|
|
45
|
-
- **An outside tool** (a database server, a bundler, a router such as Vike) joins the app as a provider: a plugin in \`plugins/<name>/\` that implements a port and
|
|
46
|
-
passes that port's conformance tests, then the opener names it. Postgres is such a provider and is not part of this package; add it when the app needs it.
|
|
47
|
-
- **The dependency rule:** only the opener imports a provider; everything else takes the port as an argument. \`${pkg} check-deps\` enforces it.
|
|
48
|
-
`;
|
|
49
|
-
}
|
|
50
|
-
/** Where the plugins are, said once. */
|
|
51
|
-
function pluginsSection(pkg) {
|
|
52
|
-
return `## Plugins
|
|
53
|
-
|
|
54
|
-
There is one plugin folder: \`plugins/\` at the root of the app. A plugin is a folder \`plugins/<name>/\` with an \`index.ts\`. \`${pkg} add <name>\` copies a library plugin
|
|
55
|
-
there; a plugin you or an agent write goes there too. Do not create \`src/plugins/\` or \`extensions/\`.
|
|
56
|
-
`;
|
|
57
|
-
}
|
|
58
|
-
/** The text of the one skill. It repeats nothing of the docs; it says where to look and how to work. */
|
|
59
|
-
function skillText(name, template, pkg) {
|
|
60
|
-
return `---
|
|
61
|
-
name: app-guide
|
|
62
|
-
description: How to change, run and check the ${name} app. Use it before adding a feature, a page, a route, a plugin or a dependency to this app, and before saying the work is done.
|
|
63
|
-
---
|
|
64
|
-
|
|
65
|
-
# Working in ${name}
|
|
66
|
-
|
|
67
|
-
1. **Read first.** \`AGENTS.md\` in this folder says how the app is laid out. The framework's API is in \`docs/framework/\`: start at \`docs/framework/README.md\`, and
|
|
68
|
-
\`docs/framework/api/summary.md\` is the one-page summary. Parts the docs mark "not yet available" are not in the package.
|
|
69
|
-
2. **Make the change small.** A route is a function from \`Request\` to \`Response\`: test it with \`await app.request('/path')\`. ${template === "notes" || template === "chat" ? "A change to the data is the next numbered file in `migrations/`; never edit one that has run." : "Keep new code in `src/` next to the code it extends."}
|
|
70
|
-
3. **One plugin folder.** A plugin lives in \`plugins/<name>/\` (\`${pkg} add <name>\` copies a library plugin there). There is no \`src/plugins/\` and no \`extensions/\`.
|
|
71
|
-
4. **Defaults are swappable.** The database, the key-value store, the server and the window are plugins behind ports. The table "Defaults you can swap" in \`AGENTS.md\` names each default and the one file that changes it. Never reach around a port to a driver: \`${pkg} check-deps\` fails the check.
|
|
72
|
-
5. **Look at the running app.** Start it with its dev script, open it in a browser, and check the page; the app has no door command yet, so do not look for one.
|
|
73
|
-
6. **Done means checked.** \`npm test\` and \`npm run check\` pass, and the change shows in the running app after a restart. No secret goes in a file or in \`git status\`: keys come from environment variables.
|
|
74
|
-
`;
|
|
75
|
-
}
|
|
76
|
-
/** Write the same text to `AGENTS.md` and `CLAUDE.md`, and the skill to every folder an agent looks in. */
|
|
77
|
-
function writeSelfKnowledge(target, agentsText, skill) {
|
|
78
|
-
const written = ["AGENTS.md", "CLAUDE.md"];
|
|
79
|
-
writeFileSync(join(target, "AGENTS.md"), agentsText);
|
|
80
|
-
writeFileSync(join(target, "CLAUDE.md"), agentsText);
|
|
81
|
-
for (const folder of SKILL_FOLDERS) {
|
|
82
|
-
const file = join(target, folder, "SKILL.md");
|
|
83
|
-
mkdirSync(dirname(file), { recursive: true });
|
|
84
|
-
writeFileSync(file, skill);
|
|
85
|
-
written.push(`${folder}/SKILL.md`);
|
|
86
|
-
}
|
|
87
|
-
return written;
|
|
88
|
-
}
|
|
89
|
-
//#endregion
|
|
90
21
|
//#region src/source.ts
|
|
91
22
|
/**
|
|
92
23
|
* Templates from outside this package: `github:owner/repo[#ref]`, a scoped npm package (`@scope/name[@version]`) or a packed tarball on disk.
|
|
@@ -310,7 +241,6 @@ const TEMPLATES = [
|
|
|
310
241
|
"nodejs",
|
|
311
242
|
"notes",
|
|
312
243
|
"chat",
|
|
313
|
-
"bun",
|
|
314
244
|
"acryl-app"
|
|
315
245
|
];
|
|
316
246
|
const PACKAGE_MANAGERS = [
|
|
@@ -324,7 +254,7 @@ const VERSION = createRequire(import.meta.url)("../package.json").version;
|
|
|
324
254
|
const HELP = `${CREATE} ${VERSION} - create an ${CLASS} app
|
|
325
255
|
|
|
326
256
|
Usage:
|
|
327
|
-
npm create ${PACKAGE}@latest [directory] [source] [-- options]
|
|
257
|
+
npm create ${PACKAGE}@latest [directory] [template | source] [-- options]
|
|
328
258
|
|
|
329
259
|
A source makes the app from someone else's template (it is downloaded and unpacked, nothing in it runs):
|
|
330
260
|
github:owner/repo[#ref] a GitHub repository, as a tarball (no clone)
|
|
@@ -333,7 +263,8 @@ A source makes the app from someone else's template (it is downloaded and unpack
|
|
|
333
263
|
A template is a folder with an ${TEMPLATE_MANIFEST} (name, description, plugins).
|
|
334
264
|
|
|
335
265
|
Options:
|
|
336
|
-
--template <name> nodejs, notes, chat,
|
|
266
|
+
--template <name> nodejs, notes, chat, acryl-app (asked when not given); a bare name after the directory means the same
|
|
267
|
+
(npm create ${PACKAGE}@latest my-app notes). Every template is a Cordis app: blend.yaml, plugins/
|
|
337
268
|
--install install the dependencies after creating the app (the lifecycle scripts it will run are listed first)
|
|
338
269
|
--pm <manager> ${PACKAGE_MANAGERS.join(", ")} (default: the one that ran this command, else npm)
|
|
339
270
|
-y, --yes ask nothing: template nodejs unless --template is given, directory ${PACKAGE}-app
|
|
@@ -385,16 +316,17 @@ function parseCreateOptions(argv) {
|
|
|
385
316
|
}
|
|
386
317
|
const { values, positionals } = parsed;
|
|
387
318
|
if (positionals.length > 2) throw new UsageError("takes a directory and at most one template source");
|
|
388
|
-
|
|
319
|
+
const bare = positionals[1] !== void 0 && isTemplate(positionals[1]) ? positionals[1] : void 0;
|
|
320
|
+
if (positionals[1] !== void 0 && values.template !== void 0) throw new UsageError("give a template (or a template source) or --template, not both");
|
|
389
321
|
if (values.template !== void 0 && !isTemplate(values.template)) throw new UsageError(`unknown template "${values.template}" (${TEMPLATES.join(", ")})`);
|
|
390
322
|
if (values.pm !== void 0 && !PACKAGE_MANAGERS.includes(values.pm)) throw new UsageError(`unknown package manager "${values.pm}" (${PACKAGE_MANAGERS.join(", ")})`);
|
|
391
323
|
return {
|
|
392
324
|
directory: positionals[0],
|
|
393
|
-
template: values.template,
|
|
325
|
+
template: bare ?? values.template,
|
|
394
326
|
install: values.install === true,
|
|
395
327
|
pm: values.pm,
|
|
396
328
|
yes: values.yes === true,
|
|
397
|
-
source: positionals[1]
|
|
329
|
+
source: bare === void 0 ? positionals[1] : void 0
|
|
398
330
|
};
|
|
399
331
|
}
|
|
400
332
|
const parse = (argv) => parseArgs({
|
|
@@ -427,7 +359,6 @@ function walkUp(from, test) {
|
|
|
427
359
|
}
|
|
428
360
|
}
|
|
429
361
|
const here = dirname(fileURLToPath(import.meta.url));
|
|
430
|
-
const templatesRoot = () => walkUp(here, (d) => existsSync(join(d, "templates", "nodejs")) ? join(d, "templates") : void 0);
|
|
431
362
|
/** The framework docs: the copy `prepack` puts in the package, or `docs/framework` of the repository. */
|
|
432
363
|
const docsRoot = () => walkUp(here, (d) => existsSync(join(d, "docs", "framework", "README.md")) ? join(d, "docs", "framework") : void 0);
|
|
433
364
|
/**
|
|
@@ -441,91 +372,6 @@ function frameworkRange() {
|
|
|
441
372
|
function replacePlaceholders(text, name) {
|
|
442
373
|
return text.replaceAll("__APP_NAME__", name).replaceAll("__PACKAGE__", PACKAGE).replaceAll("__CLASS__", CLASS).replaceAll("__RANGE__", frameworkRange());
|
|
443
374
|
}
|
|
444
|
-
/** The guide for a coding agent in a created app: where the API is, how to run it, what must pass. */
|
|
445
|
-
function agentsText(template, name) {
|
|
446
|
-
const run = {
|
|
447
|
-
nodejs: "npm run dev",
|
|
448
|
-
notes: "npm run dev",
|
|
449
|
-
chat: "npm run dev",
|
|
450
|
-
bun: "bun run dev"
|
|
451
|
-
}[template];
|
|
452
|
-
const desktopNote = template === "nodejs" || template === "notes" || template === "chat" ? `\nTo run it as a desktop window: \`npx ${PACKAGE} add desktop\`, \`npm install\`, then \`npm run desktop\` (see \`docs/framework/getting-started/desktop.md\`).` : "";
|
|
453
|
-
const test = {
|
|
454
|
-
nodejs: "npm test` and `npm run check",
|
|
455
|
-
notes: "npm test` and `npm run check",
|
|
456
|
-
chat: "npm test` and `npm run check",
|
|
457
|
-
bun: "bun test` and `bun run check"
|
|
458
|
-
}[template];
|
|
459
|
-
const jsxNote = template === "nodejs" || template === "notes" || template === "chat" ? "Write pages in `.tsx` (see `src/" + (template === "notes" ? "views.tsx" : "page.tsx") + "`): the scripts in `package.json` run Node.js with `--import acrylblends/node-server/register`, which compiles `.tsx` with this app's own `typescript`, and `tsconfig.json` sets `jsx: react-jsx` with `jsxImportSource: acrylblends/jsx`. Render a component with `.toString()` and return it with `c.html(...)`. A command that starts the app without those scripts (a bare `node src/index.ts`) cannot load a `.tsx` file. Without a build step you can write the call JSX compiles to instead: `jsx('h1', { class: 'title' }, 'Hello')` from `'acrylblends/jsx'`, children after the props. See `docs/framework/guides/jsx.md`." : "Bun compiles `.tsx` itself: write pages in `.tsx`, render a component with `.toString()` and return it with `c.html(...)`. `jsx('h1', { class: 'title' }, 'Hello')` from `'acrylblends/jsx'` (children after the props) is the same thing without JSX syntax. See `docs/framework/guides/jsx.md`.";
|
|
460
|
-
const clientNote = template === "nodejs" ? `- **Client components** (run in the browser) live in \`src/client/\`, which has its own \`tsconfig.json\` (DOM types, no Node types); \`clientModules\` in \`src/app.ts\` compiles them when the browser asks, and \`npm run build\` compiles them once for production. See \`src/client/counter.tsx\` and \`docs/framework/guides/client-modules.md\`.\n` : "";
|
|
461
|
-
return `# ${name}
|
|
462
|
-
|
|
463
|
-
An ${CLASS} app (${template}${template === "bun" ? ", experimental" : ""}): handlers over the Web Standard \`Request\` and \`Response\`, from the \`${PACKAGE}\` package.
|
|
464
|
-
|
|
465
|
-
## The framework's API is in \`docs/framework/\`
|
|
466
|
-
|
|
467
|
-
Start at \`docs/framework/README.md\`; \`api/summary.md\` is the one-page summary. Import the class from \`'${PACKAGE}'\` and each middleware or helper from its own
|
|
468
|
-
subpath (\`'${PACKAGE}/cors'\`, \`'${PACKAGE}/validator'\`, ...). Parts marked "not yet available" in the docs are not in the package yet.
|
|
469
|
-
|
|
470
|
-
## This app
|
|
471
|
-
|
|
472
|
-
Run it with \`${run}\`. The routes are in \`${template === "bun" ? "src/index.ts" : template === "notes" ? "src/notes-app.ts" : template === "chat" ? "src/chat-app.ts" : "src/app.ts"}\`; an app is a function from \`Request\` to \`Response\`,
|
|
473
|
-
so test a route with \`await app.request('/path')\` and no server.${desktopNote}
|
|
474
|
-
|
|
475
|
-
${template === "notes" ? `
|
|
476
|
-
## Structure (a notes app: accounts, sessions, a database)
|
|
477
|
-
|
|
478
|
-
- \`src/db.ts\`: \`openNotesDb()\` (the \`db\` port on a SQLite file, \`data/notes.sqlite\` or \`$NOTES_DB\`, with \`migrations/\` applied on start; it returns \`{ db, close }\`) and \`notesStore(db)\`, the queries for notes. Every \`db\` call returns a promise: \`await\` it. Use \`?\` bindings, never string-built SQL. See \`docs/framework/guides/data.md\`.
|
|
479
|
-
- \`migrations/\`: the shape of the database, one numbered file per change (\`001-notes.sql\`). A file that has run is never edited; a change is the next file (\`002-name.sql\`).
|
|
480
|
-
- **The dependency rule:** only \`src/db.ts\` (the \`opener\` in \`package.json\`) opens the database. Every other file takes a \`Db\` (\`import type { Db } from '${PACKAGE}/db'\`) as an argument and never imports \`node:sqlite\`, \`pg\`, another driver or \`${PACKAGE}/db/sqlite\`. \`npm test\` and \`npm run check\` run \`${PACKAGE} check-deps\`, which names the file and line of a violation; do not move the \`opener\` entry to silence it.
|
|
481
|
-
- \`src/auth.ts\`: scrypt password hashes (\`node:crypto\`) and the \`sessions\` table; the cookie \`sid\` holds a random token.
|
|
482
|
-
- \`src/schema.ts\`: the rules for a note and for credentials. The HTML forms and the JSON API both use \`checkNote\`.
|
|
483
|
-
- \`src/views.tsx\`: the pages, as JSX components rendered to strings, and the small script for the instant filter.
|
|
484
|
-
- \`src/client/\`: client components, with their own \`tsconfig.json\` (browser types). \`counter.tsx\` is the live character counter. \`clientModules\` in \`notes-app.ts\` compiles them when the browser asks; \`npm run build\` compiles them once into \`dist/client\` for production. See \`docs/framework/guides/client-modules.md\`.
|
|
485
|
-
- \`src/notes-app.ts\`: \`createApp(db)\` (pages and forms, csrf on) and \`createApi(db)\` (the JSON API under \`/api/notes\`, chained so \`testClient\` is typed). \`src/app.ts\` opens the database (top-level \`await\`) and exports the app and \`close\`; \`src/index.ts\` serves it and closes the database on SIGTERM. Tests open \`openNotesDb(':memory:')\` and pass its \`db\` to \`createApp\`.
|
|
486
|
-
- \`test/notes.test.ts\`: a test for every route. A form POST in a test needs \`origin: 'http://localhost'\` (csrf) and the \`sid\` cookie from sign up.
|
|
487
|
-
- Forms answer an invalid input with status 400 and the same page with the messages; a successful POST redirects with 303.
|
|
488
|
-
- To add a column or a table: write the next migration (\`migrations/002-name.sql\`), then change \`notesStore\`, \`checkNote\`, the form and the list in \`views.tsx\`, and the tests. Do not edit \`001-notes.sql\`.
|
|
489
|
-
|
|
490
|
-
## Before you ship
|
|
491
|
-
|
|
492
|
-
Read \`docs/framework/getting-started/deploy.md\`. In short:
|
|
493
|
-
|
|
494
|
-
- Install with \`npm ci --omit=dev\`, run \`npm run build\` (it compiles \`src/client\` once; with \`NODE_ENV=production\` only \`dist/client\` is served), and start with \`NODE_ENV=production npm start\` (\`typescript\` stays a runtime dependency: it compiles the \`.tsx\` pages at start).
|
|
495
|
-
- The app listens on \`127.0.0.1\`; set \`HOST=0.0.0.0\` only in a container. \`PORT\` chooses the port.
|
|
496
|
-
- Put the SQLite file outside the code folder (\`NOTES_DB=/var/lib/notes/notes.sqlite\`) and back it up.
|
|
497
|
-
- Behind an HTTPS reverse proxy set \`TRUST_PROXY=1\` and \`PUBLIC_ORIGIN=https://your.site\`, or the cookie is not \`Secure\` and csrf refuses form posts.
|
|
498
|
-
- \`npm test\` includes a test that starts the server and stops it with SIGTERM; keep it passing if you change \`src/index.ts\`.
|
|
499
|
-
` : ""}${template === "chat" ? `
|
|
500
|
-
## Structure (a chat app: a streamed answer, history in a database)
|
|
501
|
-
|
|
502
|
-
- **The dependency rule:** only \`src/db.ts\` (the \`opener\` in \`package.json\`) opens the database. Every other file takes a \`Db\` (\`import type { Db } from '${PACKAGE}/db'\`) as an argument and never imports \`node:sqlite\`, \`pg\`, another driver or \`${PACKAGE}/db/sqlite\`. \`npm test\` and \`npm run check\` run \`${PACKAGE} check-deps\`, which names the file and line of a violation; do not move the \`opener\` entry to silence it.
|
|
503
|
-
- \`src/llm.ts\`: \`Llm\`, what the app needs from a model (messages in, pieces out, an aborted signal stops the work), and \`openAiCompatible\`, which calls an OpenAI-compatible chat completions API with \`stream: true\`. The base URL is \`DEEPSEEK_BASE_URL\` (default \`https://api.deepseek.com\`), the model \`DEEPSEEK_MODEL\` (default \`deepseek-chat\`), the key **only** the environment variable \`DEEPSEEK_API_KEY\`, read at the moment of the call: never write it to a file, a response or a log.
|
|
504
|
-
- \`src/db.ts\`: \`openChatDb()\` (the \`db\` port on a SQLite file, \`data/chat.sqlite\` or \`$CHAT_DB\`, with \`migrations/\` applied on start; it returns \`{ db, close }\`) and \`chatStore(db)\`. The routes only call \`chatStore\`; keep SQL out of them. Every \`db\` call returns a promise: \`await\` it. The shape of the database is \`migrations/NNN-name.sql\`: to change it add the next numbered file and never edit one that has run. See \`docs/framework/guides/data.md\`.
|
|
505
|
-
- \`src/app.ts\` opens the database (top-level \`await\`) and exports the app and \`close\`; \`src/index.ts\` serves it and closes the database on SIGTERM. \`src/chat-app.ts\`: \`createApp(db, llm)\`. \`POST /api/chat\` answers Server-Sent Events: \`meta\` (the conversation id), a \`token\` per piece, then \`done\` or \`error\`. The request's signal (\`c.req.raw.signal\`) goes to the model call, so a closed tab or the Stop button stops the request to the model; what had arrived is kept.
|
|
506
|
-
- \`src/client/chat.tsx\`: the client component (own \`tsconfig.json\`, browser types): sends the message with \`fetch\`, reads the events as they arrive, shows the answer growing, and aborts on Stop. \`clientModules\` compiles it when the browser asks; \`npm run build\` compiles it once into \`dist/client\`. See \`docs/framework/guides/client-modules.md\`.
|
|
507
|
-
- \`test/chat.test.ts\` tests every route with a mock \`Llm\` (never the network); keep it that way. \`test/server.test.ts\` starts the real server and stops it with a signal.
|
|
508
|
-
- To try it with a real model: \`DEEPSEEK_API_KEY=... npm run dev\`.
|
|
509
|
-
|
|
510
|
-
## Before you ship
|
|
511
|
-
|
|
512
|
-
Read \`docs/framework/getting-started/deploy.md\`. In short: \`npm ci --omit=dev\`, \`npm run build\`, \`NODE_ENV=production npm start\`; the app listens on \`127.0.0.1\` (\`HOST=0.0.0.0\` only in a container); the SQLite file goes outside the code folder (\`CHAT_DB=/var/lib/chat/chat.sqlite\`) and is backed up; the model key is an environment variable of the service (a root-only environment file for systemd), never a file in the repository. Anyone who can reach the app can spend your key: put it behind a login or on a private network before it is public.
|
|
513
|
-
` : ""}
|
|
514
|
-
${defaultsSection(template, PACKAGE)}
|
|
515
|
-
${pluginsSection(PACKAGE)}
|
|
516
|
-
## Things that surprise people
|
|
517
|
-
|
|
518
|
-
- A page mounted at \`/x\` answers \`/x\`, not \`/x/\` (trailing slashes are strict); \`trimTrailingSlash()\` redirects.
|
|
519
|
-
- A \`json\` validator target reads the body only with a JSON \`Content-Type\`; a failure answers 400 with \`{ error, issues: [{ message, path }] }\`.
|
|
520
|
-
- \`throw new HTTPException(404, { message })\` answers an error response (plain text).
|
|
521
|
-
- \`testClient(app)\` from \`'${PACKAGE}/testing'\` types only routes chained on the \`new ${CLASS}()\` expression (\`new ${CLASS}().get(...).post(...)\`); headers such as a cookie go in the second argument of each call.
|
|
522
|
-
- **JSX:** ${jsxNote}
|
|
523
|
-
${clientNote}
|
|
524
|
-
## Before you say you are done
|
|
525
|
-
|
|
526
|
-
\`${test}\` pass.
|
|
527
|
-
`;
|
|
528
|
-
}
|
|
529
375
|
function copyDocs(target) {
|
|
530
376
|
const filter = (path) => !/(upstream\.json|UPSTREAM\.md)$/.test(path);
|
|
531
377
|
mkdirSync(join(target, "docs"), { recursive: true });
|
|
@@ -534,26 +380,8 @@ function copyDocs(target) {
|
|
|
534
380
|
filter
|
|
535
381
|
});
|
|
536
382
|
}
|
|
537
|
-
function copyTemplate(template, target, name) {
|
|
538
|
-
const written = [];
|
|
539
|
-
const walk = (from, to, prefix) => {
|
|
540
|
-
mkdirSync(to, { recursive: true });
|
|
541
|
-
for (const entry of readdirSync(from, { withFileTypes: true })) {
|
|
542
|
-
const targetName = prefix === "" && entry.name === "gitignore" ? ".gitignore" : entry.name;
|
|
543
|
-
if (entry.isDirectory()) walk(join(from, entry.name), join(to, targetName), `${prefix}${entry.name}/`);
|
|
544
|
-
else {
|
|
545
|
-
writeFileSync(join(to, targetName), replacePlaceholders(readFileSync(join(from, entry.name), "utf8"), name));
|
|
546
|
-
written.push(`${prefix}${targetName}`);
|
|
547
|
-
}
|
|
548
|
-
}
|
|
549
|
-
};
|
|
550
|
-
walk(join(templatesRoot(), template), target, "");
|
|
551
|
-
written.push(...writeSelfKnowledge(target, agentsText(template, name), skillText(name, template, PACKAGE)));
|
|
552
|
-
copyDocs(target);
|
|
553
|
-
return written;
|
|
554
|
-
}
|
|
555
383
|
const isEmpty = (directory) => !existsSync(directory) || readdirSync(directory).length === 0;
|
|
556
|
-
/** The `acrylblends` command of the installed framework package, which creates
|
|
384
|
+
/** The `acrylblends` command of the installed framework package, which creates every template. */
|
|
557
385
|
function acrylblendsBin() {
|
|
558
386
|
const pkgFile = createRequire(import.meta.url).resolve(`${PACKAGE}/package.json`);
|
|
559
387
|
const pkg = JSON.parse(readFileSync(pkgFile, "utf8"));
|
|
@@ -650,7 +478,7 @@ async function runCreate(argv, io = processIo()) {
|
|
|
650
478
|
const target = resolve(io.cwd, directory);
|
|
651
479
|
if (options.source !== void 0) return await createFromSource(options, target, directory, io);
|
|
652
480
|
const template = options.template ?? (ask ? await (async () => {
|
|
653
|
-
const answer = (await ask(`Which template do you want to use? (nodejs, notes, chat,
|
|
481
|
+
const answer = (await ask(`Which template do you want to use? (nodejs, notes, chat, acryl-app) [nodejs]: `)).trim() || "nodejs";
|
|
654
482
|
if (!isTemplate(answer)) throw new UsageError(`unknown template "${answer}" (${TEMPLATES.join(", ")})`);
|
|
655
483
|
return answer;
|
|
656
484
|
})() : "nodejs");
|
|
@@ -659,21 +487,16 @@ async function runCreate(argv, io = processIo()) {
|
|
|
659
487
|
return 1;
|
|
660
488
|
}
|
|
661
489
|
const name = nameFrom(target);
|
|
662
|
-
if (
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
], io.cwd) !== 0) return 1;
|
|
673
|
-
} else {
|
|
674
|
-
const files = copyTemplate(template, target, name);
|
|
675
|
-
io.stdout.write(`created ${name} (${template}) in ${target}: ${files.length} files, ${CLASS} docs in docs/framework\n`);
|
|
676
|
-
}
|
|
490
|
+
if (await io.run(process.execPath, [
|
|
491
|
+
acrylblendsBin(),
|
|
492
|
+
"init",
|
|
493
|
+
target,
|
|
494
|
+
"--template",
|
|
495
|
+
template === "acryl-app" ? "agent" : template,
|
|
496
|
+
"--name",
|
|
497
|
+
name,
|
|
498
|
+
"--yes"
|
|
499
|
+
], io.cwd) !== 0) return 1;
|
|
677
500
|
const pm = options.pm ?? PACKAGE_MANAGERS.find((m) => (io.env.npm_config_user_agent ?? "").startsWith(`${m}/`)) ?? "npm";
|
|
678
501
|
if (options.install) {
|
|
679
502
|
if (await io.run(pm, ["install"], target) !== 0) {
|
|
@@ -685,7 +508,6 @@ async function runCreate(argv, io = processIo()) {
|
|
|
685
508
|
nodejs: `${pm} run dev`,
|
|
686
509
|
notes: `${pm} run dev`,
|
|
687
510
|
chat: `${pm} run dev`,
|
|
688
|
-
bun: "bun run dev",
|
|
689
511
|
"acryl-app": `${pm} run dev`
|
|
690
512
|
}[template];
|
|
691
513
|
io.stdout.write(`\nNext:\n cd ${directory}\n${options.install ? "" : ` ${pm} install\n`} ${start}\n`);
|
|
@@ -700,6 +522,6 @@ async function runCreate(argv, io = processIo()) {
|
|
|
700
522
|
}
|
|
701
523
|
}
|
|
702
524
|
//#endregion
|
|
703
|
-
export { CLASS, CREATE, HELP, PACKAGE, PACKAGE_MANAGERS, TEMPLATES, TEMPLATE_MANIFEST, UsageError, VERSION,
|
|
525
|
+
export { CLASS, CREATE, HELP, PACKAGE, PACKAGE_MANAGERS, TEMPLATES, TEMPLATE_MANIFEST, UsageError, VERSION, frameworkRange, isTemplate, nameFrom, parseCreateOptions, processIo, replacePlaceholders, runCreate };
|
|
704
526
|
|
|
705
527
|
//# sourceMappingURL=index.js.map
|