acrylblends 0.11.0 → 1.0.0-rc.1

package/README.md

@@ -103,8 +103,7 @@ npm install
 npm run dev
 ```
 
-The `nodejs` template is a minimal Acryl app. `bun` is the same for Bun (experimental). `acryl-app` is a Cordis app built from plugins,
-with an agent that can extend it while it runs. See the
+The templates are the same through `npm create acrylblends` and `acrylblends init`: `blank`, `nodejs`, `notes`, `chat`, `todo` and `agent` (a Cordis app with an agent that can extend it while it runs; `acryl-app` is its old name). See the
 [create-acrylblends guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/create-acrylblends.md).
 
 ## A first API
@@ -270,18 +269,17 @@ See [Node.js](https://github.com/acryldev/acryl/blob/main/docs/framework/getting
 | `acrylblends/accepts`, `adapter`, `cookie`, `factory`, `html`, `route`, `streaming`, `ws`, `conninfo` | helpers ([helpers docs](https://github.com/acryldev/acryl/tree/main/docs/framework/helpers)) |
 | `acrylblends/http-exception` | `HTTPException` |
 | `acrylblends/router/*` | the routers: `reg-exp-router`, `smart-router`, `trie-router`, `pattern-router`, `linear-router` ([routers](https://github.com/acryldev/acryl/blob/main/docs/framework/concepts/routers.md)) |
-| `acrylblends/utils/*` | the utilities the framework is built from |
 | `acrylblends/tiny`, `acrylblends/quick` | the presets: `Acryl` with another router (`PatternRouter`; `LinearRouter` and `TrieRouter`) ([presets](https://github.com/acryldev/acryl/blob/main/docs/framework/api/presets.md)) |
 | `acrylblends/cache`, `acrylblends/mount` | the cache middleware and mounting another framework's fetch handler |
 | `acrylblends/ssg` | static site generation: `toSSG` writes every route as a file ([SSG helper](https://github.com/acryldev/acryl/blob/main/docs/framework/helpers/ssg.md)) |
 | `acrylblends/proxy`, `acrylblends/dev` | the proxy helper and the dev helpers (`showRoutes`, `inspectRoutes`, `getRouterName`) |
 | `acrylblends/jsx` | JSX on the server: `jsxImportSource: 'acrylblends/jsx'`, `.tsx` files run on Node with `node --import acrylblends/node-server/register`, with `jsx/streaming`, and `acrylblends/jsx-renderer` for a layout behind `c.render` ([JSX guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/jsx.md)) |
 | `acrylblends/jsx/dom` | JSX in the browser: hooks and `render` (needs the DOM library) ([client components](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/jsx-dom.md)); on Node, `clientModules` serves them to the browser without a bundler ([guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/client-modules.md)) |
+| `acrylblends/drivers` | the driver contract of the agent panel (`ChatDriver`, `TerminalDriver`, `Drivers`), for plugins that add an agent to the panel |
 | `acrylblends/css` | CSS in JSX: `css`, `cx`, `keyframes`, `Style` ([CSS helper](https://github.com/acryldev/acryl/blob/main/docs/framework/helpers/css.md)) |
 | `acrylblends/node-server` | `serve`, `createAdaptorServer`, `getRequestListener`; with `node-server/serve-static`, `node-server/conninfo`, and `node-server/register` (compiles `.tsx` with the app's `typescript`); `clientModules` and `buildClientModules` (client components without a bundler) |
 
-Every subpath is listed in the package's `exports`. The adapters of other runtimes are being ported. The docs mark them "not yet available" until they ship
-([FAQ](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/faq.md)).
+Every subpath in the table is listed in the package's `exports` and is covered by semver from 1.0, except the ones marked experimental: `acrylblends/bun` and the door (`door/*`, `cordis/door`), which are development tools. The ported core's utilities (`utils/*`) and the base-class chunk are internal and not exported. Node.js is the runtime the package is verified on; the upstream's adapters for AWS Lambda, Lambda@Edge, Cloudflare, Vercel, Netlify and Service Workers are not part of the package ([Other runtimes](https://github.com/acryldev/acryl/blob/main/docs/framework/getting-started/other-runtimes.md)).
 
 To extend the context's typed variables, augment the root module:
 
@@ -295,8 +293,8 @@ declare module 'acrylblends' {
 
 ## Upgrading from 0.4
 
-From 0.5 the package's root is the framework. `App` and `AppRequest`, the 0.4 names, still work as deprecated aliases of `Acryl` and
-`AcrylRequest` for one release. The scaffolding API that was the root in 0.4 is now `acrylblends/cli`. See
+From 0.5 the package's root is the framework. `App` and `AppRequest`, the 0.4 names, were kept as deprecated aliases of `Acryl` and
+`AcrylRequest` and are removed in 1.0. The scaffolding API that was the root in 0.4 is now `acrylblends/cli`. See
 [Migration from 0.4](https://github.com/acryldev/acryl/blob/main/docs/framework/cordis/migration-from-0-4.md).
 
 ## The acrylblends command

package/dist/index.d.ts

@@ -44,9 +44,15 @@ export declare function runCli(argv: readonly string[], io?: Io): Promise<number
 //#endregion
 //#region src/templates.d.ts
 /** The templates, all Cordis apps: a web app with a page and a client component (nodejs), a notes app and a chat app on the db port (notes, chat), a blank app on the router, a todo list on the router and state, and the blank app with the offline agent. */
