@acryldev/manifest 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/app-plugins.ts +86 -0
- package/index.ts +645 -0
- package/lib/app-plugins.js +61 -0
- package/lib/app-plugins.js.map +1 -0
- package/lib/index.js +408 -0
- package/lib/index.js.map +1 -0
- package/lib/lock.js +87 -0
- package/lib/lock.js.map +1 -0
- package/lib/snapshot.js +231 -0
- package/lib/snapshot.js.map +1 -0
- package/lib/types/app-plugins.d.ts +18 -0
- package/lib/types/index.d.ts +119 -0
- package/lib/types/lock.d.ts +7 -0
- package/lib/types/snapshot.d.ts +35 -0
- package/lib/types/tsdown.config.d.ts +2 -0
- package/lib/types/upgrade-cli.d.ts +1 -0
- package/lib/types/upgrade.d.ts +20 -0
- package/lock.ts +115 -0
- package/package.json +54 -3
- package/plugin.json +19 -0
- package/snapshot.ts +275 -0
- package/test/blend-manifest.v1alpha1.schema.json +238 -0
- package/test/lock.test.ts +82 -0
- package/test/manifest.test.ts +332 -0
- package/test/snapshot.test.ts +184 -0
- package/test/upgrade-cli.test.ts +123 -0
- package/test/upgrade.test.ts +158 -0
- package/tsconfig.json +21 -0
- package/tsdown.config.ts +23 -0
- package/upgrade-cli.ts +70 -0
- package/upgrade.ts +97 -0
- package/README.md +0 -3
package/lib/lock.js
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
import { pluginEntry } from "./app-plugins.js";
|
|
2
|
+
import { blueprintsIn } from "./index.js";
|
|
3
|
+
import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
|
|
4
|
+
import { join, resolve } from "node:path";
|
|
5
|
+
import { fileURLToPath } from "node:url";
|
|
6
|
+
import { digestFolder, generateBlendLock, manifestDigest, parseDefinition, resolveDefinition } from "@acryldev/blends-core";
|
|
7
|
+
//#region lock.ts
|
|
8
|
+
/**
|
|
9
|
+
* `npm run lock`: write `blend.lock.json` (formatVersion 3, the lock ACRYL writes too) next to the manifest, recording what the app is
|
|
10
|
+
* built from: the manifest's identity and digest, the Blueprint it was resolved over, its resolved parameters and rows, and a content
|
|
11
|
+
* digest of every plugin folder in `plugins/`. Commit it; a diff of the lock is a review of
|
|
12
|
+
* what changed.
|
|
13
|
+
*/
|
|
14
|
+
const LOCK_FILE = "blend.lock.json";
|
|
15
|
+
function read(file) {
|
|
16
|
+
const text = readFileSync(file, "utf8");
|
|
17
|
+
const { document, diagnostics } = parseDefinition(text);
|
|
18
|
+
if (diagnostics.length > 0) throw new Error(`${file}:\n${diagnostics.map((d) => `${d.path}: ${d.message}`).join("\n")}`);
|
|
19
|
+
return {
|
|
20
|
+
text,
|
|
21
|
+
document
|
|
22
|
+
};
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* A plugin folder's plugin name, as its entry file declares it (`export const name = '...'`): the library copies keep their pre-T038 plugin names
|
|
26
|
+
* while their folders are the scoped packages' short names (spec 051 T038), so the folder alone no longer names the module a row mounts. A folder
|
|
27
|
+
* without a readable name keeps its folder name, which is the app plugins' contract.
|
|
28
|
+
*/
|
|
29
|
+
function moduleNameOf(directory, folderName) {
|
|
30
|
+
const entry = pluginEntry(directory);
|
|
31
|
+
if (entry === void 0) return folderName;
|
|
32
|
+
try {
|
|
33
|
+
return /export const name = '([^']+)'/u.exec(readFileSync(entry, "utf8"))?.[1] ?? folderName;
|
|
34
|
+
} catch {
|
|
35
|
+
return folderName;
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
function localModules(appRoot, folder) {
|
|
39
|
+
const directory = join(appRoot, folder);
|
|
40
|
+
if (!existsSync(directory)) return [];
|
|
41
|
+
return readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => ({
|
|
42
|
+
name: moduleNameOf(join(directory, entry.name), entry.name),
|
|
43
|
+
origin: "local",
|
|
44
|
+
digest: `sha256:${digestFolder(join(directory, entry.name))}`,
|
|
45
|
+
source: `${folder}/${entry.name}`
|
|
46
|
+
}));
|
|
47
|
+
}
|
|
48
|
+
function writeLock(appRoot) {
|
|
49
|
+
const blendFile = join(appRoot, "blend.yaml");
|
|
50
|
+
const getBlueprint = blueprintsIn(join(appRoot, "blueprints"));
|
|
51
|
+
const { text, document } = read(blendFile);
|
|
52
|
+
const resolved = resolveDefinition(document, { getDefinition: (id) => {
|
|
53
|
+
const file = getBlueprint(id);
|
|
54
|
+
return file === void 0 ? void 0 : read(file).document;
|
|
55
|
+
} });
|
|
56
|
+
if (resolved.definition === null) throw new Error(`${blendFile}:\n${resolved.diagnostics.map((d) => `${d.path}: ${d.message}`).join("\n")}`);
|
|
57
|
+
const lineage = document.spec.lineage;
|
|
58
|
+
const blueprintFile = lineage ? getBlueprint(lineage.blueprint) : void 0;
|
|
59
|
+
const { lock } = generateBlendLock({
|
|
60
|
+
resolved: resolved.definition,
|
|
61
|
+
origin: {
|
|
62
|
+
id: document.metadata.id,
|
|
63
|
+
kind: document.kind,
|
|
64
|
+
version: document.metadata.version,
|
|
65
|
+
digest: manifestDigest(text)
|
|
66
|
+
},
|
|
67
|
+
modules: [
|
|
68
|
+
...localModules(appRoot, "plugins"),
|
|
69
|
+
...localModules(appRoot, "src/plugins"),
|
|
70
|
+
...localModules(appRoot, "extensions")
|
|
71
|
+
],
|
|
72
|
+
...lineage ? { lineage: {
|
|
73
|
+
...lineage,
|
|
74
|
+
...blueprintFile ? { digest: manifestDigest(readFileSync(blueprintFile, "utf8")) } : {}
|
|
75
|
+
} } : {}
|
|
76
|
+
});
|
|
77
|
+
writeFileSync(join(appRoot, LOCK_FILE), `${JSON.stringify(lock, null, 2)}\n`);
|
|
78
|
+
return lock;
|
|
79
|
+
}
|
|
80
|
+
if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
|
|
81
|
+
const locked = writeLock(resolve(fileURLToPath(new URL("../..", import.meta.url))));
|
|
82
|
+
console.log(`wrote ${LOCK_FILE}: ${locked.rows.length} rows, ${locked.modules.length} local plugins`);
|
|
83
|
+
}
|
|
84
|
+
//#endregion
|
|
85
|
+
export { LOCK_FILE, writeLock };
|
|
86
|
+
|
|
87
|
+
//# sourceMappingURL=lock.js.map
|
package/lib/lock.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"lock.js","names":[],"sources":["../lock.ts"],"sourcesContent":["/**\n * `npm run lock`: write `blend.lock.json` (formatVersion 3, the lock ACRYL writes too) next to the manifest, recording what the app is\n * built from: the manifest's identity and digest, the Blueprint it was resolved over, its resolved parameters and rows, and a content\n * digest of every plugin folder in `plugins/`. Commit it; a diff of the lock is a review of\n * what changed.\n */\nimport { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'\nimport { join, resolve } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport {\n type BlendDocument,\n type BlendLock,\n digestFolder,\n generateBlendLock,\n type LockModule,\n manifestDigest,\n parseDefinition,\n resolveDefinition,\n} from '@acryldev/blends-core'\nimport { pluginEntry } from './app-plugins.ts'\nimport { blueprintsIn } from './index.ts'\n\nexport const LOCK_FILE = 'blend.lock.json'\n\ntype LockV3 = Extract<BlendLock, { formatVersion: 3 }>\n\nfunction read(file: string): { text: string; document: BlendDocument } {\n const text = readFileSync(file, 'utf8')\n const { document, diagnostics } = parseDefinition(text)\n if (diagnostics.length > 0)\n throw new Error(`${file}:\\n${diagnostics.map((d) => `${d.path}: ${d.message}`).join('\\n')}`)\n return { text, document: document as BlendDocument }\n}\n\n/**\n * A plugin folder's plugin name, as its entry file declares it (`export const name = '...'`): the library copies keep their pre-T038 plugin names\n * while their folders are the scoped packages' short names (spec 051 T038), so the folder alone no longer names the module a row mounts. A folder\n * without a readable name keeps its folder name, which is the app plugins' contract.\n */\nfunction moduleNameOf(directory: string, folderName: string): string {\n const entry = pluginEntry(directory)\n if (entry === undefined) return folderName\n try {\n const match = /export const name = '([^']+)'/u.exec(readFileSync(entry, 'utf8'))\n return match?.[1] ?? folderName\n } catch {\n return folderName\n }\n}\n\nfunction localModules(appRoot: string, folder: string): LockModule[] {\n const directory = join(appRoot, folder)\n if (!existsSync(directory)) return []\n return readdirSync(directory, { withFileTypes: true })\n .filter((entry) => entry.isDirectory())\n .map((entry) => ({\n name: moduleNameOf(join(directory, entry.name), entry.name),\n origin: 'local' as const,\n digest: `sha256:${digestFolder(join(directory, entry.name))}`,\n source: `${folder}/${entry.name}`,\n }))\n}\n\nexport function writeLock(appRoot: string): LockV3 {\n const blendFile = join(appRoot, 'blend.yaml')\n const getBlueprint = blueprintsIn(join(appRoot, 'blueprints'))\n const { text, document } = read(blendFile)\n const resolved = resolveDefinition(document, {\n getDefinition: (id) => {\n const file = getBlueprint(id)\n return file === undefined ? undefined : read(file).document\n },\n })\n if (resolved.definition === null)\n throw new Error(\n `${blendFile}:\\n${resolved.diagnostics.map((d) => `${d.path}: ${d.message}`).join('\\n')}`,\n )\n // A Blend records the Blueprint file it was resolved over, so an upgrade shows up as a lock diff.\n const lineage = document.spec.lineage\n const blueprintFile = lineage ? getBlueprint(lineage.blueprint) : undefined\n const { lock } = generateBlendLock({\n resolved: resolved.definition,\n origin: {\n id: document.metadata.id,\n kind: document.kind,\n version: document.metadata.version,\n digest: manifestDigest(text),\n },\n modules: [\n ...localModules(appRoot, 'plugins'),\n ...localModules(appRoot, 'src/plugins'),\n ...localModules(appRoot, 'extensions'),\n ],\n ...(lineage\n ? {\n lineage: {\n ...lineage,\n ...(blueprintFile\n ? { digest: manifestDigest(readFileSync(blueprintFile, 'utf8')) }\n : {}),\n },\n }\n : {}),\n })\n writeFileSync(join(appRoot, LOCK_FILE), `${JSON.stringify(lock, null, 2)}\\n`)\n return lock as LockV3\n}\n\nif (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {\n const appRoot = resolve(fileURLToPath(new URL('../..', import.meta.url)))\n const locked = writeLock(appRoot)\n console.log(\n `wrote ${LOCK_FILE}: ${locked.rows.length} rows, ${locked.modules.length} local plugins`,\n )\n}\n"],"mappings":";;;;;;;;;;;;;AAsBA,MAAa,YAAY;AAIzB,SAAS,KAAK,MAAyD;CACrE,MAAM,OAAO,aAAa,MAAM,MAAM;CACtC,MAAM,EAAE,UAAU,gBAAgB,gBAAgB,IAAI;CACtD,IAAI,YAAY,SAAS,GACvB,MAAM,IAAI,MAAM,GAAG,KAAK,KAAK,YAAY,KAAK,MAAM,GAAG,EAAE,KAAK,IAAI,EAAE,SAAS,CAAC,CAAC,KAAK,IAAI,GAAG;CAC7F,OAAO;EAAE;EAAgB;CAA0B;AACrD;;;;;;AAOA,SAAS,aAAa,WAAmB,YAA4B;CACnE,MAAM,QAAQ,YAAY,SAAS;CACnC,IAAI,UAAU,KAAA,GAAW,OAAO;CAChC,IAAI;EAEF,OADc,iCAAiC,KAAK,aAAa,OAAO,MAAM,CACnE,CAAC,GAAG,MAAM;CACvB,QAAQ;EACN,OAAO;CACT;AACF;AAEA,SAAS,aAAa,SAAiB,QAA8B;CACnE,MAAM,YAAY,KAAK,SAAS,MAAM;CACtC,IAAI,CAAC,WAAW,SAAS,GAAG,OAAO,CAAC;CACpC,OAAO,YAAY,WAAW,EAAE,eAAe,KAAK,CAAC,CAAC,CACnD,QAAQ,UAAU,MAAM,YAAY,CAAC,CAAC,CACtC,KAAK,WAAW;EACf,MAAM,aAAa,KAAK,WAAW,MAAM,IAAI,GAAG,MAAM,IAAI;EAC1D,QAAQ;EACR,QAAQ,UAAU,aAAa,KAAK,WAAW,MAAM,IAAI,CAAC;EAC1D,QAAQ,GAAG,OAAO,GAAG,MAAM;CAC7B,EAAE;AACN;AAEA,SAAgB,UAAU,SAAyB;CACjD,MAAM,YAAY,KAAK,SAAS,YAAY;CAC5C,MAAM,eAAe,aAAa,KAAK,SAAS,YAAY,CAAC;CAC7D,MAAM,EAAE,MAAM,aAAa,KAAK,SAAS;CACzC,MAAM,WAAW,kBAAkB,UAAU,EAC3C,gBAAgB,OAAO;EACrB,MAAM,OAAO,aAAa,EAAE;EAC5B,OAAO,SAAS,KAAA,IAAY,KAAA,IAAY,KAAK,IAAI,CAAC,CAAC;CACrD,EACF,CAAC;CACD,IAAI,SAAS,eAAe,MAC1B,MAAM,IAAI,MACR,GAAG,UAAU,KAAK,SAAS,YAAY,KAAK,MAAM,GAAG,EAAE,KAAK,IAAI,EAAE,SAAS,CAAC,CAAC,KAAK,IAAI,GACxF;CAEF,MAAM,UAAU,SAAS,KAAK;CAC9B,MAAM,gBAAgB,UAAU,aAAa,QAAQ,SAAS,IAAI,KAAA;CAClE,MAAM,EAAE,SAAS,kBAAkB;EACjC,UAAU,SAAS;EACnB,QAAQ;GACN,IAAI,SAAS,SAAS;GACtB,MAAM,SAAS;GACf,SAAS,SAAS,SAAS;GAC3B,QAAQ,eAAe,IAAI;EAC7B;EACA,SAAS;GACP,GAAG,aAAa,SAAS,SAAS;GAClC,GAAG,aAAa,SAAS,aAAa;GACtC,GAAG,aAAa,SAAS,YAAY;EACvC;EACA,GAAI,UACA,EACE,SAAS;GACP,GAAG;GACH,GAAI,gBACA,EAAE,QAAQ,eAAe,aAAa,eAAe,MAAM,CAAC,EAAE,IAC9D,CAAC;EACP,EACF,IACA,CAAC;CACP,CAAC;CACD,cAAc,KAAK,SAAS,SAAS,GAAG,GAAG,KAAK,UAAU,MAAM,MAAM,CAAC,EAAE,GAAG;CAC5E,OAAO;AACT;AAEA,IAAI,QAAQ,KAAK,MAAM,QAAQ,QAAQ,KAAK,EAAE,MAAM,cAAc,OAAO,KAAK,GAAG,GAAG;CAElF,MAAM,SAAS,UADC,QAAQ,cAAc,IAAI,IAAI,SAAS,OAAO,KAAK,GAAG,CAAC,CACxC,CAAC;CAChC,QAAQ,IACN,SAAS,UAAU,IAAI,OAAO,KAAK,OAAO,SAAS,OAAO,QAAQ,OAAO,eAC3E;AACF"}
|
package/lib/snapshot.js
ADDED
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
import { appPluginNames } from "./app-plugins.js";
|
|
2
|
+
import { LOCK_FILE, writeLock } from "./lock.js";
|
|
3
|
+
import { cpSync, existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
|
|
4
|
+
import { basename, join, resolve } from "node:path";
|
|
5
|
+
import { isSeq, parseDocument } from "yaml";
|
|
6
|
+
import { fileURLToPath } from "node:url";
|
|
7
|
+
import { FOLDER_DIGEST_SKIPPED, digestFolder, manifestDigest } from "@acryldev/blends-core";
|
|
8
|
+
//#region snapshot.ts
|
|
9
|
+
/**
|
|
10
|
+
* The snapshot verbs: an app folder is its own Blend (`blend.yaml` + `plugins/` + `blend.lock.json`), and these keep it one that can be passed on.
|
|
11
|
+
* Ported from ACRYL's Extension Context Pack (`plugins/plugin-context/lib/blend-capture.js` `captureApp`/`verifyBlend` and
|
|
12
|
+
* `lib/blend-apply.js` `applyBlend`), for an app whose plugins are folders rather than packages installed into a DSH profile.
|
|
13
|
+
*
|
|
14
|
+
* - `captureApp` records the app as it runs: every plugin folder of its own gets a row in `blend.yaml` if it has none yet (a live install becomes
|
|
15
|
+
* part of the composition), the person's text and comments are kept, and `blend.lock.json` is written again (lock.ts).
|
|
16
|
+
* - `verifyApp` checks a snapshot against its own lock, offline: `blend.yaml` still has the digest the lock recorded, and every plugin folder the
|
|
17
|
+
* lock names still hashes to its digest.
|
|
18
|
+
* - `applySnapshot` brings a snapshot into an app: it verifies the snapshot first, refuses the whole apply when a plugin folder of the same name
|
|
19
|
+
* in the app differs from the locked one (somebody's work is never overwritten), then copies the missing folders, writes the snapshot's
|
|
20
|
+
* `blend.yaml` under the app's own `metadata` (its rows come in, its identity stays the app's) and locks
|
|
21
|
+
* the app again. A running app reloads from the change. A plugin folder the snapshot does not have is left where it is, put on the
|
|
22
|
+
* `extensions` row's `off` list so it does not start, and reported.
|
|
23
|
+
*
|
|
24
|
+
* Not ported: ACRYL's registry and pulled modules (an app's lock records local folders only) and its evolution ledger (an app's history is its git
|
|
25
|
+
* versions).
|
|
26
|
+
*
|
|
27
|
+
* node plugins/manifest/snapshot.ts capture | verify [dir] | apply <snapshot dir>
|
|
28
|
+
*/
|
|
29
|
+
const MANIFEST = "blend.yaml";
|
|
30
|
+
/** Where a lock may place a plugin folder: one level inside the app's plugin folders, never outside the app. */
|
|
31
|
+
const MODULE_SOURCE = /^(plugins|src\/plugins|extensions)\/[a-z0-9][a-z0-9._-]*$/;
|
|
32
|
+
/** Replace a file in one step: a reader sees the old text or the new, never half of it. */
|
|
33
|
+
function writeAtomic(file, text) {
|
|
34
|
+
writeFileSync(`${file}.tmp`, text);
|
|
35
|
+
renameSync(`${file}.tmp`, file);
|
|
36
|
+
}
|
|
37
|
+
const folderDigest = (dir) => `sha256:${digestFolder(dir)}`;
|
|
38
|
+
/** The plugin names `blend.yaml`'s rows mount (`name`, the folder a row loads). */
|
|
39
|
+
function rowNames(text) {
|
|
40
|
+
const rows = parseDocument(text).toJS()?.spec?.rows;
|
|
41
|
+
return new Set(Array.isArray(rows) ? rows.map((row) => String(row?.name)) : []);
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Record the app as it runs: a row for every plugin folder of its own that has none (before the `extensions` row, else before the server, else
|
|
45
|
+
* last), then `blend.lock.json`. Idempotent: a second capture with nothing new changes nothing in `blend.yaml`.
|
|
46
|
+
*/
|
|
47
|
+
function captureApp(appRoot) {
|
|
48
|
+
const file = join(appRoot, MANIFEST);
|
|
49
|
+
const text = readFileSync(file, "utf8");
|
|
50
|
+
const named = rowNames(text);
|
|
51
|
+
const missing = appPluginNames(join(appRoot, "plugins")).filter((name) => !named.has(name));
|
|
52
|
+
if (missing.length > 0) {
|
|
53
|
+
const document = parseDocument(text);
|
|
54
|
+
const rows = document.getIn(["spec", "rows"]);
|
|
55
|
+
if (!isSeq(rows)) throw new Error(`${file} has no spec.rows list; it is not an app definition`);
|
|
56
|
+
const names = rows.items.map((row) => String(row.get?.("name")));
|
|
57
|
+
const before = names.indexOf("extensions") >= 0 ? names.indexOf("extensions") : names.indexOf("acryl-node-server");
|
|
58
|
+
const at = before >= 0 ? before : rows.items.length;
|
|
59
|
+
rows.items.splice(at, 0, ...missing.map((name) => document.createNode({
|
|
60
|
+
id: name,
|
|
61
|
+
name
|
|
62
|
+
})));
|
|
63
|
+
writeAtomic(file, String(document));
|
|
64
|
+
}
|
|
65
|
+
return {
|
|
66
|
+
addedRows: missing,
|
|
67
|
+
modules: writeLock(appRoot).modules.length
|
|
68
|
+
};
|
|
69
|
+
}
|
|
70
|
+
/** Check a snapshot (an app folder, or a copy of one) against its own `blend.lock.json`. */
|
|
71
|
+
function verifyApp(dir) {
|
|
72
|
+
const manifestFile = join(dir, MANIFEST);
|
|
73
|
+
const lockFile = join(dir, LOCK_FILE);
|
|
74
|
+
if (!existsSync(manifestFile) || !existsSync(lockFile)) return {
|
|
75
|
+
ok: false,
|
|
76
|
+
problems: [`no ${MANIFEST} and ${LOCK_FILE} in ${dir}`],
|
|
77
|
+
checked: 0
|
|
78
|
+
};
|
|
79
|
+
let lock;
|
|
80
|
+
try {
|
|
81
|
+
lock = JSON.parse(readFileSync(lockFile, "utf8"));
|
|
82
|
+
} catch {
|
|
83
|
+
return {
|
|
84
|
+
ok: false,
|
|
85
|
+
problems: [`${LOCK_FILE} is not valid JSON`],
|
|
86
|
+
checked: 0
|
|
87
|
+
};
|
|
88
|
+
}
|
|
89
|
+
const problems = [];
|
|
90
|
+
if (lock.formatVersion !== 3) problems.push(`${LOCK_FILE} formatVersion ${String(lock.formatVersion)} is not 3`);
|
|
91
|
+
let checked = 1;
|
|
92
|
+
if (lock.origin?.digest !== manifestDigest(readFileSync(manifestFile, "utf8"))) problems.push(`${MANIFEST} changed since the lock was written (its digest no longer matches): capture again`);
|
|
93
|
+
for (const module of lock.modules ?? []) {
|
|
94
|
+
if (module.origin !== "local") continue;
|
|
95
|
+
checked += 1;
|
|
96
|
+
if (module.source === void 0 || !MODULE_SOURCE.test(module.source)) {
|
|
97
|
+
problems.push(`${module.name}: the lock places it at ${String(module.source)}, which is not a plugin folder of the app`);
|
|
98
|
+
continue;
|
|
99
|
+
}
|
|
100
|
+
const folder = join(dir, module.source);
|
|
101
|
+
if (!existsSync(folder)) problems.push(`${module.name}: ${module.source} is missing`);
|
|
102
|
+
else if (folderDigest(folder) !== module.digest) problems.push(`${module.name}: ${module.source} differs from the locked digest (edited after the capture)`);
|
|
103
|
+
}
|
|
104
|
+
return {
|
|
105
|
+
ok: problems.length === 0,
|
|
106
|
+
problems,
|
|
107
|
+
checked
|
|
108
|
+
};
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* The snapshot's `blend.yaml` with the app's own `metadata` (its id, name, version and visibility): a snapshot brings its composition, and the app
|
|
112
|
+
* it is applied to stays the app it is. An app with no `blend.yaml` yet takes the snapshot's whole.
|
|
113
|
+
*/
|
|
114
|
+
function keepIdentity(text, current) {
|
|
115
|
+
if (current === void 0) return text;
|
|
116
|
+
const own = parseDocument(current).get("metadata", true);
|
|
117
|
+
if (own === void 0) return text;
|
|
118
|
+
const document = parseDocument(text);
|
|
119
|
+
document.set("metadata", own);
|
|
120
|
+
return String(document);
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* `blend.yaml` with `names` on the `extensions` row's `off` list: the row starts every plugin folder that has no row of its own, and a folder the
|
|
124
|
+
* snapshot does not have must stay where it is without starting. Without an `extensions` row no such folder starts, and the text is unchanged.
|
|
125
|
+
*/
|
|
126
|
+
function keepOff(text, names) {
|
|
127
|
+
if (names.length === 0) return text;
|
|
128
|
+
const document = parseDocument(text);
|
|
129
|
+
const rows = document.getIn(["spec", "rows"]);
|
|
130
|
+
if (!isSeq(rows)) return text;
|
|
131
|
+
const row = rows.items.find((item) => item.get?.("name") === "extensions");
|
|
132
|
+
if (row === void 0) return text;
|
|
133
|
+
const listed = row.getIn(["config", "off"]);
|
|
134
|
+
const before = Array.isArray(listed?.toJSON?.()) ? listed?.toJSON?.() : [];
|
|
135
|
+
row.setIn(["config", "off"], document.createNode([.../* @__PURE__ */ new Set([...before, ...names])].sort()));
|
|
136
|
+
return String(document);
|
|
137
|
+
}
|
|
138
|
+
/** Bring the snapshot in `from` into the app at `appRoot` (see the file's doc). Nothing is written unless the whole apply can go through. */
|
|
139
|
+
function applySnapshot(from, appRoot) {
|
|
140
|
+
const verified = verifyApp(from);
|
|
141
|
+
const none = {
|
|
142
|
+
modules: [],
|
|
143
|
+
manifestChanged: false,
|
|
144
|
+
extra: []
|
|
145
|
+
};
|
|
146
|
+
if (!verified.ok) return {
|
|
147
|
+
ok: false,
|
|
148
|
+
problems: verified.problems,
|
|
149
|
+
...none
|
|
150
|
+
};
|
|
151
|
+
const lock = JSON.parse(readFileSync(join(from, LOCK_FILE), "utf8"));
|
|
152
|
+
const modules = [];
|
|
153
|
+
for (const module of lock.modules ?? []) {
|
|
154
|
+
if (module.origin !== "local" || module.source === void 0) {
|
|
155
|
+
modules.push({
|
|
156
|
+
name: module.name,
|
|
157
|
+
status: "skipped",
|
|
158
|
+
detail: `origin "${module.origin}" is not a plugin folder; add it yourself`
|
|
159
|
+
});
|
|
160
|
+
continue;
|
|
161
|
+
}
|
|
162
|
+
const target = join(appRoot, module.source);
|
|
163
|
+
if (!existsSync(target)) modules.push({
|
|
164
|
+
name: module.name,
|
|
165
|
+
status: "added",
|
|
166
|
+
source: module.source
|
|
167
|
+
});
|
|
168
|
+
else if (folderDigest(target) === module.digest) modules.push({
|
|
169
|
+
name: module.name,
|
|
170
|
+
status: "unchanged"
|
|
171
|
+
});
|
|
172
|
+
else modules.push({
|
|
173
|
+
name: module.name,
|
|
174
|
+
status: "conflict",
|
|
175
|
+
detail: `${module.source} in the app differs from the snapshot's; move it away or capture the app first`
|
|
176
|
+
});
|
|
177
|
+
}
|
|
178
|
+
const conflicts = modules.filter((module) => module.status === "conflict");
|
|
179
|
+
const report = modules.map(({ source: _, ...module }) => module);
|
|
180
|
+
if (conflicts.length > 0) return {
|
|
181
|
+
ok: false,
|
|
182
|
+
problems: conflicts.map((module) => `${module.name}: ${module.detail}`),
|
|
183
|
+
modules: report,
|
|
184
|
+
manifestChanged: false,
|
|
185
|
+
extra: []
|
|
186
|
+
};
|
|
187
|
+
for (const module of modules) if (module.status === "added" && module.source !== void 0) cpSync(join(from, module.source), join(appRoot, module.source), {
|
|
188
|
+
recursive: true,
|
|
189
|
+
filter: (path) => !FOLDER_DIGEST_SKIPPED.has(basename(path))
|
|
190
|
+
});
|
|
191
|
+
const locked = new Set((lock.modules ?? []).map((module) => module.name));
|
|
192
|
+
const extra = appPluginNames(join(appRoot, "plugins")).filter((name) => !locked.has(name));
|
|
193
|
+
const current = existsSync(join(appRoot, MANIFEST)) ? readFileSync(join(appRoot, MANIFEST), "utf8") : void 0;
|
|
194
|
+
const manifest = keepOff(keepIdentity(readFileSync(join(from, MANIFEST), "utf8"), current), extra);
|
|
195
|
+
const manifestChanged = current !== manifest;
|
|
196
|
+
if (manifestChanged) writeAtomic(join(appRoot, MANIFEST), manifest);
|
|
197
|
+
writeLock(appRoot);
|
|
198
|
+
return {
|
|
199
|
+
ok: true,
|
|
200
|
+
problems: [],
|
|
201
|
+
modules: report,
|
|
202
|
+
manifestChanged,
|
|
203
|
+
extra
|
|
204
|
+
};
|
|
205
|
+
}
|
|
206
|
+
if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
|
|
207
|
+
const appRoot = resolve(fileURLToPath(new URL("../..", import.meta.url)));
|
|
208
|
+
const [verb, target] = process.argv.slice(2);
|
|
209
|
+
if (verb === "capture") {
|
|
210
|
+
const { addedRows, modules } = captureApp(appRoot);
|
|
211
|
+
console.log(`captured: ${modules} plugin folder(s) locked${addedRows.length > 0 ? `; rows added to blend.yaml: ${addedRows.join(", ")}` : ""}`);
|
|
212
|
+
} else if (verb === "verify") {
|
|
213
|
+
const result = verifyApp(resolve(target ?? appRoot));
|
|
214
|
+
console.log(result.ok ? `ok: ${result.checked} checked` : result.problems.join("\n"));
|
|
215
|
+
process.exitCode = result.ok ? 0 : 1;
|
|
216
|
+
} else if (verb === "apply" && target !== void 0) {
|
|
217
|
+
const result = applySnapshot(resolve(target), appRoot);
|
|
218
|
+
for (const module of result.modules) console.log(`${module.status}: ${module.name}${module.detail ? ` (${module.detail})` : ""}`);
|
|
219
|
+
if (result.manifestChanged) console.log("blend.yaml: the snapshot's rows, under this app's own metadata");
|
|
220
|
+
if (result.extra.length > 0) console.log(`left in place, not in the snapshot: ${result.extra.join(", ")}`);
|
|
221
|
+
if (!result.ok) console.error(`nothing applied:\n${result.problems.join("\n")}`);
|
|
222
|
+
process.exitCode = result.ok ? 0 : 1;
|
|
223
|
+
} else {
|
|
224
|
+
console.error("usage: node plugins/manifest/snapshot.ts capture | verify [dir] | apply <snapshot dir>");
|
|
225
|
+
process.exitCode = 2;
|
|
226
|
+
}
|
|
227
|
+
}
|
|
228
|
+
//#endregion
|
|
229
|
+
export { applySnapshot, captureApp, verifyApp };
|
|
230
|
+
|
|
231
|
+
//# sourceMappingURL=snapshot.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"snapshot.js","names":[],"sources":["../snapshot.ts"],"sourcesContent":["/**\n * The snapshot verbs: an app folder is its own Blend (`blend.yaml` + `plugins/` + `blend.lock.json`), and these keep it one that can be passed on.\n * Ported from ACRYL's Extension Context Pack (`plugins/plugin-context/lib/blend-capture.js` `captureApp`/`verifyBlend` and\n * `lib/blend-apply.js` `applyBlend`), for an app whose plugins are folders rather than packages installed into a DSH profile.\n *\n * - `captureApp` records the app as it runs: every plugin folder of its own gets a row in `blend.yaml` if it has none yet (a live install becomes\n * part of the composition), the person's text and comments are kept, and `blend.lock.json` is written again (lock.ts).\n * - `verifyApp` checks a snapshot against its own lock, offline: `blend.yaml` still has the digest the lock recorded, and every plugin folder the\n * lock names still hashes to its digest.\n * - `applySnapshot` brings a snapshot into an app: it verifies the snapshot first, refuses the whole apply when a plugin folder of the same name\n * in the app differs from the locked one (somebody's work is never overwritten), then copies the missing folders, writes the snapshot's\n * `blend.yaml` under the app's own `metadata` (its rows come in, its identity stays the app's) and locks\n * the app again. A running app reloads from the change. A plugin folder the snapshot does not have is left where it is, put on the\n * `extensions` row's `off` list so it does not start, and reported.\n *\n * Not ported: ACRYL's registry and pulled modules (an app's lock records local folders only) and its evolution ledger (an app's history is its git\n * versions).\n *\n * node plugins/manifest/snapshot.ts capture | verify [dir] | apply <snapshot dir>\n */\nimport { cpSync, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs'\nimport { basename, join, resolve } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport { digestFolder, FOLDER_DIGEST_SKIPPED, manifestDigest } from '@acryldev/blends-core'\nimport { isSeq, parseDocument } from 'yaml'\nimport { appPluginNames } from './app-plugins.ts'\nimport { LOCK_FILE, writeLock } from './lock.ts'\n\nconst MANIFEST = 'blend.yaml'\n/** Where a lock may place a plugin folder: one level inside the app's plugin folders, never outside the app. */\nconst MODULE_SOURCE = /^(plugins|src\\/plugins|extensions)\\/[a-z0-9][a-z0-9._-]*$/\n\ninterface LockedModule {\n readonly name: string\n readonly origin: string\n readonly digest?: string\n readonly source?: string\n}\n\ninterface LockShape {\n readonly formatVersion?: unknown\n readonly origin?: { readonly digest?: unknown }\n readonly modules?: readonly LockedModule[]\n}\n\nexport interface CaptureResult {\n /** The rows added to `blend.yaml`, one per plugin folder that had none. */\n readonly addedRows: readonly string[]\n /** How many plugin folders the lock records. */\n readonly modules: number\n}\n\nexport interface VerifyResult {\n readonly ok: boolean\n readonly problems: readonly string[]\n /** The manifest digest and each plugin folder checked. */\n readonly checked: number\n}\n\nexport type ApplyStatus = 'added' | 'unchanged' | 'conflict' | 'skipped'\n\nexport interface ApplyResult {\n readonly ok: boolean\n /** Why nothing was applied: the snapshot does not match its lock, or a folder in the app differs from the locked one. */\n readonly problems: readonly string[]\n readonly modules: ReadonlyArray<{\n readonly name: string\n readonly status: ApplyStatus\n readonly detail?: string\n }>\n readonly manifestChanged: boolean\n /** The app's own plugin folders the snapshot does not have: left in place, and put on the `extensions` row's `off` list so they do not start. */\n readonly extra: readonly string[]\n}\n\n/** Replace a file in one step: a reader sees the old text or the new, never half of it. */\nfunction writeAtomic(file: string, text: string): void {\n writeFileSync(`${file}.tmp`, text)\n renameSync(`${file}.tmp`, file)\n}\n\nconst folderDigest = (dir: string): string => `sha256:${digestFolder(dir)}`\n\n/** The plugin names `blend.yaml`'s rows mount (`name`, the folder a row loads). */\nfunction rowNames(text: string): Set<string> {\n const rows = parseDocument(text).toJS()?.spec?.rows\n return new Set(\n Array.isArray(rows) ? rows.map((row: { name?: unknown }) => String(row?.name)) : [],\n )\n}\n\n/**\n * Record the app as it runs: a row for every plugin folder of its own that has none (before the `extensions` row, else before the server, else\n * last), then `blend.lock.json`. Idempotent: a second capture with nothing new changes nothing in `blend.yaml`.\n */\nexport function captureApp(appRoot: string): CaptureResult {\n const file = join(appRoot, MANIFEST)\n const text = readFileSync(file, 'utf8')\n const named = rowNames(text)\n const missing = appPluginNames(join(appRoot, 'plugins')).filter((name) => !named.has(name))\n if (missing.length > 0) {\n const document = parseDocument(text)\n const rows = document.getIn(['spec', 'rows'])\n if (!isSeq(rows)) throw new Error(`${file} has no spec.rows list; it is not an app definition`)\n const names = rows.items.map((row) =>\n String((row as { get?: (key: string) => unknown }).get?.('name')),\n )\n const before =\n names.indexOf('extensions') >= 0\n ? names.indexOf('extensions')\n : names.indexOf('acryl-node-server')\n const at = before >= 0 ? before : rows.items.length\n rows.items.splice(at, 0, ...missing.map((name) => document.createNode({ id: name, name })))\n writeAtomic(file, String(document))\n }\n const lock = writeLock(appRoot)\n return { addedRows: missing, modules: lock.modules.length }\n}\n\n/** Check a snapshot (an app folder, or a copy of one) against its own `blend.lock.json`. */\nexport function verifyApp(dir: string): VerifyResult {\n const manifestFile = join(dir, MANIFEST)\n const lockFile = join(dir, LOCK_FILE)\n if (!existsSync(manifestFile) || !existsSync(lockFile))\n return { ok: false, problems: [`no ${MANIFEST} and ${LOCK_FILE} in ${dir}`], checked: 0 }\n let lock: LockShape\n try {\n lock = JSON.parse(readFileSync(lockFile, 'utf8')) as LockShape\n } catch {\n return { ok: false, problems: [`${LOCK_FILE} is not valid JSON`], checked: 0 }\n }\n const problems: string[] = []\n if (lock.formatVersion !== 3)\n problems.push(`${LOCK_FILE} formatVersion ${String(lock.formatVersion)} is not 3`)\n let checked = 1\n if (lock.origin?.digest !== manifestDigest(readFileSync(manifestFile, 'utf8')))\n problems.push(\n `${MANIFEST} changed since the lock was written (its digest no longer matches): capture again`,\n )\n for (const module of lock.modules ?? []) {\n if (module.origin !== 'local') continue\n checked += 1\n if (module.source === undefined || !MODULE_SOURCE.test(module.source)) {\n problems.push(\n `${module.name}: the lock places it at ${String(module.source)}, which is not a plugin folder of the app`,\n )\n continue\n }\n const folder = join(dir, module.source)\n if (!existsSync(folder)) problems.push(`${module.name}: ${module.source} is missing`)\n else if (folderDigest(folder) !== module.digest)\n problems.push(\n `${module.name}: ${module.source} differs from the locked digest (edited after the capture)`,\n )\n }\n return { ok: problems.length === 0, problems, checked }\n}\n\n/**\n * The snapshot's `blend.yaml` with the app's own `metadata` (its id, name, version and visibility): a snapshot brings its composition, and the app\n * it is applied to stays the app it is. An app with no `blend.yaml` yet takes the snapshot's whole.\n */\nfunction keepIdentity(text: string, current: string | undefined): string {\n if (current === undefined) return text\n const own = parseDocument(current).get('metadata', true)\n if (own === undefined) return text\n const document = parseDocument(text)\n document.set('metadata', own)\n return String(document)\n}\n\n/**\n * `blend.yaml` with `names` on the `extensions` row's `off` list: the row starts every plugin folder that has no row of its own, and a folder the\n * snapshot does not have must stay where it is without starting. Without an `extensions` row no such folder starts, and the text is unchanged.\n */\nfunction keepOff(text: string, names: readonly string[]): string {\n if (names.length === 0) return text\n const document = parseDocument(text)\n const rows = document.getIn(['spec', 'rows'])\n if (!isSeq(rows)) return text\n const row = rows.items.find(\n (item) => (item as { get?: (key: string) => unknown }).get?.('name') === 'extensions',\n ) as { getIn(path: string[]): unknown; setIn(path: string[], value: unknown): void } | undefined\n if (row === undefined) return text\n const listed = row.getIn(['config', 'off']) as { toJSON?: () => unknown } | undefined\n const before = Array.isArray(listed?.toJSON?.()) ? (listed?.toJSON?.() as string[]) : []\n row.setIn(['config', 'off'], document.createNode([...new Set([...before, ...names])].sort()))\n return String(document)\n}\n\n/** Bring the snapshot in `from` into the app at `appRoot` (see the file's doc). Nothing is written unless the whole apply can go through. */\nexport function applySnapshot(from: string, appRoot: string): ApplyResult {\n const verified = verifyApp(from)\n const none = { modules: [], manifestChanged: false, extra: [] }\n if (!verified.ok) return { ok: false, problems: verified.problems, ...none }\n const lock = JSON.parse(readFileSync(join(from, LOCK_FILE), 'utf8')) as LockShape\n const modules: Array<{ name: string; status: ApplyStatus; detail?: string; source?: string }> = []\n for (const module of lock.modules ?? []) {\n if (module.origin !== 'local' || module.source === undefined) {\n modules.push({\n name: module.name,\n status: 'skipped',\n detail: `origin \"${module.origin}\" is not a plugin folder; add it yourself`,\n })\n continue\n }\n const target = join(appRoot, module.source)\n if (!existsSync(target))\n modules.push({ name: module.name, status: 'added', source: module.source })\n else if (folderDigest(target) === module.digest)\n modules.push({ name: module.name, status: 'unchanged' })\n else\n modules.push({\n name: module.name,\n status: 'conflict',\n detail: `${module.source} in the app differs from the snapshot's; move it away or capture the app first`,\n })\n }\n const conflicts = modules.filter((module) => module.status === 'conflict')\n const report = modules.map(({ source: _, ...module }) => module)\n if (conflicts.length > 0)\n return {\n ok: false,\n problems: conflicts.map((module) => `${module.name}: ${module.detail}`),\n modules: report,\n manifestChanged: false,\n extra: [],\n }\n for (const module of modules)\n if (module.status === 'added' && module.source !== undefined)\n cpSync(join(from, module.source), join(appRoot, module.source), {\n recursive: true,\n filter: (path) => !FOLDER_DIGEST_SKIPPED.has(basename(path)),\n })\n const locked = new Set((lock.modules ?? []).map((module) => module.name))\n const extra = appPluginNames(join(appRoot, 'plugins')).filter((name) => !locked.has(name))\n const current = existsSync(join(appRoot, MANIFEST))\n ? readFileSync(join(appRoot, MANIFEST), 'utf8')\n : undefined\n const manifest = keepOff(keepIdentity(readFileSync(join(from, MANIFEST), 'utf8'), current), extra)\n const manifestChanged = current !== manifest\n if (manifestChanged) writeAtomic(join(appRoot, MANIFEST), manifest)\n writeLock(appRoot)\n return { ok: true, problems: [], modules: report, manifestChanged, extra }\n}\n\nif (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {\n const appRoot = resolve(fileURLToPath(new URL('../..', import.meta.url)))\n const [verb, target] = process.argv.slice(2)\n if (verb === 'capture') {\n const { addedRows, modules } = captureApp(appRoot)\n console.log(\n `captured: ${modules} plugin folder(s) locked${addedRows.length > 0 ? `; rows added to blend.yaml: ${addedRows.join(', ')}` : ''}`,\n )\n } else if (verb === 'verify') {\n const result = verifyApp(resolve(target ?? appRoot))\n console.log(result.ok ? `ok: ${result.checked} checked` : result.problems.join('\\n'))\n process.exitCode = result.ok ? 0 : 1\n } else if (verb === 'apply' && target !== undefined) {\n const result = applySnapshot(resolve(target), appRoot)\n for (const module of result.modules)\n console.log(`${module.status}: ${module.name}${module.detail ? ` (${module.detail})` : ''}`)\n if (result.manifestChanged)\n console.log(\"blend.yaml: the snapshot's rows, under this app's own metadata\")\n if (result.extra.length > 0)\n console.log(`left in place, not in the snapshot: ${result.extra.join(', ')}`)\n if (!result.ok) console.error(`nothing applied:\\n${result.problems.join('\\n')}`)\n process.exitCode = result.ok ? 0 : 1\n } else {\n console.error(\n 'usage: node plugins/manifest/snapshot.ts capture | verify [dir] | apply <snapshot dir>',\n )\n process.exitCode = 2\n }\n}\n"],"mappings":"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"}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/** The file a plugin folder starts from, in the order they are looked for. */
|
|
2
|
+
export declare const PLUGIN_ENTRIES: readonly ["index.ts", "index.js", "index.mjs"];
|
|
3
|
+
/** The library copies a plugins folder holds (`library.json`, written by `acrylblends add`); absent or unreadable means none. */
|
|
4
|
+
export declare function libraryCopies(dir: string): ReadonlySet<string>;
|
|
5
|
+
/** The entry file of a plugin folder, or undefined when it has none. */
|
|
6
|
+
export declare function pluginEntry(dir: string): string | undefined;
|
|
7
|
+
/** The names of the app's own plugins in `dir` (the app's `plugins/`): folders with an entry file that are not library copies, sorted. */
|
|
8
|
+
export declare function appPluginNames(dir: string): string[];
|
|
9
|
+
/** A plugin module as a row mounts it. */
|
|
10
|
+
export interface AppPluginModule {
|
|
11
|
+
readonly name: string;
|
|
12
|
+
readonly apply: (...args: never[]) => unknown;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Import the app's own plugins `names` from `dir`, each checked to be a Cordis plugin whose `name` is its folder's.
|
|
16
|
+
* @throws an error that names the folder and the fix, for a folder that does not export a plugin.
|
|
17
|
+
*/
|
|
18
|
+
export declare function loadAppPlugins(dir: string, names: readonly string[]): Promise<Record<string, AppPluginModule>>;
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
import type { Context, Fiber } from '@deepseek-ai/cordis';
|
|
2
|
+
export declare const API_VERSION = "blends.acryl.dev/v1alpha1";
|
|
3
|
+
/** The file name ACRYL uses for an app definition. */
|
|
4
|
+
export declare const MANIFEST_FILE = "blend.yaml";
|
|
5
|
+
export type ParameterType = 'string' | 'number' | 'boolean';
|
|
6
|
+
export type ParameterValue = string | number | boolean;
|
|
7
|
+
export interface ParameterDeclaration {
|
|
8
|
+
readonly type: ParameterType;
|
|
9
|
+
readonly default: ParameterValue;
|
|
10
|
+
}
|
|
11
|
+
/** A row as written in `spec.rows`. */
|
|
12
|
+
export interface BlendRow {
|
|
13
|
+
readonly id: string;
|
|
14
|
+
readonly name: string;
|
|
15
|
+
readonly config?: Readonly<Record<string, unknown>>;
|
|
16
|
+
readonly disabled?: boolean;
|
|
17
|
+
}
|
|
18
|
+
/** A change to an inherited row, by id. What it sets wins; what it omits is inherited. */
|
|
19
|
+
export interface OverrideEntry {
|
|
20
|
+
readonly id: string;
|
|
21
|
+
readonly name?: string;
|
|
22
|
+
readonly config?: Readonly<Record<string, unknown>>;
|
|
23
|
+
readonly disabled?: boolean;
|
|
24
|
+
}
|
|
25
|
+
/** A row as the app mounts it: `use` is the registry entry the row's `name` selects. */
|
|
26
|
+
export interface Row {
|
|
27
|
+
readonly id: string;
|
|
28
|
+
readonly use: string;
|
|
29
|
+
readonly config?: Readonly<Record<string, unknown>>;
|
|
30
|
+
readonly disabled?: boolean;
|
|
31
|
+
}
|
|
32
|
+
export interface Metadata {
|
|
33
|
+
readonly id: string;
|
|
34
|
+
readonly name: string;
|
|
35
|
+
readonly version: string;
|
|
36
|
+
readonly category?: string;
|
|
37
|
+
readonly description?: string;
|
|
38
|
+
readonly license?: string;
|
|
39
|
+
/** Anything but an explicit `public` is private: `save` never pushes a private app to a public remote. */
|
|
40
|
+
readonly visibility?: 'private' | 'public';
|
|
41
|
+
}
|
|
42
|
+
/** Which Blueprint, at which version, a Blend was made from. */
|
|
43
|
+
export interface Lineage {
|
|
44
|
+
readonly blueprint: string;
|
|
45
|
+
readonly blueprintVersion: string;
|
|
46
|
+
}
|
|
47
|
+
export interface Manifest {
|
|
48
|
+
readonly apiVersion: typeof API_VERSION;
|
|
49
|
+
readonly kind: 'Blueprint' | 'Blend';
|
|
50
|
+
readonly metadata: Metadata;
|
|
51
|
+
readonly spec: {
|
|
52
|
+
readonly runtime: 'cordis';
|
|
53
|
+
readonly extends?: string;
|
|
54
|
+
readonly lineage?: Lineage;
|
|
55
|
+
readonly parameters?: Readonly<Record<string, ParameterDeclaration>>;
|
|
56
|
+
readonly rows?: readonly BlendRow[];
|
|
57
|
+
readonly overrides?: readonly OverrideEntry[];
|
|
58
|
+
};
|
|
59
|
+
}
|
|
60
|
+
export type DiagnosticCode = 'parse-error' | 'schema-error' | 'duplicate-row-id' | 'unknown-plugin' | 'dangling-parameter-reference' | 'unused-parameter' | 'parameter-type-mismatch' | 'parameter-override-unknown' | 'blend-without-lineage' | 'blueprint-with-lineage' | 'lineage-extends-mismatch' | 'overrides-without-parent' | 'parent-not-supplied' | 'parent-cycle' | 'override-unknown-id' | 'insert-id-collision';
|
|
61
|
+
/** Every problem names where it is, as a path into the document. */
|
|
62
|
+
export interface Diagnostic {
|
|
63
|
+
readonly code: DiagnosticCode;
|
|
64
|
+
readonly path: string;
|
|
65
|
+
readonly message: string;
|
|
66
|
+
}
|
|
67
|
+
export declare class ManifestError extends Error {
|
|
68
|
+
name: string;
|
|
69
|
+
readonly diagnostics: readonly Diagnostic[];
|
|
70
|
+
constructor(source: string, diagnostics: readonly Diagnostic[]);
|
|
71
|
+
}
|
|
72
|
+
export declare const DEFINITION_ID: RegExp;
|
|
73
|
+
export declare const SEMVER: RegExp;
|
|
74
|
+
/** The id of the definition a document resolves over: `extends`, else a Blend's lineage Blueprint. */
|
|
75
|
+
export declare function parentIdOf(document: Pick<Manifest, 'kind' | 'spec'>): string | undefined;
|
|
76
|
+
/**
|
|
77
|
+
* Validate one parsed document on its own (its parent is not read here; see `loadManifest`). An empty list means valid. `known` is
|
|
78
|
+
* the registry's names, so an unknown row `name` is reported here, before anything is mounted.
|
|
79
|
+
*/
|
|
80
|
+
export declare function validate(document: unknown, known?: Iterable<string>): Diagnostic[];
|
|
81
|
+
/** A manifest with its parameters resolved: every row's config has its tokens replaced, typed where a value is one whole token. */
|
|
82
|
+
export interface ResolvedManifest extends Manifest {
|
|
83
|
+
/** The rows to mount, in order: the parent's rows (with overrides applied), then this document's own. `use` selects the registry entry. */
|
|
84
|
+
readonly plugins: readonly Row[];
|
|
85
|
+
readonly values: Readonly<Record<string, ParameterValue>>;
|
|
86
|
+
/** sha256 of the manifest file's bytes. */
|
|
87
|
+
readonly digest: string;
|
|
88
|
+
}
|
|
89
|
+
export interface LoadOptions {
|
|
90
|
+
readonly known?: Iterable<string>;
|
|
91
|
+
/** Values for the parameters of this document. A parent always resolves with its own defaults. */
|
|
92
|
+
readonly values?: Readonly<Record<string, ParameterValue>>;
|
|
93
|
+
/** Where the parent Blueprint of a Blend lives: its file path by definition id, or undefined when it is not supplied. */
|
|
94
|
+
readonly getBlueprint?: (id: string) => string | undefined;
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Resolve one document over its parent chain. Every problem is a diagnostic; nothing throws for invalid input. Rules (ACRYL's): the
|
|
98
|
+
* parent is `extends`, else a Blend's lineage Blueprint; a parent resolves with its own defaults; an override must name a row the
|
|
99
|
+
* resolved parent has; an own row must not reuse a parent row's id; a cycle or a missing parent is reported.
|
|
100
|
+
*/
|
|
101
|
+
export declare function resolveRows(document: Manifest, options: Pick<LoadOptions, 'values' | 'getBlueprint'>, chain: readonly string[], diagnostics: Diagnostic[], where?: string): {
|
|
102
|
+
rows: Row[];
|
|
103
|
+
values: Record<string, ParameterValue>;
|
|
104
|
+
};
|
|
105
|
+
/**
|
|
106
|
+
* Read, validate and resolve a manifest. A Blend resolves over its Blueprint (`getBlueprint`). Throws a `ManifestError` with every
|
|
107
|
+
* diagnostic when anything is invalid.
|
|
108
|
+
*/
|
|
109
|
+
export declare function loadManifest(file: string, options?: LoadOptions): ResolvedManifest;
|
|
110
|
+
/** What an app can mount: a Cordis plugin per name. */
|
|
111
|
+
export type Registry = Readonly<Record<string, unknown>>;
|
|
112
|
+
/**
|
|
113
|
+
* Mount the manifest's enabled rows in order, each with its config merged under `overrides[id]` (runtime values such as the port win),
|
|
114
|
+
* awaiting each one, because a fiber still waiting on an injected service reports done too early. Returns the fibers, in order.
|
|
115
|
+
*/
|
|
116
|
+
export declare function compose(root: Context, manifest: Pick<ResolvedManifest, 'plugins'>, registry: Registry, overrides?: Readonly<Record<string, Readonly<Record<string, unknown>>>>): Promise<Fiber[]>;
|
|
117
|
+
/** The usual place for Blueprints: a folder with one `<definition id>.yaml` per Blueprint (for example `blueprints/acme.shop.yaml`). */
|
|
118
|
+
export declare function blueprintsIn(directory: string): (id: string) => string | undefined;
|
|
119
|
+
export { type AppPluginModule, appPluginNames, libraryCopies, loadAppPlugins, PLUGIN_ENTRIES, pluginEntry, } from './app-plugins.ts';
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
export interface CaptureResult {
|
|
2
|
+
/** The rows added to `blend.yaml`, one per plugin folder that had none. */
|
|
3
|
+
readonly addedRows: readonly string[];
|
|
4
|
+
/** How many plugin folders the lock records. */
|
|
5
|
+
readonly modules: number;
|
|
6
|
+
}
|
|
7
|
+
export interface VerifyResult {
|
|
8
|
+
readonly ok: boolean;
|
|
9
|
+
readonly problems: readonly string[];
|
|
10
|
+
/** The manifest digest and each plugin folder checked. */
|
|
11
|
+
readonly checked: number;
|
|
12
|
+
}
|
|
13
|
+
export type ApplyStatus = 'added' | 'unchanged' | 'conflict' | 'skipped';
|
|
14
|
+
export interface ApplyResult {
|
|
15
|
+
readonly ok: boolean;
|
|
16
|
+
/** Why nothing was applied: the snapshot does not match its lock, or a folder in the app differs from the locked one. */
|
|
17
|
+
readonly problems: readonly string[];
|
|
18
|
+
readonly modules: ReadonlyArray<{
|
|
19
|
+
readonly name: string;
|
|
20
|
+
readonly status: ApplyStatus;
|
|
21
|
+
readonly detail?: string;
|
|
22
|
+
}>;
|
|
23
|
+
readonly manifestChanged: boolean;
|
|
24
|
+
/** The app's own plugin folders the snapshot does not have: left in place, and put on the `extensions` row's `off` list so they do not start. */
|
|
25
|
+
readonly extra: readonly string[];
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Record the app as it runs: a row for every plugin folder of its own that has none (before the `extensions` row, else before the server, else
|
|
29
|
+
* last), then `blend.lock.json`. Idempotent: a second capture with nothing new changes nothing in `blend.yaml`.
|
|
30
|
+
*/
|
|
31
|
+
export declare function captureApp(appRoot: string): CaptureResult;
|
|
32
|
+
/** Check a snapshot (an app folder, or a copy of one) against its own `blend.lock.json`. */
|
|
33
|
+
export declare function verifyApp(dir: string): VerifyResult;
|
|
34
|
+
/** Bring the snapshot in `from` into the app at `appRoot` (see the file's doc). Nothing is written unless the whole apply can go through. */
|
|
35
|
+
export declare function applySnapshot(from: string, appRoot: string): ApplyResult;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function runUpgrade(argv: readonly string[], appRoot: string, out?: (text: string) => void): number;
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { type RowChange, type UpgradePlan } from '@acryldev/blends-core';
|
|
2
|
+
import type { LoadOptions } from './index.ts';
|
|
3
|
+
export type { RowChange, UpgradePlan };
|
|
4
|
+
/**
|
|
5
|
+
* Plan the upgrade of the Blend in `blendFile` from the Blueprint file it was made from (`oldBlueprint`) to a newer one
|
|
6
|
+
* (`newBlueprint`). `getBlueprint` finds the parents of either Blueprint, if they have any. Throws for input that cannot be read
|
|
7
|
+
* as a plan: a Blueprint file with the wrong id, an old Blueprint whose version is not the Blend's lineage version, or a document
|
|
8
|
+
* that is not a Blend. Everything the upgrade would break is in the plan.
|
|
9
|
+
*/
|
|
10
|
+
export declare function planUpgrade(options: {
|
|
11
|
+
blendFile: string;
|
|
12
|
+
oldBlueprint: string;
|
|
13
|
+
newBlueprint: string;
|
|
14
|
+
getBlueprint?: LoadOptions['getBlueprint'];
|
|
15
|
+
values?: LoadOptions['values'];
|
|
16
|
+
}): UpgradePlan;
|
|
17
|
+
/** Move the Blend's lineage to the plan's new version, keeping the file's comments and layout. Refuses an unsafe plan. */
|
|
18
|
+
export declare function applyUpgrade(blendFile: string, plan: UpgradePlan): void;
|
|
19
|
+
/** A short, readable account of a plan, for a terminal. */
|
|
20
|
+
export declare function describePlan(plan: UpgradePlan): string;
|