@acrylblends/blends-frame 0.1.0 → 0.1.1

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.
@@ -58,16 +58,17 @@ export declare class AppReloader {
58
58
  /** A file whose change is no change of the app: an editor's swap or backup file, a hidden file or folder. */
59
59
  export declare function isNoise(filename: string): boolean;
60
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).
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
+ * with the paths that changed in the burst (`dir` itself when the system did not say which file). Returns the function that stops watching; a folder
63
+ * that does not exist is not watched (an app without `src/` has no code to load again).
63
64
  */
64
- export declare function watchFolder(dir: string, onChange: () => void, options?: {
65
+ export declare function watchFolder(dir: string, onChange: (changed: readonly string[]) => void, options?: {
65
66
  readonly debounceMs?: number;
66
67
  readonly report?: (cause: unknown) => void;
67
68
  readonly only?: readonly string[];
68
69
  }): () => void;
69
70
  /** {@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
+ export declare function watchFolders(dirs: readonly string[], onChange: (changed: readonly string[]) => void, options?: {
71
72
  readonly debounceMs?: number;
72
73
  readonly report?: (cause: unknown) => void;
73
74
  }): () => void;
@@ -0,0 +1,43 @@
1
+ /** `blend.yaml` read for this decision: the app without its pulled records, and the digest remembered for each pulled plugin. */
2
+ export interface AppDefinition {
3
+ /** The definition with the pulled records taken out, as canonical JSON: equal when no row, order or config other than those changed. */
4
+ readonly app: string;
5
+ /** The content digest (sha256 hex) remembered for each pulled plugin, by name. */
6
+ readonly pulled: Readonly<Record<string, string>>;
7
+ }
8
+ /** `blend.yaml`'s text as an {@link AppDefinition}. A text that does not parse is its own definition, so any change to it loads the app again. */
9
+ export declare function readDefinition(text: string): AppDefinition;
10
+ /** The digest a running app's pull installed, by plugin name; undefined when it pulled no plugin of that name (or is not running). */
11
+ export type PulledDigest = (name: string) => string | undefined;
12
+ /** The app's files as its code was last loaded, and the decision for each burst of changes after it. */
13
+ export declare class AppliedLive {
14
+ private readonly root;
15
+ private readonly pulledDigest;
16
+ private definition;
17
+ private folders;
18
+ /** `root` is the app's folder; the state is read now, as the app's code was loaded at start. `pulledDigest` answers for a pull `blend.yaml` does not remember. */
19
+ constructor(root: string, pulledDigest?: PulledDigest);
20
+ /** The app's code is being loaded again from the files as they are now: they are the new reference. */
21
+ loaded(): void;
22
+ /**
23
+ * Whether the app's code must be loaded again for these changed paths (absolute, as the watcher reports them). `false` when the running app has
24
+ * applied every one of them itself; the pulled-records-only `blend.yaml` then becomes the reference.
25
+ */
26
+ needsReload(changed: readonly string[]): boolean;
27
+ private read;
28
+ }
29
+ /**
30
+ * Watches the app's files - `src/`, `plugins/` and the `blend.yaml` at its root - and calls `reload` for a burst of changes the running app has not
31
+ * applied itself. A decision that cannot read a file (it went away meanwhile) is reported and loads the app again, as without the decision.
32
+ * @returns the function that stops watching.
33
+ */
34
+ export declare function watchAppFiles(root: string, reload: () => void, options?: {
35
+ readonly debounceMs?: number;
36
+ readonly report?: (cause: unknown) => void;
37
+ readonly pulledDigest?: PulledDigest;
38
+ }): () => void;
39
+ /**
40
+ * The running app's `pluginShare` as the frame reads it: its `pulledDigest`, when the service is there and has one. Read at each call, as the app's rows
41
+ * come and go with a reload; anything else answers undefined, so the decision falls back to `blend.yaml` alone.
42
+ */
43
+ export declare function pulledDigestOf(service: () => unknown): PulledDigest;
package/lib/index.js CHANGED
@@ -1,9 +1,9 @@
1
1
  import { appGeneration } from "./app-generation.js";
2
2
  import { createRequire } from "node:module";
3
3
  import { execFile, execFileSync } from "node:child_process";
4
- import { cpSync, existsSync, mkdirSync, realpathSync, rmSync, watch, writeFileSync } from "node:fs";
4
+ import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
5
5
  import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
6
- import { basename, dirname, isAbsolute, join, resolve } from "node:path";
6
+ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
7
7
  import { Acryl } from "acrylblends";
8
8
  import { error } from "@acrylblends/loopback-http";
9
9
  import { INVALID_JSON, jsonBody, ownPage, privateApi, readJson } from "@acrylblends/loopback-http/router";
@@ -12,6 +12,8 @@ import * as workspaceHost from "@acrylblends/workspace";
12
12
  import { promisify } from "node:util";
13
13
  import { PluginStore, bumpVersion, gitCli, githubCli, parseVersion, sharePlugin, storeRootOf } from "@webboxes/plugin-hub";
14
14
  import { pathToFileURL } from "node:url";
15
+ import { digestFolder } from "@webboxes/blends-core";
16
+ import { parseDocument } from "yaml";
15
17
  import { boundContextSummary, createUserMessage } from "@deepseek-ai/dsh-llm";
16
18
  import { randomBytes } from "node:crypto";
17
19
  //#region src/contract.ts
@@ -996,21 +998,28 @@ function isNoise(filename) {
996
998
  return filename.split(/[\\/]/u).some((part) => part.startsWith(".")) || /(~|\.sw[a-p]|\.tmp)$/u.test(filename);
997
999
  }
998
1000
  /**
999
- * 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.
1000
- * 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).
1001
+ * 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,
1002
+ * with the paths that changed in the burst (`dir` itself when the system did not say which file). Returns the function that stops watching; a folder
1003
+ * that does not exist is not watched (an app without `src/` has no code to load again).
1001
1004
  */
1002
1005
  function watchFolder(dir, onChange, options = {}) {
1003
1006
  if (!existsSync(dir)) return () => {};
1004
1007
  const debounceMs = options.debounceMs ?? 300;
1005
1008
  let timer;
1009
+ const changed = /* @__PURE__ */ new Set();
1006
1010
  const startedAt = Date.now();
1007
1011
  const only = options.only;
1008
1012
  const watcher = watch(dir, { recursive: only === void 0 }, (_event, filename) => {
1009
1013
  if (Date.now() - startedAt < REPLAY_WINDOW_MS) return;
1010
1014
  if (only !== void 0 && (typeof filename !== "string" || !only.includes(filename))) return;
1011
1015
  if (typeof filename === "string" && isNoise(filename)) return;
1016
+ changed.add(typeof filename === "string" ? join(dir, filename) : dir);
1012
1017
  clearTimeout(timer);
1013
- timer = setTimeout(onChange, debounceMs);
1018
+ timer = setTimeout(() => {
1019
+ const burst = [...changed];
1020
+ changed.clear();
1021
+ onChange(burst);
1022
+ }, debounceMs);
1014
1023
  });
1015
1024
  watcher.on("error", (cause) => {
1016
1025
  options.report?.(cause);
@@ -1028,6 +1037,143 @@ function watchFolders(dirs, onChange, options = {}) {
1028
1037
  };
1029
1038
  }
1030
1039
  //#endregion
1040
+ //#region src/applied-live.ts
1041
+ /**
1042
+ * Which changes of an app's files the running app has already applied itself, so the frame does not load its code again for them (spec 049 T022).
1043
+ *
1044
+ * A pull (`plugin pull`, the door's or the frame's) installs a plugin live: it writes `plugins/<name>/`, remembers the release in `blend.yaml` (the
1045
+ * `plugin-share` row's `pulled` config) and the plugin runs at once. Loading the whole app again for those writes restarts every app row for seconds,
1046
+ * and a second pull made meanwhile is cut off. The files themselves say which writes those were, so this needs no timer and no event:
1047
+ *
1048
+ * - `plugins/<name>/` that digests to the digest of its pull is the released plugin as pulled. An edit changes the digest, so an agent editing a pulled
1049
+ * plugin still has the app loaded again. The digest is the one `blend.yaml` remembers or, for a pull `blend.yaml` does not remember (from a local
1050
+ * file), the one the running `pluginShare` installed.
1051
+ * - `plugins/<name>/` that is gone and was not there when the app's code was last loaded came and went live (a refused pull, a plugin removed live).
1052
+ * - `blend.yaml` that differs only in the pulled records changes no row.
1053
+ *
1054
+ * Anything else, every change of `src/` among it, has the app loaded again, as before.
1055
+ */
1056
+ /** The row whose config remembers the pulled plugins (acrylblends' `plugin-share`). */
1057
+ const SHARE_ROW = "plugin-share";
1058
+ /** `blend.yaml`'s text as an {@link AppDefinition}. A text that does not parse is its own definition, so any change to it loads the app again. */
1059
+ function readDefinition(text) {
1060
+ const document = parseDocument(text);
1061
+ if (document.errors.length > 0) return {
1062
+ app: text,
1063
+ pulled: {}
1064
+ };
1065
+ const value = document.toJS();
1066
+ const rows = value?.spec?.rows;
1067
+ const pulled = {};
1068
+ if (Array.isArray(rows)) for (const row of rows) {
1069
+ if (row?.name !== SHARE_ROW || typeof row.config !== "object" || row.config === null) continue;
1070
+ const records = row.config.pulled;
1071
+ if (typeof records === "object" && records !== null) {
1072
+ for (const [name, record] of Object.entries(records)) if (typeof record?.digest === "string") pulled[name] = record.digest;
1073
+ }
1074
+ delete row.config.pulled;
1075
+ if (Object.keys(row.config).length === 0) delete row.config;
1076
+ }
1077
+ return {
1078
+ app: JSON.stringify(value),
1079
+ pulled
1080
+ };
1081
+ }
1082
+ /** The folders of `plugins/` now. */
1083
+ function pluginFolders(root) {
1084
+ const dir = join(root, "plugins");
1085
+ if (!existsSync(dir)) return /* @__PURE__ */ new Set();
1086
+ return new Set(readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name));
1087
+ }
1088
+ /** The app's files as its code was last loaded, and the decision for each burst of changes after it. */
1089
+ var AppliedLive = class {
1090
+ root;
1091
+ pulledDigest;
1092
+ definition;
1093
+ folders;
1094
+ /** `root` is the app's folder; the state is read now, as the app's code was loaded at start. `pulledDigest` answers for a pull `blend.yaml` does not remember. */
1095
+ constructor(root, pulledDigest = () => void 0) {
1096
+ this.root = root;
1097
+ this.pulledDigest = pulledDigest;
1098
+ this.definition = this.read().app;
1099
+ this.folders = pluginFolders(root);
1100
+ }
1101
+ /** The app's code is being loaded again from the files as they are now: they are the new reference. */
1102
+ loaded() {
1103
+ this.definition = this.read().app;
1104
+ this.folders = pluginFolders(this.root);
1105
+ }
1106
+ /**
1107
+ * Whether the app's code must be loaded again for these changed paths (absolute, as the watcher reports them). `false` when the running app has
1108
+ * applied every one of them itself; the pulled-records-only `blend.yaml` then becomes the reference.
1109
+ */
1110
+ needsReload(changed) {
1111
+ const now = this.read();
1112
+ for (const path of changed) {
1113
+ const parts = relative(this.root, path).split(sep);
1114
+ if (parts.length === 1 && parts[0] === "blend.yaml") {
1115
+ if (now.app !== this.definition) return true;
1116
+ continue;
1117
+ }
1118
+ const name = parts[0] === "plugins" ? parts[1] : void 0;
1119
+ if (name === void 0 || name === "") return true;
1120
+ const dir = join(this.root, "plugins", name);
1121
+ if (existsSync(dir) && statSync(dir).isDirectory()) {
1122
+ const remembered = now.pulled[name] ?? this.pulledDigest(name);
1123
+ if (remembered === void 0 || digestFolder(dir) !== remembered) return true;
1124
+ } else if (this.folders.has(name)) return true;
1125
+ }
1126
+ this.definition = now.app;
1127
+ return false;
1128
+ }
1129
+ read() {
1130
+ const file = join(this.root, "blend.yaml");
1131
+ return readDefinition(existsSync(file) ? readFileSync(file, "utf8") : "");
1132
+ }
1133
+ };
1134
+ /**
1135
+ * Watches the app's files - `src/`, `plugins/` and the `blend.yaml` at its root - and calls `reload` for a burst of changes the running app has not
1136
+ * applied itself. A decision that cannot read a file (it went away meanwhile) is reported and loads the app again, as without the decision.
1137
+ * @returns the function that stops watching.
1138
+ */
1139
+ function watchAppFiles(root, reload, options = {}) {
1140
+ const applied = new AppliedLive(root, options.pulledDigest);
1141
+ const onChange = (changed) => {
1142
+ try {
1143
+ if (!applied.needsReload(changed)) return;
1144
+ applied.loaded();
1145
+ } catch (cause) {
1146
+ options.report?.(cause);
1147
+ }
1148
+ reload();
1149
+ };
1150
+ const watching = {
1151
+ ...options.debounceMs === void 0 ? {} : { debounceMs: options.debounceMs },
1152
+ ...options.report === void 0 ? {} : { report: options.report }
1153
+ };
1154
+ const stopCode = watchFolders([join(root, "src"), join(root, "plugins")], onChange, watching);
1155
+ const stopBlend = watchFolder(root, onChange, {
1156
+ ...watching,
1157
+ only: ["blend.yaml"]
1158
+ });
1159
+ return () => {
1160
+ stopCode();
1161
+ stopBlend();
1162
+ };
1163
+ }
1164
+ /**
1165
+ * The running app's `pluginShare` as the frame reads it: its `pulledDigest`, when the service is there and has one. Read at each call, as the app's rows
1166
+ * come and go with a reload; anything else answers undefined, so the decision falls back to `blend.yaml` alone.
1167
+ */
1168
+ function pulledDigestOf(service) {
1169
+ return (name) => {
1170
+ const share = service();
1171
+ if (typeof share?.pulledDigest !== "function") return void 0;
1172
+ const digest = share.pulledDigest.call(share, name);
1173
+ return typeof digest === "string" ? digest : void 0;
1174
+ };
1175
+ }
1176
+ //#endregion
1031
1177
  //#region src/outward-guard.ts
1032
1178
  /**
1033
1179
  * The agent never sends the person's work out of the machine without their yes.
@@ -2831,18 +2977,13 @@ function apply(ctx, config = {}) {
2831
2977
  appRoot: realpathSync(root),
2832
2978
  report
2833
2979
  });
2834
- const reloadApp = () => {
2835
- appReload?.reload();
2836
- };
2837
- const stopWatchingCode = appReload === void 0 ? () => {} : watchFolders([join(root, "src"), join(root, "plugins")], reloadApp, { report });
2838
- const stopWatchingBlend = appReload === void 0 ? () => {} : watchFolder(root, reloadApp, {
2980
+ const pulledDigest = pulledDigestOf(() => ctx.get("pluginShare"));
2981
+ const stopWatching = appReload === void 0 ? () => {} : watchAppFiles(root, () => {
2982
+ appReload.reload();
2983
+ }, {
2839
2984
  report,
2840
- only: ["blend.yaml"]
2985
+ pulledDigest
2841
2986
  });
2842
- const stopWatching = () => {
2843
- stopWatchingCode();
2844
- stopWatchingBlend();
2845
- };
2846
2987
  /** git's own line as the message a person reads: the runner keeps it as the failure's detail. */
2847
2988
  const gitReason = (cause, fallback) => {
2848
2989
  const detail = cause.detail;