@acrylblends/blends-frame 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +105 -2
- package/cordis.patch.yml +3 -0
- package/lib/app-generation.d.ts +38 -0
- package/lib/app-generation.js +102 -0
- package/lib/app-generation.js.map +1 -0
- package/lib/app-plugins.d.ts +118 -0
- package/lib/app-reload.d.ts +73 -0
- package/lib/app-snapshot.d.ts +40 -0
- package/lib/app-urls.d.ts +17 -0
- package/lib/auto-save.d.ts +63 -0
- package/lib/branch-chats.d.ts +37 -0
- package/lib/client.js +18899 -0
- package/lib/client.js.map +1 -0
- package/lib/contract.d.ts +293 -0
- package/lib/git-sync.d.ts +52 -0
- package/lib/index.d.ts +169 -0
- package/lib/index.js +2923 -0
- package/lib/index.js.map +1 -0
- package/lib/outward-guard.d.ts +45 -0
- package/lib/real-chats.d.ts +42 -0
- package/lib/selection-context.d.ts +118 -0
- package/lib/tool-call-guard.d.ts +104 -0
- package/lib/types/client/BlendsFrame.d.ts +46 -0
- package/lib/types/client/FileView.d.ts +8 -0
- package/lib/types/client/FilesView.d.ts +17 -0
- package/lib/types/client/GitView.d.ts +18 -0
- package/lib/types/client/LeftPanel.d.ts +71 -0
- package/lib/types/client/PluginsSection.d.ts +7 -0
- package/lib/types/client/RemoteSync.d.ts +17 -0
- package/lib/types/client/RightPanel.d.ts +45 -0
- package/lib/types/client/SelectionChip.d.ts +59 -0
- package/lib/types/client/SettingsLauncher.d.ts +9 -0
- package/lib/types/client/ShortcutsRow.d.ts +15 -0
- package/lib/types/client/TerminalView.d.ts +7 -0
- package/lib/types/client/TurnSaveFooter.d.ts +18 -0
- package/lib/types/client/app-reload.d.ts +28 -0
- package/lib/types/client/branch-chats.d.ts +71 -0
- package/lib/types/client/branches.d.ts +23 -0
- package/lib/types/client/canvas/AppCanvas.d.ts +25 -0
- package/lib/types/client/canvas/app-canvas.d.ts +59 -0
- package/lib/types/client/canvas/picker.d.ts +27 -0
- package/lib/types/client/chat-draft.d.ts +15 -0
- package/lib/types/client/chat-saves.d.ts +28 -0
- package/lib/types/client/chats.d.ts +182 -0
- package/lib/types/client/feedback.d.ts +21 -0
- package/lib/types/client/frame-state.d.ts +34 -0
- package/lib/types/client/frame-view.d.ts +35 -0
- package/lib/types/client/fuzzy.d.ts +23 -0
- package/lib/types/client/git-sync.d.ts +39 -0
- package/lib/types/client/highlight.d.ts +15 -0
- package/lib/types/client/index.d.ts +23 -0
- package/lib/types/client/panel-resize.d.ts +29 -0
- package/lib/types/client/plugins-navigator.d.ts +51 -0
- package/lib/types/client/selection.d.ts +56 -0
- package/lib/types/client/sidebar-opens.d.ts +36 -0
- package/lib/types/client/snapshot.d.ts +11 -0
- package/lib/types/client/styles.d.ts +3 -0
- package/lib/types/client/switch-request.d.ts +18 -0
- package/lib/types/client/tab-sizing.d.ts +31 -0
- package/lib/types/client/tabs.d.ts +139 -0
- package/lib/types/client/tools.d.ts +15 -0
- package/lib/types/client/versions.d.ts +34 -0
- package/lib/types/client/view-state.d.ts +42 -0
- package/lib/types/contract.d.ts +293 -0
- package/package.json +122 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 WebBoxes s.r.o.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,106 @@
|
|
|
1
|
-
#
|
|
1
|
+
# acryl-blends-frame
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The workbench around an app made with ACRYL Blends, as the owner's mockup draws it (`docs/design/blends-frame-mockup.html`):
|
|
4
|
+
|
|
5
|
+
- a top bar: the left-panel toggle, the app's name and newest version, Build/Preview, Settings, the right-panel toggle;
|
|
6
|
+
- on the left: the app's branches, each with what is open on it, then the versions (save points) of the checked-out branch;
|
|
7
|
+
- in the centre: the app alone, in one frame that only a person or the door navigates or reloads; its Select control picks an element of the
|
|
8
|
+
app, and the next message the chat sends then carries that element's page and selector, shown at the left of the composer's input row as
|
|
9
|
+
`Selected: ...` until its x clears it;
|
|
10
|
+
- on the right: the agents as tabs, with the chat's History.
|
|
11
|
+
|
|
12
|
+
On a new app the frame is the first screen: both panels open, a blank chat with its composer at the bottom, and the model connected in
|
|
13
|
+
Settings > Models. DSH's preview notice and credential prompt stay out of the frame instead of covering the app.
|
|
14
|
+
|
|
15
|
+
The canvas page reads the frame's view (`src/client/frame-view.ts`): Build keeps the app's own build-time controls out of the canvas (the
|
|
16
|
+
agent-panel's button and the feedback button), and Preview shows what production shows without a reload. The page's plugins read the handle
|
|
17
|
+
through `window.parent`; a page opened directly is unchanged.
|
|
18
|
+
|
|
19
|
+
A feedback note shows its screenshot as a thumbnail, and handing it to the chat puts the page and selector text in the composer with the picture as a real attachment. Settings > Plugins shares a local plugin: the frame packages it under the app's home (`plugin-packages/<name>`; the builder's package shape,
|
|
20
|
+
plus the Loader patch the plugin-hub needs) and first says what it will do, for example "Create repository ana/notes on GitHub and publish
|
|
21
|
+
v0.1.0? It will be private.", with Cancel as the default. Only on the person's yes does it publish, with `@webboxes/plugin-hub` through the user's
|
|
22
|
+
own `gh` and `git`, exactly that repository, version and visibility; when the plan changed meanwhile nothing is sent. The Host refuses a share
|
|
23
|
+
that does not carry the confirmed plan. The row then shows the repository and version. A second app installs it with `acrylblends add <the
|
|
24
|
+
package folder>`; the plugin-hub refuses a package with secrets before anything is sent. `shareOwner` in the frame row's config names the GitHub
|
|
25
|
+
account or organization (the signed-in account when absent); a rehearsal sets a test organization there (`shareOwner: inboxxobni`). A version
|
|
26
|
+
already released there is planned as the next patch, and the question says so.
|
|
27
|
+
|
|
28
|
+
It owns the page's `root` slot, so it is mounted instead of the IDE's workbench (`acryl-workspace`), never beside it. The Host half serves one
|
|
29
|
+
private route, `GET /api/acryl-blends-frame/state` (the app's name, folder, page and branches); `appPage` in the row's config says where the
|
|
30
|
+
app's page is served.
|
|
31
|
+
|
|
32
|
+
## The chat saves by itself
|
|
33
|
+
|
|
34
|
+
When the chat's agent finishes a turn that changed files in the app's folder, the Host makes a save point (a version) without being asked. It is named
|
|
35
|
+
after the person's request (its first sentence, cut at a word after 50 characters), it holds the whole folder as `Save point` does, and the chat says
|
|
36
|
+
so in one line under that answer: `edited src/routes.ts, src/board.ts · saved as v7`. The new version is the top of Versions, "(current)", and the top
|
|
37
|
+
bar reads `v7 · saved`. A turn that changed no file makes no version and says nothing. A turn the person stops saves the files it had changed
|
|
38
|
+
by then, under the same line: DSH tells the Host about a stopping turn's changes before the turn ends, and the Host saves on that.
|
|
39
|
+
|
|
40
|
+
Which files a turn changed comes from DSH's `workspace-changes` row, which compares the working tree before and after each turn, so edits the person
|
|
41
|
+
made earlier and has not saved are not credited to the agent (they are still in the version, as in any save point). The Host keeps which turn made
|
|
42
|
+
which version in `chat-saves.json` in the app's data home (`GET /api/acryl-blends-frame/chat-saves?session=`), so the line is still there after a restart.
|
|
43
|
+
|
|
44
|
+
The chat the frame mounts needs more of DSH than the frame draws: the agent preset `acryl-blends` (shell, file tools and jobs; the registry's default),
|
|
45
|
+
the host rows it stands on, and the chat view's client rows. They are in `packages/cli/src/ide-profile.ts`. DSH's right sidebar (`ui-sidebar-right`) is
|
|
46
|
+
drawn inside the right panel as its Panel tab: when DSH opens a page there (a plan, the review of a turn's changed files) the tab opens, and closing the
|
|
47
|
+
tab collapses the sidebar.
|
|
48
|
+
|
|
49
|
+
## Nothing leaves the machine without a yes
|
|
50
|
+
|
|
51
|
+
Share (Settings > Plugins) and Push (the `↑N` chip on the versions header, and the Git tab's Push) send the person's work under their name, so each
|
|
52
|
+
first says what it will send and where, read without sending anything: "Create repository ana/notes on GitHub and publish v0.1.0? It will be
|
|
53
|
+
private.", "Push 2 versions to origin/main (github.com/ana/notes)?". Cancel is focused, so Enter or a stray click sends nothing. The Host's routes
|
|
54
|
+
take only the plan the person confirmed (`/plugins/share` and `/git/push` answer 400 without one), read it again just before sending, and send
|
|
55
|
+
nothing when it changed meanwhile (another account, a new version, the remote moved). The remote's address is shown without any credential.
|
|
56
|
+
|
|
57
|
+
The agent is held to the same rule (`src/outward-guard.ts`): a shell call that pushes or publishes (`git push`, `gh repo create`, `gh release create`,
|
|
58
|
+
a `gh api` write, `npm publish`, ...) and the app's `save_app` tool become DSH's approval prompt, naming the command, whatever the access mode; they
|
|
59
|
+
run only when the person allows them once. It reads the command's words, so it is a seat belt for an honest agent, not a sandbox.
|
|
60
|
+
|
|
61
|
+
## Chats belong to a branch
|
|
62
|
+
|
|
63
|
+
A chat belongs to the branch it was made on. The Host records that once per chat in `branch-chats.json` in the app's data home (`/api/acryl-blends-frame/branches/chats`): a chat made by the frame is recorded as it is made, a chat DSH made (or one from before this file) is recorded
|
|
64
|
+
the first time the frame sees it with a turn, on the branch checked out then, and a record is never moved by a later switch. That file is the only source
|
|
65
|
+
of truth; the client reads it and keeps no list of its own.
|
|
66
|
+
|
|
67
|
+
The chat on screen always belongs to the checked-out branch (`src/client/chats.ts`, `decideChat`): switching to a branch shows its most recently used chat
|
|
68
|
+
(or the one whose tab is showing), and a branch with no chat gets a new one, made on the Host and recorded for it before anything is shown. Expanding a
|
|
69
|
+
branch in the left panel lists its own chats; History in the right panel opens the checked-out branch's. `+` then **Chat** starts a new chat of its own on
|
|
70
|
+
the current branch as a tab (the one on screen is reused while it has no turn); the base tab and each `chat:<id>` tab follow the chat on screen.
|
|
71
|
+
|
|
72
|
+
### Open and closed chats
|
|
73
|
+
|
|
74
|
+
A chat is **open** while it has a tab or is the chat on screen; every other chat is **closed**. The left panel lists only open chats (a branch's "N open"
|
|
75
|
+
counts only those), and History lists all of them: `open · now`, or `closed · 1 h · opens as a tab`. Picking a closed chat of the checked-out branch opens
|
|
76
|
+
it as a tab and it joins the left panel; picking one of another branch hands the request to the left panel, which offers the switch first through the
|
|
77
|
+
same guard as its own rows. Closing a chat's tab (the x) closes the chat; when it was on screen the view moves to the chat of the tab now shown, else to the
|
|
78
|
+
base tab's chat. The base tab (never closed) shows the branch's newest open chat that has no tab of its own, or a new chat when there is none.
|
|
79
|
+
|
|
80
|
+
Which chats are open is remembered per app in the same Host file: `open` maps the app's root to the open chat ids (`POST {id, open}` opens or closes one,
|
|
81
|
+
`POST {opened: [ids]}` records the first decision; the Host keeps the first). While the file has no `open` entry for the app, nobody decided: the frame
|
|
82
|
+
decides once - the latest chat with a turn of each branch, the chat on screen and the chats that already have a tab (`initialOpenChats`) - so an app that
|
|
83
|
+
already has many chats opens with only one per branch and the rest in History. A tab left in a remembered strip whose chat is not open is dropped.
|
|
84
|
+
|
|
85
|
+
DSH moves its main view in steps and finishes a move it started even when something else moved the view meanwhile, so the frame asks for a chat only
|
|
86
|
+
after the call that told it has ended, asks once while that move is on its way, and never from inside DSH's start-up.
|
|
87
|
+
|
|
88
|
+
## The canvas shows what the files say
|
|
89
|
+
|
|
90
|
+
The app's code runs in the dev host (`npm run dev`), and the host loads it once. So that a version the person goes back to, a file the chat wrote, a
|
|
91
|
+
line typed in an editor or a `git switch` shows in the canvas without a restart (a restart would end the terminals and agents in the right panel),
|
|
92
|
+
the Host loads the app's code again whenever `blend.yaml` or a file under `src/` or `plugins/` changes, whoever changed it (300 ms after the last
|
|
93
|
+
change).
|
|
94
|
+
|
|
95
|
+
How it works: the launcher (`scripts/ide-host.mjs`) loads `acryl-blends-frame/app-generation` before anything of the app does. It installs a resolve
|
|
96
|
+
hook that, once the Host raises the generation, gives every file of the app's `src/`, of its own plugins (the
|
|
97
|
+
folders of `plugins/` that `plugins/library.json` does not list) and of the generated `frame/` rows a `?gen=N` query, so a new import of them - and
|
|
98
|
+
of everything they import - is a fresh copy. Nothing in `node_modules` or the library copies in `plugins/` gets one, so their services stay single
|
|
99
|
+
instances. The Host (`src/app-reload.ts`) then imports the app's rows (`app-plugins`, `app-routes`) under the new generation, and only if that
|
|
100
|
+
succeeds stops them and starts them from the new code. The page follows a long poll on `GET /api/acryl-blends-frame/app?after=<seq>` and reloads the
|
|
101
|
+
canvas when a new generation is up.
|
|
102
|
+
|
|
103
|
+
A file that does not load (a syntax error, a missing import) or a row that does not start leaves the last good code running and shows one line in
|
|
104
|
+
the top bar (`Not reloaded: src/routes.ts:47 ...`) until the next change loads. In-memory state of the app's modules starts again with each load.
|
|
105
|
+
Development only: Node cannot unload a module, so the old copies stay in memory until the host stops; `npm start` has no launcher and never loads the
|
|
106
|
+
hook. A host started by a launcher that predates the hook runs the code as it started.
|
package/cordis.patch.yml
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The app's code, loaded again in the running dev host. Node keeps every module it has imported under its URL, so the app's routes row, imported once at
|
|
3
|
+
* boot, keeps serving the code it was started with: a version the person went back to, a file the chat wrote, a line typed in an editor would all stay
|
|
4
|
+
* invisible until the host restarts (which would also end every terminal and agent running in the right panel).
|
|
5
|
+
*
|
|
6
|
+
* The launcher (`scripts/ide-host.mjs`) installs a resolve hook here, before anything of the app loads. While the generation is 0 it does nothing. When
|
|
7
|
+
* the Host raises the generation, every file of the app's `src/`, of its own plugins (the folders of `plugins/` that are not library copies: the
|
|
8
|
+
* features `blend.yaml` mounts by name) and of the generated `frame/` rows that import them resolves with `?gen=N` appended, so an import made now gets
|
|
9
|
+
* a fresh copy of the file and, because each of its own imports resolves through the same hook, of everything it imports. Nothing else gets a query:
|
|
10
|
+
* `node_modules`, the library copies in `plugins/` (`plugins/library.json` lists them) and the frame itself stay single instances, so the services the
|
|
11
|
+
* app uses are not duplicated.
|
|
12
|
+
*
|
|
13
|
+
* Development only: the old copies of a module stay in memory (Node cannot unload a module), which a dev host that restarts at the end of the day can
|
|
14
|
+
* carry. Production never loads this file: `npm start` has no frame and no launcher.
|
|
15
|
+
*
|
|
16
|
+
* The state sits on `globalThis` under a registered symbol, not in this module: the launcher and the Host plugin load this code as two separate files.
|
|
17
|
+
*/
|
|
18
|
+
/** The generation the app's files resolve under: 0 is the files as they are (no query), each later number is a fresh copy of them all. */
|
|
19
|
+
export interface AppGeneration {
|
|
20
|
+
current(): number;
|
|
21
|
+
set(generation: number): void;
|
|
22
|
+
}
|
|
23
|
+
/** The app's `plugins/` folder, as a folder URL ending in `/`, and the library copies in it, which stay single instances. */
|
|
24
|
+
export interface PluginScope {
|
|
25
|
+
readonly scope: string;
|
|
26
|
+
readonly library: ReadonlySet<string>;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* `url` with the generation as its query when it is a file of the app's folders (`scopes`, as folder URLs ending in `/`) or of one of the app's own
|
|
30
|
+
* plugin folders (`plugins`), and has none yet.
|
|
31
|
+
*/
|
|
32
|
+
export declare function generationUrl(url: string, scopes: readonly string[], generation: number, plugins?: PluginScope): string;
|
|
33
|
+
/** The generation switch the launcher installed in this process; undefined when it did not (the app's code is then never loaded again). */
|
|
34
|
+
export declare function appGeneration(): AppGeneration | undefined;
|
|
35
|
+
/** Install the hook for the app at `appRoot` once per process; a second call returns the first one's switch. */
|
|
36
|
+
export declare function installAppGeneration({ appRoot }: {
|
|
37
|
+
readonly appRoot: string;
|
|
38
|
+
}): AppGeneration;
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
import { registerHooks } from "node:module";
|
|
2
|
+
import { readFileSync, realpathSync } from "node:fs";
|
|
3
|
+
import { join, sep } from "node:path";
|
|
4
|
+
import { pathToFileURL } from "node:url";
|
|
5
|
+
//#region src/app-generation.ts
|
|
6
|
+
/**
|
|
7
|
+
* The app's code, loaded again in the running dev host. Node keeps every module it has imported under its URL, so the app's routes row, imported once at
|
|
8
|
+
* boot, keeps serving the code it was started with: a version the person went back to, a file the chat wrote, a line typed in an editor would all stay
|
|
9
|
+
* invisible until the host restarts (which would also end every terminal and agent running in the right panel).
|
|
10
|
+
*
|
|
11
|
+
* The launcher (`scripts/ide-host.mjs`) installs a resolve hook here, before anything of the app loads. While the generation is 0 it does nothing. When
|
|
12
|
+
* the Host raises the generation, every file of the app's `src/`, of its own plugins (the folders of `plugins/` that are not library copies: the
|
|
13
|
+
* features `blend.yaml` mounts by name) and of the generated `frame/` rows that import them resolves with `?gen=N` appended, so an import made now gets
|
|
14
|
+
* a fresh copy of the file and, because each of its own imports resolves through the same hook, of everything it imports. Nothing else gets a query:
|
|
15
|
+
* `node_modules`, the library copies in `plugins/` (`plugins/library.json` lists them) and the frame itself stay single instances, so the services the
|
|
16
|
+
* app uses are not duplicated.
|
|
17
|
+
*
|
|
18
|
+
* Development only: the old copies of a module stay in memory (Node cannot unload a module), which a dev host that restarts at the end of the day can
|
|
19
|
+
* carry. Production never loads this file: `npm start` has no frame and no launcher.
|
|
20
|
+
*
|
|
21
|
+
* The state sits on `globalThis` under a registered symbol, not in this module: the launcher and the Host plugin load this code as two separate files.
|
|
22
|
+
*/
|
|
23
|
+
const KEY = Symbol.for("acrylblends.app-generation");
|
|
24
|
+
/** The folders of an app whose files take a generation: its own code, and the generated rows that import it. */
|
|
25
|
+
const APP_FOLDERS = ["src", "frame"];
|
|
26
|
+
/**
|
|
27
|
+
* `url` with the generation as its query when it is a file of the app's folders (`scopes`, as folder URLs ending in `/`) or of one of the app's own
|
|
28
|
+
* plugin folders (`plugins`), and has none yet.
|
|
29
|
+
*/
|
|
30
|
+
function generationUrl(url, scopes, generation, plugins) {
|
|
31
|
+
if (generation === 0 || url.includes("?")) return url;
|
|
32
|
+
if (!scopes.some((scope) => url.startsWith(scope)) && !isOwnPluginFile(url, plugins)) return url;
|
|
33
|
+
return `${url}?gen=${String(generation)}`;
|
|
34
|
+
}
|
|
35
|
+
/** Whether `url` is a file inside one of the app's own plugin folders (`plugins/<name>/...` with `<name>` not a library copy). */
|
|
36
|
+
function isOwnPluginFile(url, plugins) {
|
|
37
|
+
if (plugins === void 0 || !url.startsWith(plugins.scope)) return false;
|
|
38
|
+
const rest = url.slice(plugins.scope.length);
|
|
39
|
+
const slash = rest.indexOf("/");
|
|
40
|
+
if (slash <= 0) return false;
|
|
41
|
+
return !plugins.library.has(decodeURIComponent(rest.slice(0, slash)));
|
|
42
|
+
}
|
|
43
|
+
/** The library copies `plugins/library.json` lists; none when it is absent or unreadable. */
|
|
44
|
+
function libraryCopies(pluginsDir) {
|
|
45
|
+
try {
|
|
46
|
+
const listed = JSON.parse(readFileSync(join(pluginsDir, "library.json"), "utf8")).plugins;
|
|
47
|
+
return new Set(Array.isArray(listed) ? listed.filter((name) => typeof name === "string") : []);
|
|
48
|
+
} catch {
|
|
49
|
+
return /* @__PURE__ */ new Set();
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
function isAppGeneration(value) {
|
|
53
|
+
return value !== null && typeof value === "object" && typeof value.current === "function" && typeof value.set === "function";
|
|
54
|
+
}
|
|
55
|
+
/** The generation switch the launcher installed in this process; undefined when it did not (the app's code is then never loaded again). */
|
|
56
|
+
function appGeneration() {
|
|
57
|
+
const value = globalThis[KEY];
|
|
58
|
+
return isAppGeneration(value) ? value : void 0;
|
|
59
|
+
}
|
|
60
|
+
/** Install the hook for the app at `appRoot` once per process; a second call returns the first one's switch. */
|
|
61
|
+
function installAppGeneration({ appRoot }) {
|
|
62
|
+
const installed = appGeneration();
|
|
63
|
+
if (installed !== void 0) return installed;
|
|
64
|
+
let generation = 0;
|
|
65
|
+
const real = (path) => {
|
|
66
|
+
try {
|
|
67
|
+
return realpathSync(path);
|
|
68
|
+
} catch {
|
|
69
|
+
return path;
|
|
70
|
+
}
|
|
71
|
+
};
|
|
72
|
+
const scopes = APP_FOLDERS.map((folder) => pathToFileURL(real(join(appRoot, folder)) + sep).href);
|
|
73
|
+
const pluginsDir = real(join(appRoot, "plugins"));
|
|
74
|
+
let plugins = {
|
|
75
|
+
scope: pathToFileURL(pluginsDir + sep).href,
|
|
76
|
+
library: libraryCopies(pluginsDir)
|
|
77
|
+
};
|
|
78
|
+
registerHooks({ resolve(specifier, context, nextResolve) {
|
|
79
|
+
const resolved = nextResolve(specifier, context);
|
|
80
|
+
const url = generationUrl(resolved.url, scopes, generation, plugins);
|
|
81
|
+
return url === resolved.url ? resolved : {
|
|
82
|
+
...resolved,
|
|
83
|
+
url
|
|
84
|
+
};
|
|
85
|
+
} });
|
|
86
|
+
const created = {
|
|
87
|
+
current: () => generation,
|
|
88
|
+
set: (next) => {
|
|
89
|
+
plugins = {
|
|
90
|
+
...plugins,
|
|
91
|
+
library: libraryCopies(pluginsDir)
|
|
92
|
+
};
|
|
93
|
+
generation = next;
|
|
94
|
+
}
|
|
95
|
+
};
|
|
96
|
+
globalThis[KEY] = created;
|
|
97
|
+
return created;
|
|
98
|
+
}
|
|
99
|
+
//#endregion
|
|
100
|
+
export { appGeneration, generationUrl, installAppGeneration };
|
|
101
|
+
|
|
102
|
+
//# sourceMappingURL=app-generation.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"app-generation.js","names":[],"sources":["../src/app-generation.ts"],"sourcesContent":["/**\n * The app's code, loaded again in the running dev host. Node keeps every module it has imported under its URL, so the app's routes row, imported once at\n * boot, keeps serving the code it was started with: a version the person went back to, a file the chat wrote, a line typed in an editor would all stay\n * invisible until the host restarts (which would also end every terminal and agent running in the right panel).\n *\n * The launcher (`scripts/ide-host.mjs`) installs a resolve hook here, before anything of the app loads. While the generation is 0 it does nothing. When\n * the Host raises the generation, every file of the app's `src/`, of its own plugins (the folders of `plugins/` that are not library copies: the\n * features `blend.yaml` mounts by name) and of the generated `frame/` rows that import them resolves with `?gen=N` appended, so an import made now gets\n * a fresh copy of the file and, because each of its own imports resolves through the same hook, of everything it imports. Nothing else gets a query:\n * `node_modules`, the library copies in `plugins/` (`plugins/library.json` lists them) and the frame itself stay single instances, so the services the\n * app uses are not duplicated.\n *\n * Development only: the old copies of a module stay in memory (Node cannot unload a module), which a dev host that restarts at the end of the day can\n * carry. Production never loads this file: `npm start` has no frame and no launcher.\n *\n * The state sits on `globalThis` under a registered symbol, not in this module: the launcher and the Host plugin load this code as two separate files.\n */\n\nimport { readFileSync, realpathSync } from 'node:fs'\nimport { registerHooks } from 'node:module'\nimport { join, sep } from 'node:path'\nimport { pathToFileURL } from 'node:url'\n\nconst KEY = Symbol.for('acrylblends.app-generation')\n\n/** The generation the app's files resolve under: 0 is the files as they are (no query), each later number is a fresh copy of them all. */\nexport interface AppGeneration {\n current(): number\n set(generation: number): void\n}\n\n/** The folders of an app whose files take a generation: its own code, and the generated rows that import it. */\nconst APP_FOLDERS = ['src', 'frame']\n\n/** The app's `plugins/` folder, as a folder URL ending in `/`, and the library copies in it, which stay single instances. */\nexport interface PluginScope {\n readonly scope: string\n readonly library: ReadonlySet<string>\n}\n\n/**\n * `url` with the generation as its query when it is a file of the app's folders (`scopes`, as folder URLs ending in `/`) or of one of the app's own\n * plugin folders (`plugins`), and has none yet.\n */\nexport function generationUrl(url: string, scopes: readonly string[], generation: number, plugins?: PluginScope): string {\n if (generation === 0 || url.includes('?')) return url\n if (!scopes.some(scope => url.startsWith(scope)) && !isOwnPluginFile(url, plugins)) return url\n return `${url}?gen=${String(generation)}`\n}\n\n/** Whether `url` is a file inside one of the app's own plugin folders (`plugins/<name>/...` with `<name>` not a library copy). */\nfunction isOwnPluginFile(url: string, plugins: PluginScope | undefined): boolean {\n if (plugins === undefined || !url.startsWith(plugins.scope)) return false\n const rest = url.slice(plugins.scope.length)\n const slash = rest.indexOf('/')\n if (slash <= 0) return false\n return !plugins.library.has(decodeURIComponent(rest.slice(0, slash)))\n}\n\n/** The library copies `plugins/library.json` lists; none when it is absent or unreadable. */\nfunction libraryCopies(pluginsDir: string): ReadonlySet<string> {\n try {\n const listed = (JSON.parse(readFileSync(join(pluginsDir, 'library.json'), 'utf8')) as { plugins?: unknown }).plugins\n return new Set(Array.isArray(listed) ? listed.filter((name): name is string => typeof name === 'string') : [])\n } catch {\n return new Set()\n }\n}\n\nfunction isAppGeneration(value: unknown): value is AppGeneration {\n return value !== null && typeof value === 'object'\n && typeof (value as { current?: unknown }).current === 'function' && typeof (value as { set?: unknown }).set === 'function'\n}\n\n/** The generation switch the launcher installed in this process; undefined when it did not (the app's code is then never loaded again). */\nexport function appGeneration(): AppGeneration | undefined {\n const value = (globalThis as Record<symbol, unknown>)[KEY]\n return isAppGeneration(value) ? value : undefined\n}\n\n/** Install the hook for the app at `appRoot` once per process; a second call returns the first one's switch. */\nexport function installAppGeneration({ appRoot }: { readonly appRoot: string }): AppGeneration {\n const installed = appGeneration()\n if (installed !== undefined) return installed\n let generation = 0\n // Node resolves a module to its real path, so the folders are matched by theirs: an app under a symlinked directory still gets its generations.\n const real = (path: string): string => {\n try {\n return realpathSync(path)\n } catch {\n return path\n }\n }\n const scopes = APP_FOLDERS.map(folder => pathToFileURL(real(join(appRoot, folder)) + sep).href)\n const pluginsDir = real(join(appRoot, 'plugins'))\n // Read again at each raise: `acrylblends add` may have copied a library plugin since.\n let plugins: PluginScope = { scope: pathToFileURL(pluginsDir + sep).href, library: libraryCopies(pluginsDir) }\n registerHooks({\n resolve(specifier, context, nextResolve) {\n const resolved = nextResolve(specifier, context)\n const url = generationUrl(resolved.url, scopes, generation, plugins)\n return url === resolved.url ? resolved : { ...resolved, url }\n },\n })\n const created: AppGeneration = {\n current: () => generation,\n set: (next) => {\n plugins = { ...plugins, library: libraryCopies(pluginsDir) }\n generation = next\n },\n };\n (globalThis as Record<symbol, unknown>)[KEY] = created\n return created\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAuBA,MAAM,MAAM,OAAO,IAAI,4BAA4B;;AASnD,MAAM,cAAc,CAAC,OAAO,OAAO;;;;;AAYnC,SAAgB,cAAc,KAAa,QAA2B,YAAoB,SAA+B;CACvH,IAAI,eAAe,KAAK,IAAI,SAAS,GAAG,GAAG,OAAO;CAClD,IAAI,CAAC,OAAO,MAAK,UAAS,IAAI,WAAW,KAAK,CAAC,KAAK,CAAC,gBAAgB,KAAK,OAAO,GAAG,OAAO;CAC3F,OAAO,GAAG,IAAI,OAAO,OAAO,UAAU;AACxC;;AAGA,SAAS,gBAAgB,KAAa,SAA2C;CAC/E,IAAI,YAAY,KAAA,KAAa,CAAC,IAAI,WAAW,QAAQ,KAAK,GAAG,OAAO;CACpE,MAAM,OAAO,IAAI,MAAM,QAAQ,MAAM,MAAM;CAC3C,MAAM,QAAQ,KAAK,QAAQ,GAAG;CAC9B,IAAI,SAAS,GAAG,OAAO;CACvB,OAAO,CAAC,QAAQ,QAAQ,IAAI,mBAAmB,KAAK,MAAM,GAAG,KAAK,CAAC,CAAC;AACtE;;AAGA,SAAS,cAAc,YAAyC;CAC9D,IAAI;EACF,MAAM,SAAU,KAAK,MAAM,aAAa,KAAK,YAAY,cAAc,GAAG,MAAM,CAAC,CAAC,CAA2B;EAC7G,OAAO,IAAI,IAAI,MAAM,QAAQ,MAAM,IAAI,OAAO,QAAQ,SAAyB,OAAO,SAAS,QAAQ,IAAI,CAAC,CAAC;CAC/G,QAAQ;EACN,uBAAO,IAAI,IAAI;CACjB;AACF;AAEA,SAAS,gBAAgB,OAAwC;CAC/D,OAAO,UAAU,QAAQ,OAAO,UAAU,YACrC,OAAQ,MAAgC,YAAY,cAAc,OAAQ,MAA4B,QAAQ;AACrH;;AAGA,SAAgB,gBAA2C;CACzD,MAAM,QAAS,WAAuC;CACtD,OAAO,gBAAgB,KAAK,IAAI,QAAQ,KAAA;AAC1C;;AAGA,SAAgB,qBAAqB,EAAE,WAAwD;CAC7F,MAAM,YAAY,cAAc;CAChC,IAAI,cAAc,KAAA,GAAW,OAAO;CACpC,IAAI,aAAa;CAEjB,MAAM,QAAQ,SAAyB;EACrC,IAAI;GACF,OAAO,aAAa,IAAI;EAC1B,QAAQ;GACN,OAAO;EACT;CACF;CACA,MAAM,SAAS,YAAY,KAAI,WAAU,cAAc,KAAK,KAAK,SAAS,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI;CAC9F,MAAM,aAAa,KAAK,KAAK,SAAS,SAAS,CAAC;CAEhD,IAAI,UAAuB;EAAE,OAAO,cAAc,aAAa,GAAG,CAAC,CAAC;EAAM,SAAS,cAAc,UAAU;CAAE;CAC7G,cAAc,EACZ,QAAQ,WAAW,SAAS,aAAa;EACvC,MAAM,WAAW,YAAY,WAAW,OAAO;EAC/C,MAAM,MAAM,cAAc,SAAS,KAAK,QAAQ,YAAY,OAAO;EACnE,OAAO,QAAQ,SAAS,MAAM,WAAW;GAAE,GAAG;GAAU;EAAI;CAC9D,EACF,CAAC;CACD,MAAM,UAAyB;EAC7B,eAAe;EACf,MAAM,SAAS;GACb,UAAU;IAAE,GAAG;IAAS,SAAS,cAAc,UAAU;GAAE;GAC3D,aAAa;EACf;CACF;CACA,WAAwC,OAAO;CAC/C,OAAO;AACT"}
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The app's plugins for Settings → Plugins, read and switched in the app's own files: `blend.yaml` (a row is off with `disabled: true`; a plugin
|
|
3
|
+
* from `plugins/` is off when the `extensions` row's `off` list names it) and the `plugins/` folder (what was written after the app was made, as the
|
|
4
|
+
* `extensions` row finds it). `blend.yaml` is edited by lines, so its comments and layout stay as the person wrote them. The running app takes a
|
|
5
|
+
* switch when its Loader row (`app-plugins`) loads again, which the client asks for.
|
|
6
|
+
*/
|
|
7
|
+
import { type PublishGitPort, type RepositoryHostPort } from '@webboxes/plugin-hub';
|
|
8
|
+
import { type AppPluginView, type FramePluginState, type FramePluginView, type SharedPluginView, type SharePlan } from './contract.ts';
|
|
9
|
+
/** One row of `blend.yaml`'s `spec.rows`: where its block starts and ends (line indexes, end exclusive). */
|
|
10
|
+
export interface BlendRow {
|
|
11
|
+
readonly id: string;
|
|
12
|
+
readonly name: string;
|
|
13
|
+
readonly disabled: boolean;
|
|
14
|
+
/** The comment lines right above the row, joined: what the row is for. */
|
|
15
|
+
readonly comment: string;
|
|
16
|
+
readonly start: number;
|
|
17
|
+
readonly end: number;
|
|
18
|
+
}
|
|
19
|
+
export declare function parseBlendRows(text: string): BlendRow[];
|
|
20
|
+
/** `blend.yaml` with one row switched: `disabled: true` added under its id, or removed. */
|
|
21
|
+
export declare function setRowOn(text: string, id: string, on: boolean): string;
|
|
22
|
+
/** The plugins from `plugins/` the `extensions` row's `off` list names. */
|
|
23
|
+
export declare function extensionsOff(text: string): string[];
|
|
24
|
+
/** `blend.yaml` with a plugin from `plugins/` switched: its name taken out of, or put in, the `extensions` row's `off` list. */
|
|
25
|
+
export declare function setMadeOn(text: string, name: string, on: boolean): string;
|
|
26
|
+
/** The folders in `plugins/` the `extensions` row starts: not a library copy (`library.json`), and with an entry file. */
|
|
27
|
+
export declare function madePlugins(root: string): Promise<string[]>;
|
|
28
|
+
/** The first sentence of a file's leading doc comment, without its code marks. */
|
|
29
|
+
export declare function docSummary(source: string): string;
|
|
30
|
+
/** The first sentence of a text, without code marks, cut to a line's length. */
|
|
31
|
+
export declare function firstSentence(text: string): string;
|
|
32
|
+
/** Who a commit says made it: an agent named in a `Co-Authored-By` trailer, else the commit's author. */
|
|
33
|
+
export declare function commitMaker(author: string, body: string): string;
|
|
34
|
+
export interface GitPort {
|
|
35
|
+
run(args: readonly string[], cwd: string): Promise<{
|
|
36
|
+
readonly stdout: string;
|
|
37
|
+
}>;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Every plugin of the app: first the app's own plugins (the folders of `plugins/` that are not library copies), each mounted by its `blend.yaml` row
|
|
41
|
+
* or, without one, started by the `extensions` row; then the library rows of `blend.yaml` in their order.
|
|
42
|
+
*/
|
|
43
|
+
/**
|
|
44
|
+
* Whether a shared plugin's repository is still there: false when GitHub answers that it does not exist (deleted or renamed), undefined when it could
|
|
45
|
+
* not be asked (offline, gh signed out), so a row is marked gone only on GitHub's own word.
|
|
46
|
+
*/
|
|
47
|
+
export type RepositoryCheck = (url: string) => Promise<boolean | undefined>;
|
|
48
|
+
/** The check through the user's own `gh`, without blocking the Host. */
|
|
49
|
+
export declare const ghRepositoryCheck: RepositoryCheck;
|
|
50
|
+
/** The share records, each checked once: a repository GitHub says is gone is marked so, and the row offers a new share. */
|
|
51
|
+
export declare function checkedShares(records: Readonly<Record<string, SharedPluginView>>, check: RepositoryCheck): Promise<Record<string, SharedPluginView>>;
|
|
52
|
+
export declare function readAppPlugins(root: string, git: GitPort, sharedFile?: string, check?: RepositoryCheck): Promise<AppPluginView[]>;
|
|
53
|
+
/**
|
|
54
|
+
* Switch one plugin in `blend.yaml`: a row (a library row, or one of the app's own plugins that has a row) gets or loses `disabled: true`; an own
|
|
55
|
+
* plugin without a row is put in or taken out of the `extensions` row's `off` list. @throws when there is no such plugin.
|
|
56
|
+
*/
|
|
57
|
+
export declare function switchAppPlugin(root: string, kind: 'row' | 'made', name: string, on: boolean): Promise<void>;
|
|
58
|
+
/** The frame's own Loader rows the list shows: ACRYL's plugins around the app, not DSH's engine rows nor the rows that run the app. */
|
|
59
|
+
export declare function isFramePlugin(moduleName: string, entryId: string): boolean;
|
|
60
|
+
/** A Loader row as the frame reads it: its id, module, whether it is switched off, and its fiber's state (Cordis `FiberState`). */
|
|
61
|
+
export interface FrameRow {
|
|
62
|
+
readonly id: string;
|
|
63
|
+
readonly name: string;
|
|
64
|
+
readonly disabled: boolean;
|
|
65
|
+
readonly fiberState: number | undefined;
|
|
66
|
+
}
|
|
67
|
+
/** Cordis `FiberState`: PENDING 0, LOADING 1, ACTIVE 2, FAILED 3. */
|
|
68
|
+
export declare function frameRowState(row: FrameRow): FramePluginState;
|
|
69
|
+
/** The frame's own plugins, in Loader order, each with its release and what it does. */
|
|
70
|
+
export declare function readFramePlugins(root: string, rows: readonly FrameRow[]): Promise<FramePluginView[]>;
|
|
71
|
+
/** The package.json a local plugin is shared with: the fields the builder's package_plugin writes (plugins/builder/index.ts), plus the Loader
|
|
72
|
+
* patch the plugin-hub's share requires so the package can also be installed as a row. */
|
|
73
|
+
export declare function pluginPackageManifest(name: string, description: string, version?: string): Record<string, unknown>;
|
|
74
|
+
/**
|
|
75
|
+
* The shares this app completed, from its own home (`shared-plugins.json`). The record is written only after the hub's whole share succeeded: a
|
|
76
|
+
* package.json can name a repository before the release exists, because the hub prepares it before its guards, and a refused share must not look
|
|
77
|
+
* shared.
|
|
78
|
+
*/
|
|
79
|
+
export declare function readSharedRecords(file: string | undefined): Promise<Readonly<Record<string, SharedPluginView>>>;
|
|
80
|
+
/** Remember one completed share in the app's own record. */
|
|
81
|
+
export declare function recordShare(file: string, name: string, shared: SharedPluginView): Promise<void>;
|
|
82
|
+
/** Where the frame packages the plugins it shares: under the app's home, never in the app's folder, so a share leaves no file to save. */
|
|
83
|
+
export declare const pluginPackagesOf: (home: string) => string;
|
|
84
|
+
/** Copy one local plugin into its package folder under `packages`, the way the builder's package_plugin does; answers the folder. */
|
|
85
|
+
export declare function packageAppPlugin(root: string, name: string, packages: string): Promise<string>;
|
|
86
|
+
/** Bump one package folder's patch version (what the hub asks for after a release), and answer the new version. */
|
|
87
|
+
export declare function bumpPackageVersion(dir: string): Promise<string>;
|
|
88
|
+
/** Where a share goes through: the user's own `gh` (the repository host) and `git`; a test passes stand-ins, so no test publishes. */
|
|
89
|
+
export interface SharePorts {
|
|
90
|
+
readonly host: RepositoryHostPort;
|
|
91
|
+
readonly git: PublishGitPort;
|
|
92
|
+
}
|
|
93
|
+
export declare const githubSharePorts: () => SharePorts;
|
|
94
|
+
/** A completed share: where it went. */
|
|
95
|
+
export type ShareAppPluginResult = SharedPluginView & {
|
|
96
|
+
readonly owner: string;
|
|
97
|
+
readonly repo: string;
|
|
98
|
+
readonly tag: string;
|
|
99
|
+
};
|
|
100
|
+
/**
|
|
101
|
+
* What sharing one local plugin would do, read without sending anything: it packages the plugin under the app's home and asks the host who is
|
|
102
|
+
* signed in, whether the repository exists and whether this version is released there (then the plan releases the next patch).
|
|
103
|
+
* @param options - the repository owner (the signed-in account when absent).
|
|
104
|
+
*/
|
|
105
|
+
export declare function planAppPluginShare(root: string, home: string, name: string, options: {
|
|
106
|
+
readonly owner?: string;
|
|
107
|
+
}, ports: SharePorts): Promise<SharePlan>;
|
|
108
|
+
/**
|
|
109
|
+
* Share one local plugin through the plugin-hub path, exactly as the person confirmed it: the plan is read again, and when it no longer matches
|
|
110
|
+
* (another account signed in, the repository made meanwhile, a version released) nothing is sent and the error says to look again. The hub then
|
|
111
|
+
* publishes to that repository, version and visibility with the user's own `gh` and `git` (it reads no token), and the local store keeps the
|
|
112
|
+
* tarball as it does for every share.
|
|
113
|
+
* @param confirmed - the plan the person said yes to.
|
|
114
|
+
* @param options - the repository owner the frame is configured with (the signed-in account when absent).
|
|
115
|
+
*/
|
|
116
|
+
export declare function shareAppPlugin(root: string, home: string, name: string, confirmed: SharePlan, options: {
|
|
117
|
+
readonly owner?: string;
|
|
118
|
+
}, ports: SharePorts): Promise<ShareAppPluginResult>;
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Host's half of "the canvas shows what the files say": it loads the app's code again, and tells the page when the new code is up.
|
|
3
|
+
*
|
|
4
|
+
* What it does, in order, when the app's files change (a version restored, a branch switched, the chat or a PTY agent or an editor writing `src/`):
|
|
5
|
+
* the generation (./app-generation.ts) is raised; each of the app's rows (its routes, its composed plugins) imports its module again under it, which
|
|
6
|
+
* surfaces a syntax error or a missing import before anything is stopped; only then are the rows stopped and started from the new code. A row that
|
|
7
|
+
* does not start fails the whole reload: the last working generation comes back and its rows are started again, so the canvas keeps showing the last
|
|
8
|
+
* good app, and the error is kept for the frame to show (one line in the bar) until a reload succeeds.
|
|
9
|
+
*
|
|
10
|
+
* The rows run on the Cordis loader (`ctx.loader`), so the terminals, agents and chats around the app are untouched: only the app's own fibers restart.
|
|
11
|
+
*/
|
|
12
|
+
import type { AppReloadView } from './contract.ts';
|
|
13
|
+
import type { AppGeneration } from './app-generation.ts';
|
|
14
|
+
/** How long a change is waited on before it is acted on: a version restore or an agent's turn writes many files in a burst. */
|
|
15
|
+
export declare const RELOAD_DEBOUNCE_MS = 300;
|
|
16
|
+
/** One of the app's loader rows, as the reloader drives it. */
|
|
17
|
+
export interface AppRow {
|
|
18
|
+
readonly id: string;
|
|
19
|
+
/** Import the row's module under the current generation; rejects with the load error (a syntax error, a missing import). */
|
|
20
|
+
load(): Promise<void>;
|
|
21
|
+
/** Stop the row and start it from its module as it loads now; rejects when it does not run. */
|
|
22
|
+
restart(): Promise<void>;
|
|
23
|
+
}
|
|
24
|
+
export interface AppReloaderDeps {
|
|
25
|
+
readonly generation: AppGeneration;
|
|
26
|
+
/** The rows to restart, in the order they start. Read at each reload, so a row switched off meanwhile is left out. */
|
|
27
|
+
readonly rows: () => readonly AppRow[];
|
|
28
|
+
/** The app's folder (its real path): a failure's stack is read for the file of the app it points at. */
|
|
29
|
+
readonly appRoot?: string;
|
|
30
|
+
readonly report?: (cause: unknown) => void;
|
|
31
|
+
}
|
|
32
|
+
/** The line a person reads for a failed load: where (`src/board.ts:12`, when the stack points into the app's `src/`) and what, cut short. */
|
|
33
|
+
export declare function describeError(cause: unknown, appRoot?: string): string;
|
|
34
|
+
export declare class AppReloader {
|
|
35
|
+
private readonly deps;
|
|
36
|
+
private seq;
|
|
37
|
+
private shown;
|
|
38
|
+
private error;
|
|
39
|
+
/** The number the last attempt took: every attempt gets its own, so a failed one is never loaded again. */
|
|
40
|
+
private attempt;
|
|
41
|
+
/** The last generation whose rows run. */
|
|
42
|
+
private good;
|
|
43
|
+
private running;
|
|
44
|
+
private again;
|
|
45
|
+
private readonly waiters;
|
|
46
|
+
constructor(deps: AppReloaderDeps);
|
|
47
|
+
view(): AppReloadView;
|
|
48
|
+
/** The view once it differs from the one the caller has (`after` is its `seq`), or as it is when `timeoutMs` has passed. */
|
|
49
|
+
wait(after: number, timeoutMs: number): Promise<AppReloadView>;
|
|
50
|
+
/** Load the app's code again. A call made while a reload runs makes one more run after it (the files changed again), never two at once. */
|
|
51
|
+
reload(): Promise<void>;
|
|
52
|
+
private drain;
|
|
53
|
+
private once;
|
|
54
|
+
/** The new code did not load or start: the last working generation is what the rows run again (its modules are still loaded). */
|
|
55
|
+
private recover;
|
|
56
|
+
private change;
|
|
57
|
+
}
|
|
58
|
+
/** A file whose change is no change of the app: an editor's swap or backup file, a hidden file or folder. */
|
|
59
|
+
export declare function isNoise(filename: string): boolean;
|
|
60
|
+
/**
|
|
61
|
+
* Calls `onChange` once, `debounceMs` after the last change of a file under `dir` (recursively, or only the `only` files at its top), whoever made it.
|
|
62
|
+
* Returns the function that stops watching; a folder that does not exist is not watched (an app without `src/` has no code to load again).
|
|
63
|
+
*/
|
|
64
|
+
export declare function watchFolder(dir: string, onChange: () => void, options?: {
|
|
65
|
+
readonly debounceMs?: number;
|
|
66
|
+
readonly report?: (cause: unknown) => void;
|
|
67
|
+
readonly only?: readonly string[];
|
|
68
|
+
}): () => void;
|
|
69
|
+
/** {@link watchFolder} over several folders, one debounce per folder: a burst across two folders reloads once, as a reload already running takes the next one in. */
|
|
70
|
+
export declare function watchFolders(dirs: readonly string[], onChange: () => void, options?: {
|
|
71
|
+
readonly debounceMs?: number;
|
|
72
|
+
readonly report?: (cause: unknown) => void;
|
|
73
|
+
}): () => void;
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import type { GitRemoteState, SnapshotApply, SnapshotCapture, SnapshotVerify } from './contract.ts';
|
|
2
|
+
/** Where the verbs are in an app folder. */
|
|
3
|
+
export declare const SNAPSHOT_MODULE = "plugins/manifest/snapshot.ts";
|
|
4
|
+
/** An app made before the snapshot verbs: a save goes on without a capture, a tool says so. */
|
|
5
|
+
export declare class SnapshotVerbsMissing extends Error {
|
|
6
|
+
}
|
|
7
|
+
/** The verbs as the app's module exports them. */
|
|
8
|
+
export interface SnapshotVerbs {
|
|
9
|
+
captureApp(appRoot: string): SnapshotCapture;
|
|
10
|
+
verifyApp(dir: string): SnapshotVerify;
|
|
11
|
+
applySnapshot(from: string, appRoot: string): SnapshotApply;
|
|
12
|
+
}
|
|
13
|
+
/** The branch's remote as the Git tab reads it. */
|
|
14
|
+
export interface VersionRemote {
|
|
15
|
+
state(options?: {
|
|
16
|
+
readonly fetch?: boolean;
|
|
17
|
+
}): Promise<GitRemoteState>;
|
|
18
|
+
}
|
|
19
|
+
export interface AppSnapshotService {
|
|
20
|
+
/** A row for every plugin folder of the app that has none, then `blend.lock.json`. @throws when the app has no snapshot verbs. */
|
|
21
|
+
capture(): Promise<SnapshotCapture>;
|
|
22
|
+
/**
|
|
23
|
+
* The capture every version starts with (Save point and the auto-save): undefined when the app was made before the verbs, so the version is
|
|
24
|
+
* saved as before. @throws what else stops a capture (a `blend.yaml` that does not parse).
|
|
25
|
+
*/
|
|
26
|
+
captureForSave(): Promise<SnapshotCapture | undefined>;
|
|
27
|
+
/** The app (or another snapshot folder, relative to the app) checked against its own lock, offline. */
|
|
28
|
+
verify(dir?: string): Promise<SnapshotVerify>;
|
|
29
|
+
/** Brings another snapshot folder into the app; writes nothing on a conflict. Only on the person's word: it changes the app's composition. */
|
|
30
|
+
apply(dir: string): Promise<SnapshotApply>;
|
|
31
|
+
/** The checked-out branch against its remote; `fetch` asks the remote first. */
|
|
32
|
+
remote(fetch?: boolean): Promise<GitRemoteState>;
|
|
33
|
+
}
|
|
34
|
+
/** Imports the app's own verbs. @throws a sentence naming the missing file when the app was made before them. */
|
|
35
|
+
export declare function loadSnapshotVerbs(root: string): Promise<SnapshotVerbs>;
|
|
36
|
+
/**
|
|
37
|
+
* @param load - the app's verbs; read once, on first use (a test passes its own).
|
|
38
|
+
* Capture and apply write `blend.yaml`, the lock and plugin folders: they run one at a time, and a verify waits for the write before it.
|
|
39
|
+
*/
|
|
40
|
+
export declare function createAppSnapshot(root: string, remote: VersionRemote, load?: () => Promise<SnapshotVerbs>): AppSnapshotService;
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* An app's own URLs seen from the frame's root (development host only). The app's pages answer under the canvas prefix (`/app`), but a page written the
|
|
3
|
+
* way the docs teach carries root-relative links, form actions, image sources and fetch paths. A request the frame's root did not answer, made from a
|
|
4
|
+
* page under the prefix, belongs to the app: a navigation is sent back under the prefix (method and body kept), and a sub-resource is served there
|
|
5
|
+
* without leaving it. Production serves the app at the root and has none of this.
|
|
6
|
+
*/
|
|
7
|
+
/** Whether `pathname` is the app base or below it. */
|
|
8
|
+
export declare function underAppBase(appBase: string, pathname: string): boolean;
|
|
9
|
+
/** The path of a same-origin Referer header; undefined when it is missing or not an absolute URL. */
|
|
10
|
+
export declare function refererPath(referer: string | null): string | undefined;
|
|
11
|
+
/**
|
|
12
|
+
* Where an app page's navigation that reached the frame's root goes: the same path and query under the app base. Only a browser navigation
|
|
13
|
+
* (`Sec-Fetch-Mode: navigate`) from a page under the app base counts; the frame's own page load has no such referer.
|
|
14
|
+
*/
|
|
15
|
+
export declare function appNavigationTarget(appBase: string, url: URL, headers: Headers): string | undefined;
|
|
16
|
+
/** Where a sub-resource, form response or fetch from an app page that reached the frame's root is served: the same path and query under the app base. */
|
|
17
|
+
export declare function appFallbackTarget(appBase: string, url: URL, headers: Headers): string | undefined;
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The frame's auto-save: when the chat's agent finishes a turn that changed the app's files, the Host makes a save point (a version) by itself and
|
|
3
|
+
* remembers which turn it belongs to, so the chat can say "edited src/routes.ts, src/board.ts · saved as v7" under that answer
|
|
4
|
+
* (docs/design/blends-frame-mockup.html, scenario 2).
|
|
5
|
+
*
|
|
6
|
+
* The turn-end signal is DSH's own: its `workspace-changes` plugin diffs the working tree around every turn (the person's earlier unsaved edits never
|
|
7
|
+
* enter a turn's list) and appends a `workspace/changes` session event only when files changed, so a turn that changed nothing makes no version here.
|
|
8
|
+
* The Host hears that event on `session/event`, reads the turn's file list from `ctx.workspaceChanges.summary`, and saves through `acryl-versions`.
|
|
9
|
+
*/
|
|
10
|
+
import type { TurnSaveView } from './contract.ts';
|
|
11
|
+
/** The person's request, shortened into a version's name: its first sentence or clause, one line, cut at a word. */
|
|
12
|
+
export declare function requestSubject(request: string | undefined, limit?: number): string;
|
|
13
|
+
/** The text of a user message's blocks, in order; blocks that are not text (images) add nothing. */
|
|
14
|
+
export declare function messageText(data: unknown): string;
|
|
15
|
+
/** What a chat's turn saved, kept in a file so the line under an answer is still there after a restart. */
|
|
16
|
+
export declare class SaveStore {
|
|
17
|
+
private readonly file;
|
|
18
|
+
private readonly report;
|
|
19
|
+
private loaded;
|
|
20
|
+
private writing;
|
|
21
|
+
constructor(file: string, report?: (cause: unknown) => void);
|
|
22
|
+
forSession(session: string): Promise<readonly TurnSaveView[]>;
|
|
23
|
+
/** Remember a turn's save; a turn saved twice (its changes settled after the first record) keeps every file and the newer version. */
|
|
24
|
+
put(session: string, save: TurnSaveView): Promise<void>;
|
|
25
|
+
private read;
|
|
26
|
+
private trim;
|
|
27
|
+
/** One write at a time, each to a new file renamed into place, so a crash leaves the old list or the new one. */
|
|
28
|
+
private write;
|
|
29
|
+
}
|
|
30
|
+
/** A session event, as `session/event` carries it. */
|
|
31
|
+
export interface SessionEventLike {
|
|
32
|
+
readonly type: string;
|
|
33
|
+
readonly seq: number;
|
|
34
|
+
readonly data: unknown;
|
|
35
|
+
}
|
|
36
|
+
export interface AutoSaveDeps {
|
|
37
|
+
/** The files a `workspace/changes` event of a session announced (`ctx.workspaceChanges.summary`); undefined when the Host no longer has it. */
|
|
38
|
+
summary(session: string, seq: number): {
|
|
39
|
+
readonly files: readonly {
|
|
40
|
+
readonly display: string;
|
|
41
|
+
}[];
|
|
42
|
+
} | undefined;
|
|
43
|
+
/** Save the app's files as a version called `message`; undefined when there was nothing to save. */
|
|
44
|
+
save(message: string): Promise<{
|
|
45
|
+
readonly hash: string;
|
|
46
|
+
readonly version: number;
|
|
47
|
+
readonly subject: string;
|
|
48
|
+
} | undefined>;
|
|
49
|
+
readonly store: SaveStore;
|
|
50
|
+
readonly report: (cause: unknown) => void;
|
|
51
|
+
}
|
|
52
|
+
/** Listens to the chat's session events and saves a version after each turn that changed files. */
|
|
53
|
+
export declare class AutoSave {
|
|
54
|
+
private readonly deps;
|
|
55
|
+
private readonly turns;
|
|
56
|
+
/** Saves run one after another: two chats finishing together must not commit over each other. */
|
|
57
|
+
private tail;
|
|
58
|
+
constructor(deps: AutoSaveDeps);
|
|
59
|
+
observe(session: string, event: SessionEventLike): void;
|
|
60
|
+
/** Resolves when every save queued so far has finished. */
|
|
61
|
+
settled(): Promise<void>;
|
|
62
|
+
private saveTurn;
|
|
63
|
+
}
|