acrylblends 1.0.10 → 1.2.0

package/README.md

@@ -376,6 +376,15 @@ declare module 'acrylblends' {
 
 An app made with any 0.9.1 or later release moves with `acrylblends upgrade` (above); its edited files are never replaced silently.
 
+An app made by a published release from 0.7.8 on that still runs on the standalone layout also moves onto the ACRYL frame: `acrylblends upgrade` writes
+`scripts/ide-host.mjs`, the generated overlay (`cordis.patch.yml` with the app's own rows and the frame rows), `cordis.yml`, `app/runtime.mjs` and
+`frame/app-plugins.mjs` (with the entry isolate the app's services need), brings `src/app.ts`, `src/routes.ts` (or the template's route module) and
+`src/frame.ts` up to date when they are still the released template's, copies the two host plugins (`acryl-web-server`, `acryl-page`), and points
+`npm run dev` at the frame; `npm start` keeps the app's own server and URLs. A file you edited stops the upgrade (nothing is written) unless `--force`
+backs it up first, and `blend.yaml` is never touched. The frame packages' specs come from `ACRYLBLENDS_FRAME_PACKAGES` while they are unpublished.
+An app made before 0.7.8 cannot be carried forward: those releases wrote `src/main.ts` importing `./plugins/...` where the plugins are one folder up, so the
+app could not start as scaffolded; the upgrade says so and asks for the `../plugins/...` paths (0.7.8 fixed them) before it writes the frame.
+
 Code that imports the old names moves by hand: `App` and `AppRequest`, the 0.4 aliases of `Acryl` and `AcrylRequest`, are removed in 1.0, and
 the scaffolding API that was the package root in 0.4 is now `acrylblends/cli`. See
 [Migration to 1.0](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/cordis/migration-to-1-0.md) and

package/dist/index.d.ts

@@ -42,6 +42,50 @@ export declare const HELP: string;
  */
 export declare function runCli(argv: readonly string[], io?: Io): Promise<number>;
 //#endregion
+//#region src/frame-url.d.ts
+/** The record's file name inside the app home. */
+export declare const FRAME_URL_FILE = "frame-url.json";
+/** What the launcher writes: the address, the token it carries, the process that wrote it, and when. */
+interface FrameUrlRecord {
+  readonly version: 1;
+  readonly url: string;
+  readonly token: string;
+  readonly pid: number;
+  readonly writtenAt: string;
+}
+/** The app home the frame uses: `ACRYLBLENDS_HOME` when set, else `<app>/.acrylblends` (the launcher's own rule). */
+export declare function frameHome(appRoot: string, env?: Record<string, string | undefined>): string;
+export declare function frameUrlPath(home: string): string;
+/** The token a frame address carries, if it carries one. */
+export declare function tokenOfFrameUrl(url: string): string | undefined;
+/** Write the frame's address for `home`, owner-only and atomically. Throws when the folder or file cannot be written; the caller decides whether
+ * that is fatal (the launcher prints why and keeps serving the app). */
+export declare function writeFrameUrl(home: string, url: string, pid?: number): void;
+/** Remove the record, but only the one `pid` wrote: a host that is stopping must not erase the address of a newer one that already started. */
+export declare function removeFrameUrl(home: string, pid?: number): void;
+/** The record, or undefined when there is none, it is not ours, or it is malformed. */
+export declare function readFrameUrl(home: string): FrameUrlRecord | undefined;
+/** What `acrylblends open` found. */
+type FrameUrlLookup = {
+  readonly kind: 'running';
+  readonly record: FrameUrlRecord;
+} | {
+  readonly kind: 'stopped';
+  readonly record: FrameUrlRecord;
+} | {
+  readonly kind: 'none';
+  readonly home: string;
+};
+/** Read the record and say whether the frame it names is still listening. */
+export declare function lookUpFrameUrl(appRoot: string, env?: Record<string, string | undefined>): Promise<FrameUrlLookup>;
+/**
+ * `acrylblends open [dir] [--new]`: print the address of the frame running the app in this folder, so a page whose session ended (or the person, after
+ * a restart) can open it again without restarting the host. Only a listening host's address is printed, and only the address goes to stdout, for copy
+ * and paste. `--new` rotates the token in the running host first: the old address stops working at once and the new one is printed; with no host
+ * running, the stored address is simply forgotten and the next start mints a fresh one.
+ */
+export declare function openFrame(args: 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 ["blank", "nodejs", "notes", "chat", "todo", "agent"];
@@ -142,8 +186,22 @@ export declare function assertTargetFree(target: string): void;
  */
 export declare function copyTemplate(source: string, target: string, name: string): string[];
 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. */
+/**
+ * Add run-time dependencies to an app's package.json, keeping what is there and sorting the keys. Returns the names added. A package the app lists as a development
+ * dependency too is taken out of that list: npm lets the development entry win, so `npm install --omit=dev` would leave a run-time dependency out.
+ */
 export declare function mergeDependencies(appDir: string, dependencies: Readonly<Record<string, string>>): string[];
+/**
+ * Add a plugin's development dependencies and scripts to an app's package.json: nothing the app already has is replaced, and a package the app already needs at run time
+ * (`dependencies`) is not listed again as a development one. Returns the names of the development dependencies and scripts added.
+ */
+export declare function mergeTooling(appDir: string, tooling: {
+  devDependencies?: Readonly<Record<string, string>> | undefined;
+  scripts?: Readonly<Record<string, string>> | undefined;
+}): {
+  devDependencies: string[];
+  scripts: string[];
+};
 //#endregion
 //#region src/upgrade.d.ts
 interface UpgradeOptions {
@@ -166,5 +224,5 @@ export declare function parseUpgradeOptions(argv: readonly string[]): UpgradeOpt
  */
 export declare function upgrade(options: UpgradeOptions, io: Io): Promise<number>;
 //#endregion
-export type { AddOptions, InitOptions, Io, LibraryPlugin, Template, UpgradeOptions };
+export type { AddOptions, FrameUrlRecord, InitOptions, Io, LibraryPlugin, Template, UpgradeOptions };
 //# sourceMappingURL=index.d.ts.map