-export declare const TEMPLATES: readonly ["nodejs", "notes", "chat", "blank", "todo", "agent"];
+export declare const TEMPLATES: readonly ["blank", "nodejs", "notes", "chat", "todo", "agent"];
 type Template = (typeof TEMPLATES)[number];
+/** One line per template: the single list `acrylblends init` and `create-acrylblends` both show (`create-acrylblends` tests that its own copy equals this one). */
+export declare const TEMPLATE_SUMMARY: Record<(typeof TEMPLATES)[number], string>;
+/** Names that were templates once and still work: `create-acrylblends --template acryl-app` made the agent app. */
+export declare const TEMPLATE_ALIASES: Record<string, Template>;
 export declare function isTemplate(value: string): value is Template;
+/** The template a name means: itself, or what an old name stands for; undefined for anything else. */
+export declare function resolveTemplate(value: string): Template | undefined;
 /**
  * The `templates/` folder of this package. The module sits at different depths in source (`src/`) and in the build
  * (`dist/`), so walk up until a `templates` folder holds the `blank` template.
@@ -137,5 +143,26 @@ export declare function readTemplatePlugins(templateDir: string): string[];
 /** Add run-time dependencies to an app's package.json, keeping what is there and sorting the keys. Returns the names added. */
 export declare function mergeDependencies(appDir: string, dependencies: Readonly<Record<string, string>>): string[];
 //#endregion
-export type { AddOptions, InitOptions, Io, LibraryPlugin, Template };
+//#region src/upgrade.d.ts
+interface UpgradeOptions {
+  /** Library plugins to upgrade; none means every library plugin the app carries. */
+  readonly names: readonly string[];
+  readonly directory: string | undefined;
+  /** Show what would change and stop. */
+  readonly dryRun: boolean;
+  /** Replace a file the app edited too (the edited version is saved first). */
+  readonly force: boolean;
+  /** Print the diff of every changed file, not only of the edited ones. */
+  readonly diff: boolean;
+}
+/** Parse `upgrade [plugin...] [--dir <app>] [--dry-run] [--force] [--diff]`. */
+export declare function parseUpgradeOptions(argv: readonly string[]): UpgradeOptions;
+/**
+ * `acrylblends upgrade`: bring the library plugins an app carries (the router, the server, the door, `extensions`, ...) up to the version of this package. Each file is compared with what
+ * the app was given: an untouched file is replaced, a file the app edited stops the upgrade (it is shown as a diff and nothing changes) unless `--force`, which saves the edited version
+ * under `.acrylblends/upgrade-backup/` first. Returns the exit code: 0 done or nothing to do, 1 refused or failed.
+ */
+export declare function upgrade(options: UpgradeOptions, io: Io): Promise<number>;
+//#endregion
+export type { AddOptions, InitOptions, Io, LibraryPlugin, Template, UpgradeOptions };
 //# sourceMappingURL=index.d.ts.map