@wendoo/bridge-app 0.2.2

package/dist/compilation.js

@@ -0,0 +1,404 @@
+import { fileContentEquals } from "@wendoo/app-host";
+import { createWorkspaceCompiler, } from "@wendoo/ts-compiler";
+import { createAppBridge } from "./app-bridge.js";
+function buildFeatureStatus(file, diagnostics) {
+    let errorCount = 0;
+    let warningCount = 0;
+    for (const diagnostic of diagnostics) {
+        if (diagnostic.severity === "error") {
+            errorCount++;
+        }
+        else if (diagnostic.severity === "warning") {
+            warningCount++;
+        }
+    }
+    return {
+        file,
+        success: errorCount === 0,
+        diagnosticCount: {
+            error: errorCount,
+            warning: warningCount,
+        },
+    };
+}
+/**
+ * Build an {@link AppBridgeFeature} that compiles project files on remote
+ * changes and publishes diagnostics (and, by default, per-file status) to the
+ * peer.
+ */
+export function createCompilationFeature(options) {
+    return {
+        attach(context) {
+            let lastSnapshot;
+            const previousDiagnosticFiles = new Set();
+            const publishStatus = options.publishStatus ?? true;
+            const publishSnapshot = (snapshot) => {
+                if (context.snapshot().status !== "connected") {
+                    return;
+                }
+                const currentFiles = new Set();
+                for (const [file, diagnostics] of snapshot.files) {
+                    currentFiles.add(file);
+                    if (diagnostics.length > 0 || previousDiagnosticFiles.has(file)) {
+                        context.publishDiagnostics(file, diagnostics);
+                        if (publishStatus) {
+                            context.publishStatus(buildFeatureStatus(file, diagnostics));
+                        }
+                    }
+                }
+                for (const file of previousDiagnosticFiles) {
+                    if (!currentFiles.has(file)) {
+                        context.publishDiagnostics(file, []);
+                        if (publishStatus) {
+                            context.publishStatus(buildFeatureStatus(file, []));
+                        }
+                    }
+                }
+                previousDiagnosticFiles.clear();
+                for (const [file, diagnostics] of snapshot.files) {
+                    if (diagnostics.length > 0) {
+                        previousDiagnosticFiles.add(file);
+                    }
+                }
+            };
+            const compileAndPublish = () => {
+                const snapshot = options.compiler.compile();
+                if (lastSnapshot !== snapshot) {
+                    lastSnapshot = snapshot;
+                    publishSnapshot(snapshot);
+                }
+            };
+            const compileUnsub = options.compiler.onDidCompile((snapshot) => {
+                lastSnapshot = snapshot;
+                publishSnapshot(snapshot);
+            });
+            options.compiler.replaceProjectFiles(context.projectFileSnapshot());
+            compileAndPublish();
+            const remoteChangeUnsub = context.onRemoteChange((change) => {
+                options.compiler.applyProjectFileChange(change);
+                compileAndPublish();
+            });
+            const syncUnsub = context.onDidSync(() => {
+                if (lastSnapshot) {
+                    publishSnapshot(lastSnapshot);
+                }
+            });
+            return () => {
+                syncUnsub();
+                remoteChangeUnsub();
+                compileUnsub();
+            };
+        },
+    };
+}
+/**
+ * Drives a {@link CompilationProvider} from incoming filesystem notifications
+ * and emits diagnostics to the peer. Sends version-tagged `compile:diagnostics`
+ * and `compile:status` messages when connected.
+ */
+export class CompilationManager {
+    _provider;
+    _send;
+    _isConnected;
+    _versions = new Map();
+    _previousFiles = new Set();
+    _compilationListeners = new Set();
+    _lastResult;
+    _removalListeners = new Set();
+    constructor(provider, send, isConnected) {
+        this._provider = provider;
+        this._send = send;
+        this._isConnected = isConnected;
+    }
+    handleFileChange(ev) {
+        switch (ev.action) {
+            case "write":
+                this._provider.fileWritten(ev.path, ev.content);
+                break;
+            case "delete":
+                this._provider.fileDeleted(ev.path);
+                break;
+            case "rename":
+                this._provider.fileRenamed(ev.oldPath, ev.newPath);
+                break;
+            case "import":
+                this._provider.fullSync(ev.entries);
+                break;
+            case "mkdir":
+            case "rmdir":
+                return;
+        }
+        this.compileAndEmit();
+    }
+    onCompilation(fn) {
+        this._compilationListeners.add(fn);
+        return () => {
+            this._compilationListeners.delete(fn);
+        };
+    }
+    onRemoval(fn) {
+        this._removalListeners.add(fn);
+        return () => {
+            this._removalListeners.delete(fn);
+        };
+    }
+    sendDiagnostics() {
+        if (!this._lastResult || !this._isConnected())
+            return;
+        for (const [file, diagnostics] of this._lastResult.files) {
+            if (diagnostics.length > 0) {
+                this.emitDiagnostics(file, diagnostics);
+            }
+        }
+    }
+    compileAndEmit() {
+        const result = this._provider.compileAll();
+        this._lastResult = result;
+        for (const fn of this._compilationListeners) {
+            fn(result);
+        }
+        if (!this._isConnected())
+            return;
+        const currentFiles = new Set();
+        for (const [file, diagnostics] of result.files) {
+            currentFiles.add(file);
+            if (diagnostics.length > 0 || this._previousFiles.has(file)) {
+                this.emitDiagnostics(file, diagnostics);
+            }
+        }
+        for (const file of this._previousFiles) {
+            if (!currentFiles.has(file)) {
+                this.emitDiagnostics(file, []);
+                for (const fn of this._removalListeners) {
+                    fn(file);
+                }
+            }
+        }
+        this._previousFiles.clear();
+        for (const [file, diagnostics] of result.files) {
+            if (diagnostics.length > 0) {
+                this._previousFiles.add(file);
+            }
+        }
+    }
+    emitDiagnostics(file, diagnostics) {
+        const version = (this._versions.get(file) ?? 0) + 1;
+        this._versions.set(file, version);
+        this._send({
+            type: "compile:diagnostics",
+            payload: { file, version, diagnostics },
+        });
+        let errorCount = 0;
+        let warningCount = 0;
+        for (const d of diagnostics) {
+            if (d.severity === "error")
+                errorCount++;
+            else if (d.severity === "warning")
+                warningCount++;
+        }
+        this._send({
+            type: "compile:status",
+            payload: {
+                file,
+                success: errorCount === 0,
+                diagnosticCount: { error: errorCount, warning: warningCount },
+            },
+        });
+    }
+}
+/** Wrap a {@link ProjectFileSystem} as a TS workspace compiler over the live project files. */
+export function createProjectCompiler(options) {
+    const { mounts, environment, filesystem, projectNamespace, dependencies, dependencyMounts } = options;
+    const compiler = createWorkspaceCompiler({
+        projectNamespace,
+        mounts,
+        environment,
+        dependencies,
+        dependencyMounts,
+    });
+    if (options.onDidCompile) {
+        compiler.onDidCompile(options.onDidCompile);
+    }
+    return {
+        compiler,
+        initialize() {
+            compiler.replaceWorkspace(filesystem.exportSnapshot());
+            compiler.compile();
+        },
+        replaceProjectFiles() {
+            compiler.replaceWorkspace(filesystem.exportSnapshot());
+            compiler.compile();
+        },
+    };
+}
+/**
+ * Wire up an {@link AppBridge} that uses `projectCompiler` for diagnostics and
+ * surfaces compiler-controlled files to the remote peer.
+ */
+export function createBridgeProject(options) {
+    const { projectCompiler, servedFileSystem } = options;
+    const compiler = projectCompiler.compiler;
+    let latestBindingToken = options.bindingToken;
+    const onBindingTokenChange = (token) => {
+        latestBindingToken = token;
+        options.onBindingTokenChange?.(token);
+    };
+    let currentBridge = buildBridge({
+        bridgeUrl: options.bridgeUrl,
+        filesystem: servedFileSystem,
+        bindingToken: latestBindingToken,
+        onBindingTokenChange,
+    }, compiler);
+    return {
+        get bridge() {
+            return currentBridge;
+        },
+        recreateBridge(bridgeUrl) {
+            currentBridge.stop();
+            currentBridge = buildBridge({ bridgeUrl, filesystem: servedFileSystem, bindingToken: latestBindingToken, onBindingTokenChange }, compiler);
+        },
+    };
+}
+/** The directory portion of `path` (empty for a root-level path). */
+function parentDirectory(path) {
+    const idx = path.lastIndexOf("/");
+    return idx <= 0 ? "" : path.slice(0, idx);
+}
+/**
+ * Ensure `dirPath` and each of its ancestors are present in `snapshot` as
+ * directory entries, adding any that are missing shallowest-first. An empty
+ * `dirPath` (a root-level path's parent) adds nothing.
+ */
+function ensureSnapshotDirectory(snapshot, dirPath) {
+    const segments = dirPath.split("/").filter((segment) => segment.length > 0);
+    for (let i = 1; i <= segments.length; i++) {
+        const ancestor = segments.slice(0, i).join("/");
+        if (!snapshot.has(ancestor)) {
+            snapshot.set(ancestor, { kind: "directory" });
+        }
+    }
+}
+/** True when the two compiler-controlled file maps carry a different set of paths or content. */
+function compilerControlledFilesChanged(previous, current) {
+    if (previous.size !== current.size) {
+        return true;
+    }
+    for (const [path, content] of current) {
+        const before = previous.get(path);
+        if (before === undefined || !fileContentEquals(before, content)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Wrap a {@link ProjectFileSystem} so its exported snapshot also carries the
+ * compiler-controlled files (ambient declarations, `tsconfig.json`, and the
+ * read-only installed-extensions tree), all marked read-only. Local and remote
+ * changes targeting those augmented paths are filtered out, leaving them
+ * read-only from the peer's side.
+ *
+ * When a compile changes the compiler-controlled file set (installing or
+ * uninstalling an extension adds or removes its `.libraries/` subtree), the
+ * wrapper emits one full-snapshot `import` local change and invokes the
+ * options' change callback with the new set. The peer reconciles the whole
+ * tree from the import: newly installed paths appear and uninstalled paths
+ * are pruned. The read-only compiler-controlled paths cannot be updated by an
+ * incremental write/delete notification, so the full-snapshot import is their
+ * propagation channel.
+ */
+export function augmentProjectFileSystem(filesystem, compiler, options) {
+    const isAugmentedPath = (path) => compiler.getCompilerControlledFiles().has(path);
+    const filterChange = (change) => {
+        switch (change.action) {
+            case "write":
+            case "delete":
+            case "mkdir":
+            case "rmdir":
+                return isAugmentedPath(change.path) ? undefined : change;
+            case "rename":
+                return isAugmentedPath(change.oldPath) || isAugmentedPath(change.newPath) ? undefined : change;
+            case "import":
+                return { action: "import", entries: change.entries.filter(([path]) => !isAugmentedPath(path)) };
+        }
+    };
+    const buildSnapshot = () => {
+        const snapshot = filesystem.exportSnapshot();
+        const controlledFiles = compiler.getCompilerControlledFiles();
+        for (const [path, content] of controlledFiles) {
+            ensureSnapshotDirectory(snapshot, parentDirectory(path));
+            snapshot.set(path, { kind: "file", content, etag: "compiler-controlled", isReadonly: true });
+        }
+        return snapshot;
+    };
+    const localChangeListeners = new Set();
+    let previousControlledFiles = new Map(compiler.getCompilerControlledFiles());
+    compiler.onDidCompile(() => {
+        const currentControlledFiles = compiler.getCompilerControlledFiles();
+        if (!compilerControlledFilesChanged(previousControlledFiles, currentControlledFiles)) {
+            return;
+        }
+        previousControlledFiles = new Map(currentControlledFiles);
+        options?.onCompilerControlledFilesChanged?.(currentControlledFiles);
+        const change = { action: "import", entries: [...buildSnapshot()] };
+        for (const listener of localChangeListeners) {
+            listener(change);
+        }
+    });
+    return {
+        exportSnapshot() {
+            return buildSnapshot();
+        },
+        applyRemoteChange(change) {
+            const filtered = filterChange(change);
+            if (filtered) {
+                filesystem.applyRemoteChange(filtered);
+            }
+        },
+        applyLocalChange(change) {
+            const filtered = filterChange(change);
+            if (filtered) {
+                filesystem.applyLocalChange(filtered);
+            }
+        },
+        onLocalChange(listener) {
+            localChangeListeners.add(listener);
+            const unsubscribeUnderlying = filesystem.onLocalChange(listener);
+            return () => {
+                localChangeListeners.delete(listener);
+                unsubscribeUnderlying();
+            };
+        },
+        onAnyChange(listener) {
+            return filesystem.onAnyChange(listener);
+        },
+        flush() {
+            filesystem.flush();
+        },
+    };
+}
+function buildBridge(options, compiler) {
+    return createAppBridge({
+        bridgeUrl: options.bridgeUrl,
+        filesystem: options.filesystem,
+        features: [createCompilationFeature({ compiler: createProjectFileCompilerAdapter(compiler) })],
+        bindingToken: options.bindingToken,
+        onBindingTokenChange: options.onBindingTokenChange,
+    });
+}
+function createProjectFileCompilerAdapter(compiler) {
+    return {
+        replaceProjectFiles(snapshot) {
+            compiler.replaceWorkspace(snapshot);
+        },
+        applyProjectFileChange(change) {
+            compiler.applyWorkspaceChange(change);
+        },
+        compile() {
+            return compiler.compile();
+        },
+        onDidCompile(listener) {
+            return compiler.onDidCompile((result) => listener(result));
+        },
+    };
+}

package/dist/core-extension.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The core layer's `<owner>/<repo>` coordinate: its identity, its compiler
+ * namespace, and the name it is imported and stored under
+ * (`@lib/wendoo-lang/lib-core`). The single shared language base at the bottom of
+ * every Wendoo platform's stack.
+ */
+export declare const CORE_LIB_COORDINATE = "wendoo-lang/lib-core";
+/** Manifest reference form delivering the core layer from a host application's embed record. */
+export declare const CORE_LIB_REFERENCE = "embedded:wendoo-lang/lib-core";
+//# sourceMappingURL=core-extension.d.ts.map

package/dist/core-extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-extension.d.ts","sourceRoot":"","sources":["../src/core-extension.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAE1D,gGAAgG;AAChG,eAAO,MAAM,kBAAkB,kCAAkC,CAAC"}

package/dist/core-extension.js

@@ -0,0 +1,9 @@
+/**
+ * The core layer's `<owner>/<repo>` coordinate: its identity, its compiler
+ * namespace, and the name it is imported and stored under
+ * (`@lib/wendoo-lang/lib-core`). The single shared language base at the bottom of
+ * every Wendoo platform's stack.
+ */
+export const CORE_LIB_COORDINATE = "wendoo-lang/lib-core";
+/** Manifest reference form delivering the core layer from a host application's embed record. */
+export const CORE_LIB_REFERENCE = "embedded:wendoo-lang/lib-core";

package/dist/embedded-extension-id-gate.d.ts

@@ -0,0 +1,38 @@
+import type { BrainServices } from "@wendoo/core/brain";
+import type { EmbeddedExtension } from "./embedded-extensions.js";
+/**
+ * A declaration in a repo-embedded extension that ships without an explicit
+ * stable `id`. Read-only extension source is regenerated on load, so the
+ * compiler cannot mint and persist an id for it; the id must be present in the
+ * bundled source.
+ */
+export interface EmbeddedExtensionIdViolation {
+    /** The `<owner>/<repo>` coordinate of the extension whose source is missing an id. */
+    coordinate: string;
+    /** The extension-relative path of the file declaring the id-less tile. */
+    path: string;
+    /** The compiler's diagnostic message, naming the declaration kind and name. */
+    message: string;
+}
+/**
+ * Compile every extension in `embedRecord` as read-only roots and collect each
+ * declared Sensor, Actuator, or Conversion that ships without an explicit
+ * stable `id`. Systems carry no explicit id (their identity is structural) and
+ * are never reported. Returns an empty array when every declaration carries an
+ * id.
+ *
+ * The compile mirrors how a consuming project mounts these extensions: each
+ * origin's transitive closure is resolved from the record, and every origin is
+ * compiled under its own coordinate namespace into `services`. Supply a
+ * `services` built with the app's modules so the ambient the extensions compile
+ * against matches the app's platform.
+ */
+export declare function findEmbeddedExtensionsMissingStableIds(embedRecord: readonly EmbeddedExtension[], services: BrainServices): EmbeddedExtensionIdViolation[];
+/**
+ * Render {@link EmbeddedExtensionIdViolation}s as an author-facing failure
+ * message that names each offending extension coordinate and file and states
+ * how to obtain a stable id. Use it as the assertion message of a build gate
+ * over an app's embedded extensions.
+ */
+export declare function formatEmbeddedExtensionIdViolations(violations: readonly EmbeddedExtensionIdViolation[]): string;
+//# sourceMappingURL=embedded-extension-id-gate.d.ts.map

package/dist/embedded-extension-id-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedded-extension-id-gate.d.ts","sourceRoot":"","sources":["../src/embedded-extension-id-gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAGlE;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B;IAC3C,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sCAAsC,CACpD,WAAW,EAAE,SAAS,iBAAiB,EAAE,EACzC,QAAQ,EAAE,aAAa,GACtB,4BAA4B,EAAE,CA4BhC;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CAAC,UAAU,EAAE,SAAS,4BAA4B,EAAE,GAAG,MAAM,CAQ/G"}

package/dist/embedded-extension-id-gate.js

@@ -0,0 +1,55 @@
+import { CompileDiagCode, MultiRootSession } from "@wendoo/ts-compiler";
+import { resolveProjectExtensions } from "./embedded-extensions.js";
+/**
+ * Compile every extension in `embedRecord` as read-only roots and collect each
+ * declared Sensor, Actuator, or Conversion that ships without an explicit
+ * stable `id`. Systems carry no explicit id (their identity is structural) and
+ * are never reported. Returns an empty array when every declaration carries an
+ * id.
+ *
+ * The compile mirrors how a consuming project mounts these extensions: each
+ * origin's transitive closure is resolved from the record, and every origin is
+ * compiled under its own coordinate namespace into `services`. Supply a
+ * `services` built with the app's modules so the ambient the extensions compile
+ * against matches the app's platform.
+ */
+export function findEmbeddedExtensionsMissingStableIds(embedRecord, services) {
+    const references = {};
+    for (const extension of embedRecord) {
+        references[extension.canonicalOrigin] = `embedded:${extension.canonicalOrigin}`;
+    }
+    const { dependencyMounts } = resolveProjectExtensions(references, { embedded: embedRecord });
+    const roots = dependencyMounts.map((mount) => ({
+        namespace: mount.namespace,
+        files: mount.files,
+        dependencies: mount.dependencies,
+        readOnlySource: true,
+    }));
+    const session = new MultiRootSession({ services });
+    session.setRoots(roots);
+    const { roots: results } = session.compile();
+    const violations = [];
+    for (const [coordinate, result] of results) {
+        for (const [path, compileResult] of result.results) {
+            for (const diagnostic of compileResult.diagnostics) {
+                if (diagnostic.code === CompileDiagCode.ExtensionDeclarationMissingId) {
+                    violations.push({ coordinate, path, message: diagnostic.message });
+                }
+            }
+        }
+    }
+    return violations;
+}
+/**
+ * Render {@link EmbeddedExtensionIdViolation}s as an author-facing failure
+ * message that names each offending extension coordinate and file and states
+ * how to obtain a stable id. Use it as the assertion message of a build gate
+ * over an app's embedded extensions.
+ */
+export function formatEmbeddedExtensionIdViolations(violations) {
+    const lines = violations.map((v) => `  ${v.coordinate} (${v.path}): ${v.message}`);
+    return ("Repo-embedded extension(s) ship a declaration without an explicit stable id:\n" +
+        `${lines.join("\n")}\n` +
+        "To obtain an id, compile the extension as a writable project to mint one, " +
+        "then set that id explicitly in the declaration's source.");
+}

package/dist/embedded-extension-loader.d.ts

@@ -0,0 +1,33 @@
+import type { EmbeddedExtension } from "./embedded-extensions.js";
+/**
+ * Return the declared `files` entries an extension names but that do not exist on
+ * disk, resolved relative to the extension's manifest directory. An empty result
+ * means every listed file is present. Files present on disk but absent from the
+ * list are valid content exclusions and are never reported: this checks only the
+ * error direction, a listed file the build cannot assemble.
+ *
+ * @param dir - Directory holding the extension's `wendoo.json`.
+ */
+export declare function findMissingExtensionFiles(dir: string): readonly string[];
+/**
+ * Absolute paths of every on-disk file that backs an embedded extension: its
+ * `wendoo.json` plus each file its `files` list names. A build-time provider
+ * watches these so editing extension source refreshes the assembled bundle.
+ *
+ * @param dir - Directory holding the extension's `wendoo.json`.
+ */
+export declare function extensionSourceFiles(dir: string): readonly string[];
+/**
+ * Assemble an embedded extension by reading its `wendoo.json` from `dir`,
+ * loading exactly the files its `files` list names, and returning the bundle
+ * keyed by `canonicalOrigin`. The manifest is included at the extension root as
+ * `wendoo.json` and is never listed by `files`. Each listed entry is resolved
+ * relative to `dir` and bundled at its extension-relative path.
+ *
+ * @param dir - Directory holding the extension's `wendoo.json`.
+ * @param canonicalOrigin - The `<owner>/<repo>` coordinate the bundle is keyed under.
+ * @throws {Error} when the manifest is missing, invalid, declares neither
+ *   `files` nor a `hostApp` bundle, or names a file absent from disk.
+ */
+export declare function buildEmbeddedExtensionFromDir(dir: string, canonicalOrigin: string): EmbeddedExtension;
+//# sourceMappingURL=embedded-extension-loader.d.ts.map

package/dist/embedded-extension-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedded-extension-loader.d.ts","sourceRoot":"","sources":["../src/embedded-extension-loader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAyB,MAAM,0BAA0B,CAAC;AA8CzF;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAGxE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAGnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,iBAAiB,CAiBrG"}

package/dist/embedded-extension-loader.js

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename, relative, resolve, sep } from "node:path";
+import { parseProjectContentManifest, WENDOO_JSON_PATH } from "@wendoo/app-host";
+import { findMissingListedFiles } from "./manifest-files.js";
+/**
+ * Map a manifest `files` entry to the extension-relative path it occupies in the
+ * assembled bundle. An entry that stays within the extension directory keeps its
+ * directory-relative path; an entry the manifest pulls in from outside that
+ * directory (a generated artifact reached through `..`) is placed at the
+ * extension root under its base name.
+ */
+function bundlePathFor(dir, entry) {
+    const rel = relative(dir, resolve(dir, entry));
+    return rel.startsWith("..") ? basename(entry) : rel.split(sep).join("/");
+}
+/**
+ * Read and parse the `files` list an extension declares in its own
+ * `wendoo.json`. An extension must declare content `files` or a `hostApp`
+ * bundle: a library names its content files, and a target (a `hostApp`) carries
+ * no library content, so it resolves to an empty file list. A manifest that
+ * declares neither is rejected.
+ */
+function readManifestFiles(dir) {
+    const manifestPath = resolve(dir, WENDOO_JSON_PATH);
+    if (!existsSync(manifestPath)) {
+        throw new Error(`Embedded extension at ${dir} has no ${WENDOO_JSON_PATH}.`);
+    }
+    const manifestText = readFileSync(manifestPath, "utf8");
+    const parsed = parseProjectContentManifest(manifestText);
+    if (!parsed.ok) {
+        throw new Error(`Embedded extension manifest at ${manifestPath} is invalid: ` +
+            parsed.errors.map((e) => `${e.path} ${e.message}`).join("; "));
+    }
+    if (parsed.manifest.files === undefined) {
+        if (parsed.manifest.hostApp !== undefined) {
+            return { manifestText, files: [] };
+        }
+        throw new Error(`Embedded extension manifest at ${manifestPath} must declare a "files" list naming its content, or a "hostApp" bundle.`);
+    }
+    return { manifestText, files: parsed.manifest.files };
+}
+/**
+ * Return the declared `files` entries an extension names but that do not exist on
+ * disk, resolved relative to the extension's manifest directory. An empty result
+ * means every listed file is present. Files present on disk but absent from the
+ * list are valid content exclusions and are never reported: this checks only the
+ * error direction, a listed file the build cannot assemble.
+ *
+ * @param dir - Directory holding the extension's `wendoo.json`.
+ */
+export function findMissingExtensionFiles(dir) {
+    const { files } = readManifestFiles(dir);
+    return findMissingListedFiles(files, (entry) => existsSync(resolve(dir, entry)));
+}
+/**
+ * Absolute paths of every on-disk file that backs an embedded extension: its
+ * `wendoo.json` plus each file its `files` list names. A build-time provider
+ * watches these so editing extension source refreshes the assembled bundle.
+ *
+ * @param dir - Directory holding the extension's `wendoo.json`.
+ */
+export function extensionSourceFiles(dir) {
+    const { files } = readManifestFiles(dir);
+    return [resolve(dir, WENDOO_JSON_PATH), ...files.map((entry) => resolve(dir, entry))];
+}
+/**
+ * Assemble an embedded extension by reading its `wendoo.json` from `dir`,
+ * loading exactly the files its `files` list names, and returning the bundle
+ * keyed by `canonicalOrigin`. The manifest is included at the extension root as
+ * `wendoo.json` and is never listed by `files`. Each listed entry is resolved
+ * relative to `dir` and bundled at its extension-relative path.
+ *
+ * @param dir - Directory holding the extension's `wendoo.json`.
+ * @param canonicalOrigin - The `<owner>/<repo>` coordinate the bundle is keyed under.
+ * @throws {Error} when the manifest is missing, invalid, declares neither
+ *   `files` nor a `hostApp` bundle, or names a file absent from disk.
+ */
+export function buildEmbeddedExtensionFromDir(dir, canonicalOrigin) {
+    const { manifestText, files: declared } = readManifestFiles(dir);
+    const missing = findMissingExtensionFiles(dir);
+    if (missing.length > 0) {
+        throw new Error(`Embedded extension "${canonicalOrigin}" at ${dir} declares files absent from disk: ${missing.join(", ")}.`);
+    }
+    const files = declared.map((entry) => ({
+        path: bundlePathFor(dir, entry),
+        content: readFileSync(resolve(dir, entry), "utf8"),
+    }));
+    files.push({ path: WENDOO_JSON_PATH, content: manifestText });
+    return { canonicalOrigin, files };
+}