@telorun/kernel 0.10.0 → 0.11.0

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { ControllerLoader } from "./controller-loader.js";
 export { ControllerRegistry } from "./controller-registry.js";
 export { EvaluationContext } from "./evaluation-context.js";
 export { LocalFileSource } from "./manifest-sources/local-file-source.js";
+export { LocalManifestCacheSource, cachePathForCanonical, resolveEntryDir, writeManifestCache, } from "./manifest-sources/local-manifest-cache-source.js";
 export { MemorySource } from "./manifest-sources/memory-source.js";
 export { EventStream } from "./event-stream.js";
 export { ExecutionContext } from "./execution-context.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,gBAAgB,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC1E,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,GACnB,MAAM,mDAAmD,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,gBAAgB,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -2,6 +2,7 @@ export { ControllerLoader } from "./controller-loader.js";
 export { ControllerRegistry } from "./controller-registry.js";
 export { EvaluationContext } from "./evaluation-context.js";
 export { LocalFileSource } from "./manifest-sources/local-file-source.js";
+export { LocalManifestCacheSource, cachePathForCanonical, resolveEntryDir, writeManifestCache, } from "./manifest-sources/local-manifest-cache-source.js";
 export { MemorySource } from "./manifest-sources/memory-source.js";
 export { EventStream } from "./event-stream.js";
 export { ExecutionContext } from "./execution-context.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAsB,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,gBAAgB,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC1E,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,GACnB,MAAM,mDAAmD,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAsB,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,gBAAgB,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/manifest-sources/local-manifest-cache-source.d.ts

@@ -0,0 +1,50 @@
+import type { LoadedGraph, ManifestSource } from "@telorun/analyzer";
+/**
+ * Reads previously-cached manifest YAMLs from `<entry-dir>/.telo/manifests/`.
+ * Sits ahead of `RegistrySource` / `HttpSource` in the source chain — a hit
+ * makes boot hermetic, a miss falls through to the network source unchanged.
+ *
+ * Populated by `writeManifestCache` at install time.
+ */
+export declare class LocalManifestCacheSource implements ManifestSource {
+    private readonly cacheRoot;
+    private readonly registryUrl;
+    constructor(entryDir: string, registryUrl?: string);
+    supports(url: string): boolean;
+    read(url: string): Promise<{
+        text: string;
+        source: string;
+    }>;
+    resolveRelative(base: string, relative: string): string;
+    private tryMap;
+}
+/**
+ * Map a graph's canonical `source` URL to the on-disk cache file path it
+ * should be written to (writer side). Returns `null` for sources that do
+ * not need caching — file:// (already on disk), memory:// (transient), or
+ * any path that would escape the cache root.
+ *
+ * Uses the same mapping function as `LocalManifestCacheSource`, so the
+ * writer and reader always agree on where every URL lives.
+ */
+export declare function cachePathForCanonical(canonicalSource: string, entryDir: string, registryUrl: string): string | null;
+/**
+ * Persist every manifest file reachable from `graph` (owners + partials) to
+ * `<entryDir>/.telo/manifests/`, except the entry manifest itself and any
+ * file:// or memory:// sources (already on disk or transient).
+ *
+ * Idempotent: rewrites any existing file with the freshly fetched bytes so
+ * a partial re-install converges. Never deletes entries — stale versions
+ * stay until `.telo/manifests/` is removed by hand, matching the
+ * `.telo/npm/` convention.
+ *
+ * Returns the list of paths written, for diagnostics.
+ */
+export declare function writeManifestCache(graph: LoadedGraph, entryDir: string, registryUrl?: string): Promise<string[]>;
+/** Resolve the entry-anchor directory for the manifest cache.
+ *
+ * For a file path or `file://` URL: returns the containing directory.
+ * For a directory path: returns the directory itself.
+ * For an HTTP(S) URL: returns `null` (no local anchor; cache writes skipped). */
+export declare function resolveEntryDir(entryPath: string): string | null;
+//# sourceMappingURL=local-manifest-cache-source.d.ts.map

package/dist/manifest-sources/local-manifest-cache-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-manifest-cache-source.d.ts","sourceRoot":"","sources":["../../src/manifest-sources/local-manifest-cache-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AA4HrE;;;;;;GAMG;AACH,qBAAa,wBAAyB,YAAW,cAAc;IAC7D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,QAAQ,EAAE,MAAM,EAAE,WAAW,GAAE,MAA6B;IAKxE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIxB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAWlE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IASvD,OAAO,CAAC,MAAM;CAYf;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CAGf;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,MAAM,EAChB,WAAW,GAAE,MAA6B,GACzC,OAAO,CAAC,MAAM,EAAE,CAAC,CAoBnB;AAED;;;;iFAIiF;AACjF,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgBhE"}

package/dist/manifest-sources/local-manifest-cache-source.js

@@ -0,0 +1,227 @@
+import { createHash } from "crypto";
+import { statSync } from "fs";
+import * as fs from "fs/promises";
+import * as path from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+const CACHE_SUBDIR = ".telo/manifests";
+const HTTP_NAMESPACE = "__http";
+const DEFAULT_MANIFEST_FILENAME = "telo.yaml";
+const DEFAULT_REGISTRY_URL = "https://registry.telo.run";
+const QUERY_HASH_LENGTH = 12;
+/** Verify that `candidate` resolves to a path under `root`. Returns the
+ *  candidate path on success, `null` when any segment escapes the root.
+ *  Guards against `..` segments inside module refs or HTTP pathnames. */
+function joinUnder(root, ...segments) {
+    if (segments.some((s) => s === ""))
+        return null;
+    const candidate = path.join(root, ...segments);
+    const resolved = path.resolve(candidate);
+    const resolvedRoot = path.resolve(root);
+    if (resolved !== resolvedRoot && !resolved.startsWith(resolvedRoot + path.sep)) {
+        return null;
+    }
+    return candidate;
+}
+/** Mirror `HttpSource.read`'s `fetchUrl` derivation: when the URL does not
+ *  already point at a YAML file, append `/telo.yaml`. Used by both the
+ *  reader and writer so a raw import URL and the canonical source it
+ *  resolves to map to the same cache path. */
+function normalizePathname(url, parsed) {
+    let pathname = parsed.pathname;
+    if (!url.includes(".yaml")) {
+        pathname = pathname.endsWith("/")
+            ? `${pathname}${DEFAULT_MANIFEST_FILENAME}`
+            : `${pathname}/${DEFAULT_MANIFEST_FILENAME}`;
+    }
+    return pathname;
+}
+/** Compute a short hash of `search + hash` so two URLs that differ only in
+ *  query / fragment do not collide at the same cache path. Inserted before
+ *  the final extension so the filename stays readable. */
+function disambiguatePath(pathname, search, hash) {
+    if (!search && !hash)
+        return pathname;
+    const digest = createHash("sha256")
+        .update(search + hash)
+        .digest("hex")
+        .slice(0, QUERY_HASH_LENGTH);
+    const ext = path.extname(pathname);
+    const base = pathname.slice(0, pathname.length - ext.length);
+    return `${base}.${digest}${ext}`;
+}
+/** Single source of truth for URL → cache path. Used identically by the
+ *  reader (cache lookup) and writer (install-time persistence). For any
+ *  given import URL — registry ref, direct registry URL, or arbitrary
+ *  HTTP — both sides land on the same file.
+ *
+ *  Returns `null` for unsupported URLs (file://, memory://, relative paths)
+ *  or for path-traversal attempts that would escape `cacheRoot`. */
+function cachePathForUrl(url, cacheRoot, registryUrl) {
+    const trimmedRegistry = registryUrl.replace(/\/+$/, "");
+    // 1. Registry ref form: namespace/name@version
+    if (!url.startsWith("http://") &&
+        !url.startsWith("https://") &&
+        !url.startsWith("/") &&
+        !url.startsWith(".") &&
+        !url.startsWith("file://") &&
+        !url.startsWith("memory://") &&
+        url.includes("@") &&
+        url.includes("/")) {
+        const atIdx = url.lastIndexOf("@");
+        if (atIdx <= 0 || atIdx === url.length - 1)
+            return null;
+        const modulePath = url.slice(0, atIdx);
+        if (!modulePath.includes("/"))
+            return null;
+        const version = url.slice(atIdx + 1).replace(/^v/, "");
+        if (!version)
+            return null;
+        return joinUnder(cacheRoot, modulePath, version, DEFAULT_MANIFEST_FILENAME);
+    }
+    // 2. HTTP(S) URL — could be a direct registry URL or arbitrary external.
+    if (url.startsWith("http://") || url.startsWith("https://")) {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            return null;
+        }
+        const pathname = normalizePathname(url, parsed);
+        // 2a. URL is on the configured registry, with no query/fragment:
+        //     fold into the registry layout so the writer that received a
+        //     registry-ref canonical and the reader that sees a direct URL
+        //     both resolve to the same file.
+        const normalizedUrl = `${parsed.protocol}//${parsed.host}${pathname}`;
+        if (!parsed.search &&
+            !parsed.hash &&
+            (normalizedUrl === trimmedRegistry || normalizedUrl.startsWith(`${trimmedRegistry}/`))) {
+            const rel = normalizedUrl.slice(trimmedRegistry.length + 1);
+            if (!rel)
+                return null;
+            return joinUnder(cacheRoot, ...rel.split("/"));
+        }
+        // 2b. Arbitrary HTTP(S) URL → __http subtree, with a short query-hash
+        //     suffix when query / fragment are present to prevent collisions.
+        const cleanPath = pathname.startsWith("/") ? pathname.slice(1) : pathname;
+        const disambiguated = disambiguatePath(cleanPath, parsed.search, parsed.hash);
+        return joinUnder(cacheRoot, HTTP_NAMESPACE, parsed.host, ...disambiguated.split("/"));
+    }
+    return null;
+}
+/**
+ * Reads previously-cached manifest YAMLs from `<entry-dir>/.telo/manifests/`.
+ * Sits ahead of `RegistrySource` / `HttpSource` in the source chain — a hit
+ * makes boot hermetic, a miss falls through to the network source unchanged.
+ *
+ * Populated by `writeManifestCache` at install time.
+ */
+export class LocalManifestCacheSource {
+    constructor(entryDir, registryUrl = DEFAULT_REGISTRY_URL) {
+        this.cacheRoot = path.join(entryDir, CACHE_SUBDIR);
+        this.registryUrl = registryUrl;
+    }
+    supports(url) {
+        return this.tryMap(url) !== null;
+    }
+    async read(url) {
+        const mapped = this.tryMap(url);
+        if (!mapped) {
+            throw new Error(`LocalManifestCacheSource does not support '${url}' (cache miss or unsupported scheme)`);
+        }
+        const text = await fs.readFile(mapped, "utf-8");
+        return { text, source: pathToFileURL(mapped).href };
+    }
+    resolveRelative(base, relative) {
+        // Once `read()` serves a file the canonical `source` is a file:// URL, so
+        // any further include: / sibling resolution flows through LocalFileSource.
+        // This method exists only for completeness; if the loader ever invokes it
+        // with a cache-mapped base, fall back to file-URL semantics.
+        const baseDir = base.endsWith("/") ? base : base.slice(0, base.lastIndexOf("/") + 1);
+        return new URL(relative, baseDir).href;
+    }
+    tryMap(url) {
+        const candidate = cachePathForUrl(url, this.cacheRoot, this.registryUrl);
+        if (!candidate)
+            return null;
+        // Require a regular file. A directory, dangling symlink, or stat failure
+        // (ENOENT, EACCES, EISDIR-on-component) all fall through as a cache miss
+        // so the next source in the chain still gets a chance to serve the URL.
+        try {
+            return statSync(candidate).isFile() ? candidate : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Map a graph's canonical `source` URL to the on-disk cache file path it
+ * should be written to (writer side). Returns `null` for sources that do
+ * not need caching — file:// (already on disk), memory:// (transient), or
+ * any path that would escape the cache root.
+ *
+ * Uses the same mapping function as `LocalManifestCacheSource`, so the
+ * writer and reader always agree on where every URL lives.
+ */
+export function cachePathForCanonical(canonicalSource, entryDir, registryUrl) {
+    const cacheRoot = path.join(entryDir, CACHE_SUBDIR);
+    return cachePathForUrl(canonicalSource, cacheRoot, registryUrl);
+}
+/**
+ * Persist every manifest file reachable from `graph` (owners + partials) to
+ * `<entryDir>/.telo/manifests/`, except the entry manifest itself and any
+ * file:// or memory:// sources (already on disk or transient).
+ *
+ * Idempotent: rewrites any existing file with the freshly fetched bytes so
+ * a partial re-install converges. Never deletes entries — stale versions
+ * stay until `.telo/manifests/` is removed by hand, matching the
+ * `.telo/npm/` convention.
+ *
+ * Returns the list of paths written, for diagnostics.
+ */
+export async function writeManifestCache(graph, entryDir, registryUrl = DEFAULT_REGISTRY_URL) {
+    const written = [];
+    const seen = new Set();
+    for (const [, module] of graph.modules) {
+        for (const file of [module.owner, ...module.partials]) {
+            if (file.source === graph.rootSource)
+                continue;
+            if (seen.has(file.source))
+                continue;
+            seen.add(file.source);
+            const target = cachePathForCanonical(file.source, entryDir, registryUrl);
+            if (!target)
+                continue;
+            await fs.mkdir(path.dirname(target), { recursive: true });
+            await fs.writeFile(target, file.text, "utf-8");
+            written.push(target);
+        }
+    }
+    return written;
+}
+/** Resolve the entry-anchor directory for the manifest cache.
+ *
+ * For a file path or `file://` URL: returns the containing directory.
+ * For a directory path: returns the directory itself.
+ * For an HTTP(S) URL: returns `null` (no local anchor; cache writes skipped). */
+export function resolveEntryDir(entryPath) {
+    if (entryPath.startsWith("http://") || entryPath.startsWith("https://")) {
+        return null;
+    }
+    let absolute;
+    if (entryPath.startsWith("file://")) {
+        absolute = fileURLToPath(entryPath);
+    }
+    else {
+        absolute = path.resolve(entryPath);
+    }
+    try {
+        const stat = statSync(absolute);
+        return stat.isDirectory() ? absolute : path.dirname(absolute);
+    }
+    catch {
+        return path.dirname(absolute);
+    }
+}
+//# sourceMappingURL=local-manifest-cache-source.js.map

package/dist/manifest-sources/local-manifest-cache-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-manifest-cache-source.js","sourceRoot":"","sources":["../../src/manifest-sources/local-manifest-cache-source.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEnD,MAAM,YAAY,GAAG,iBAAiB,CAAC;AACvC,MAAM,cAAc,GAAG,QAAQ,CAAC;AAChC,MAAM,yBAAyB,GAAG,WAAW,CAAC;AAC9C,MAAM,oBAAoB,GAAG,2BAA2B,CAAC;AACzD,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAE7B;;yEAEyE;AACzE,SAAS,SAAS,CAAC,IAAY,EAAE,GAAG,QAAkB;IACpD,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IAChD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,QAAQ,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACzC,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,QAAQ,KAAK,YAAY,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/E,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;8CAG8C;AAC9C,SAAS,iBAAiB,CAAC,GAAW,EAAE,MAAW;IACjD,IAAI,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC/B,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC;YAC/B,CAAC,CAAC,GAAG,QAAQ,GAAG,yBAAyB,EAAE;YAC3C,CAAC,CAAC,GAAG,QAAQ,IAAI,yBAAyB,EAAE,CAAC;IACjD,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;0DAE0D;AAC1D,SAAS,gBAAgB,CAAC,QAAgB,EAAE,MAAc,EAAE,IAAY;IACtE,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI;QAAE,OAAO,QAAQ,CAAC;IACtC,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC;SAChC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC;SACrB,MAAM,CAAC,KAAK,CAAC;SACb,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC;IAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7D,OAAO,GAAG,IAAI,IAAI,MAAM,GAAG,GAAG,EAAE,CAAC;AACnC,CAAC;AAED;;;;;;oEAMoE;AACpE,SAAS,eAAe,CACtB,GAAW,EACX,SAAiB,EACjB,WAAmB;IAEnB,MAAM,eAAe,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAExD,+CAA+C;IAC/C,IACE,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC;QAC1B,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC;QAC3B,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC;QACpB,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC;QACpB,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC;QAC1B,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC;QAC5B,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC;QACjB,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EACjB,CAAC;QACD,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,KAAK,GAAG,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QACxD,MAAM,UAAU,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QACvC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAC3C,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACvD,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAC1B,OAAO,SAAS,CAAC,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,yBAAyB,CAAC,CAAC;IAC9E,CAAC;IAED,yEAAyE;IACzE,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5D,IAAI,MAAW,CAAC;QAChB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAEhD,iEAAiE;QACjE,kEAAkE;QAClE,mEAAmE;QACnE,qCAAqC;QACrC,MAAM,aAAa,GAAG,GAAG,MAAM,CAAC,QAAQ,KAAK,MAAM,CAAC,IAAI,GAAG,QAAQ,EAAE,CAAC;QACtE,IACE,CAAC,MAAM,CAAC,MAAM;YACd,CAAC,MAAM,CAAC,IAAI;YACZ,CAAC,aAAa,KAAK,eAAe,IAAI,aAAa,CAAC,UAAU,CAAC,GAAG,eAAe,GAAG,CAAC,CAAC,EACtF,CAAC;YACD,MAAM,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAC5D,IAAI,CAAC,GAAG;gBAAE,OAAO,IAAI,CAAC;YACtB,OAAO,SAAS,CAAC,SAAS,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACjD,CAAC;QAED,sEAAsE;QACtE,sEAAsE;QACtE,MAAM,SAAS,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC1E,MAAM,aAAa,GAAG,gBAAgB,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9E,OAAO,SAAS,CAAC,SAAS,EAAE,cAAc,EAAE,MAAM,CAAC,IAAI,EAAE,GAAG,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACxF,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,wBAAwB;IAInC,YAAY,QAAgB,EAAE,cAAsB,oBAAoB;QACtE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;QACnD,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;IAED,QAAQ,CAAC,GAAW;QAClB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAW;QACpB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,8CAA8C,GAAG,sCAAsC,CACxF,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IACtD,CAAC;IAED,eAAe,CAAC,IAAY,EAAE,QAAgB;QAC5C,0EAA0E;QAC1E,2EAA2E;QAC3E,0EAA0E;QAC1E,6DAA6D;QAC7D,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QACrF,OAAO,IAAI,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;IACzC,CAAC;IAEO,MAAM,CAAC,GAAW;QACxB,MAAM,SAAS,GAAG,eAAe,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QACzE,IAAI,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC;QAC5B,yEAAyE;QACzE,yEAAyE;QACzE,wEAAwE;QACxE,IAAI,CAAC;YACH,OAAO,QAAQ,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CACnC,eAAuB,EACvB,QAAgB,EAChB,WAAmB;IAEnB,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IACpD,OAAO,eAAe,CAAC,eAAe,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAkB,EAClB,QAAgB,EAChB,cAAsB,oBAAoB;IAE1C,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,KAAK,MAAM,CAAC,EAAE,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QACvC,KAAK,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YACtD,IAAI,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,UAAU;gBAAE,SAAS;YAC/C,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC;gBAAE,SAAS;YACpC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAEtB,MAAM,MAAM,GAAG,qBAAqB,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;YACzE,IAAI,CAAC,MAAM;gBAAE,SAAS;YAEtB,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1D,MAAM,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAC/C,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;iFAIiF;AACjF,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,IAAI,SAAS,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACxE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,QAAgB,CAAC;IACrB,IAAI,SAAS,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACpC,QAAQ,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;SAAM,CAAC;QACN,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACrC,CAAC;IACD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/kernel",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Telo Runtime - A lightweight, polyglot execution host.",
   "keywords": [
     "digly",
@@ -47,7 +47,7 @@
   "dependencies": {
     "@marcbachmann/cel-js": "^7.5.3",
     "@sinclair/typebox": "^0.34.48",
-    "@telorun/analyzer": "0.9.0",
+    "@telorun/analyzer": "0.10.0",
     "@telorun/sdk": "0.10.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",

package/src/index.ts

@@ -2,6 +2,12 @@ export { ControllerLoader } from "./controller-loader.js";
 export { ControllerRegistry } from "./controller-registry.js";
 export { EvaluationContext } from "./evaluation-context.js";
 export { LocalFileSource } from "./manifest-sources/local-file-source.js";
+export {
+  LocalManifestCacheSource,
+  cachePathForCanonical,
+  resolveEntryDir,
+  writeManifestCache,
+} from "./manifest-sources/local-manifest-cache-source.js";
 export { MemorySource } from "./manifest-sources/memory-source.js";
 export { EventStream } from "./event-stream.js";
 export { ExecutionContext } from "./execution-context.js";

package/src/manifest-sources/local-manifest-cache-source.ts

@@ -0,0 +1,256 @@
+import type { LoadedGraph, ManifestSource } from "@telorun/analyzer";
+import { createHash } from "crypto";
+import { statSync } from "fs";
+import * as fs from "fs/promises";
+import * as path from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+
+const CACHE_SUBDIR = ".telo/manifests";
+const HTTP_NAMESPACE = "__http";
+const DEFAULT_MANIFEST_FILENAME = "telo.yaml";
+const DEFAULT_REGISTRY_URL = "https://registry.telo.run";
+const QUERY_HASH_LENGTH = 12;
+
+/** Verify that `candidate` resolves to a path under `root`. Returns the
+ *  candidate path on success, `null` when any segment escapes the root.
+ *  Guards against `..` segments inside module refs or HTTP pathnames. */
+function joinUnder(root: string, ...segments: string[]): string | null {
+  if (segments.some((s) => s === "")) return null;
+  const candidate = path.join(root, ...segments);
+  const resolved = path.resolve(candidate);
+  const resolvedRoot = path.resolve(root);
+  if (resolved !== resolvedRoot && !resolved.startsWith(resolvedRoot + path.sep)) {
+    return null;
+  }
+  return candidate;
+}
+
+/** Mirror `HttpSource.read`'s `fetchUrl` derivation: when the URL does not
+ *  already point at a YAML file, append `/telo.yaml`. Used by both the
+ *  reader and writer so a raw import URL and the canonical source it
+ *  resolves to map to the same cache path. */
+function normalizePathname(url: string, parsed: URL): string {
+  let pathname = parsed.pathname;
+  if (!url.includes(".yaml")) {
+    pathname = pathname.endsWith("/")
+      ? `${pathname}${DEFAULT_MANIFEST_FILENAME}`
+      : `${pathname}/${DEFAULT_MANIFEST_FILENAME}`;
+  }
+  return pathname;
+}
+
+/** Compute a short hash of `search + hash` so two URLs that differ only in
+ *  query / fragment do not collide at the same cache path. Inserted before
+ *  the final extension so the filename stays readable. */
+function disambiguatePath(pathname: string, search: string, hash: string): string {
+  if (!search && !hash) return pathname;
+  const digest = createHash("sha256")
+    .update(search + hash)
+    .digest("hex")
+    .slice(0, QUERY_HASH_LENGTH);
+  const ext = path.extname(pathname);
+  const base = pathname.slice(0, pathname.length - ext.length);
+  return `${base}.${digest}${ext}`;
+}
+
+/** Single source of truth for URL → cache path. Used identically by the
+ *  reader (cache lookup) and writer (install-time persistence). For any
+ *  given import URL — registry ref, direct registry URL, or arbitrary
+ *  HTTP — both sides land on the same file.
+ *
+ *  Returns `null` for unsupported URLs (file://, memory://, relative paths)
+ *  or for path-traversal attempts that would escape `cacheRoot`. */
+function cachePathForUrl(
+  url: string,
+  cacheRoot: string,
+  registryUrl: string,
+): string | null {
+  const trimmedRegistry = registryUrl.replace(/\/+$/, "");
+
+  // 1. Registry ref form: namespace/name@version
+  if (
+    !url.startsWith("http://") &&
+    !url.startsWith("https://") &&
+    !url.startsWith("/") &&
+    !url.startsWith(".") &&
+    !url.startsWith("file://") &&
+    !url.startsWith("memory://") &&
+    url.includes("@") &&
+    url.includes("/")
+  ) {
+    const atIdx = url.lastIndexOf("@");
+    if (atIdx <= 0 || atIdx === url.length - 1) return null;
+    const modulePath = url.slice(0, atIdx);
+    if (!modulePath.includes("/")) return null;
+    const version = url.slice(atIdx + 1).replace(/^v/, "");
+    if (!version) return null;
+    return joinUnder(cacheRoot, modulePath, version, DEFAULT_MANIFEST_FILENAME);
+  }
+
+  // 2. HTTP(S) URL — could be a direct registry URL or arbitrary external.
+  if (url.startsWith("http://") || url.startsWith("https://")) {
+    let parsed: URL;
+    try {
+      parsed = new URL(url);
+    } catch {
+      return null;
+    }
+    const pathname = normalizePathname(url, parsed);
+
+    // 2a. URL is on the configured registry, with no query/fragment:
+    //     fold into the registry layout so the writer that received a
+    //     registry-ref canonical and the reader that sees a direct URL
+    //     both resolve to the same file.
+    const normalizedUrl = `${parsed.protocol}//${parsed.host}${pathname}`;
+    if (
+      !parsed.search &&
+      !parsed.hash &&
+      (normalizedUrl === trimmedRegistry || normalizedUrl.startsWith(`${trimmedRegistry}/`))
+    ) {
+      const rel = normalizedUrl.slice(trimmedRegistry.length + 1);
+      if (!rel) return null;
+      return joinUnder(cacheRoot, ...rel.split("/"));
+    }
+
+    // 2b. Arbitrary HTTP(S) URL → __http subtree, with a short query-hash
+    //     suffix when query / fragment are present to prevent collisions.
+    const cleanPath = pathname.startsWith("/") ? pathname.slice(1) : pathname;
+    const disambiguated = disambiguatePath(cleanPath, parsed.search, parsed.hash);
+    return joinUnder(cacheRoot, HTTP_NAMESPACE, parsed.host, ...disambiguated.split("/"));
+  }
+
+  return null;
+}
+
+/**
+ * Reads previously-cached manifest YAMLs from `<entry-dir>/.telo/manifests/`.
+ * Sits ahead of `RegistrySource` / `HttpSource` in the source chain — a hit
+ * makes boot hermetic, a miss falls through to the network source unchanged.
+ *
+ * Populated by `writeManifestCache` at install time.
+ */
+export class LocalManifestCacheSource implements ManifestSource {
+  private readonly cacheRoot: string;
+  private readonly registryUrl: string;
+
+  constructor(entryDir: string, registryUrl: string = DEFAULT_REGISTRY_URL) {
+    this.cacheRoot = path.join(entryDir, CACHE_SUBDIR);
+    this.registryUrl = registryUrl;
+  }
+
+  supports(url: string): boolean {
+    return this.tryMap(url) !== null;
+  }
+
+  async read(url: string): Promise<{ text: string; source: string }> {
+    const mapped = this.tryMap(url);
+    if (!mapped) {
+      throw new Error(
+        `LocalManifestCacheSource does not support '${url}' (cache miss or unsupported scheme)`,
+      );
+    }
+    const text = await fs.readFile(mapped, "utf-8");
+    return { text, source: pathToFileURL(mapped).href };
+  }
+
+  resolveRelative(base: string, relative: string): string {
+    // Once `read()` serves a file the canonical `source` is a file:// URL, so
+    // any further include: / sibling resolution flows through LocalFileSource.
+    // This method exists only for completeness; if the loader ever invokes it
+    // with a cache-mapped base, fall back to file-URL semantics.
+    const baseDir = base.endsWith("/") ? base : base.slice(0, base.lastIndexOf("/") + 1);
+    return new URL(relative, baseDir).href;
+  }
+
+  private tryMap(url: string): string | null {
+    const candidate = cachePathForUrl(url, this.cacheRoot, this.registryUrl);
+    if (!candidate) return null;
+    // Require a regular file. A directory, dangling symlink, or stat failure
+    // (ENOENT, EACCES, EISDIR-on-component) all fall through as a cache miss
+    // so the next source in the chain still gets a chance to serve the URL.
+    try {
+      return statSync(candidate).isFile() ? candidate : null;
+    } catch {
+      return null;
+    }
+  }
+}
+
+/**
+ * Map a graph's canonical `source` URL to the on-disk cache file path it
+ * should be written to (writer side). Returns `null` for sources that do
+ * not need caching — file:// (already on disk), memory:// (transient), or
+ * any path that would escape the cache root.
+ *
+ * Uses the same mapping function as `LocalManifestCacheSource`, so the
+ * writer and reader always agree on where every URL lives.
+ */
+export function cachePathForCanonical(
+  canonicalSource: string,
+  entryDir: string,
+  registryUrl: string,
+): string | null {
+  const cacheRoot = path.join(entryDir, CACHE_SUBDIR);
+  return cachePathForUrl(canonicalSource, cacheRoot, registryUrl);
+}
+
+/**
+ * Persist every manifest file reachable from `graph` (owners + partials) to
+ * `<entryDir>/.telo/manifests/`, except the entry manifest itself and any
+ * file:// or memory:// sources (already on disk or transient).
+ *
+ * Idempotent: rewrites any existing file with the freshly fetched bytes so
+ * a partial re-install converges. Never deletes entries — stale versions
+ * stay until `.telo/manifests/` is removed by hand, matching the
+ * `.telo/npm/` convention.
+ *
+ * Returns the list of paths written, for diagnostics.
+ */
+export async function writeManifestCache(
+  graph: LoadedGraph,
+  entryDir: string,
+  registryUrl: string = DEFAULT_REGISTRY_URL,
+): Promise<string[]> {
+  const written: string[] = [];
+  const seen = new Set<string>();
+
+  for (const [, module] of graph.modules) {
+    for (const file of [module.owner, ...module.partials]) {
+      if (file.source === graph.rootSource) continue;
+      if (seen.has(file.source)) continue;
+      seen.add(file.source);
+
+      const target = cachePathForCanonical(file.source, entryDir, registryUrl);
+      if (!target) continue;
+
+      await fs.mkdir(path.dirname(target), { recursive: true });
+      await fs.writeFile(target, file.text, "utf-8");
+      written.push(target);
+    }
+  }
+
+  return written;
+}
+
+/** Resolve the entry-anchor directory for the manifest cache.
+ *
+ * For a file path or `file://` URL: returns the containing directory.
+ * For a directory path: returns the directory itself.
+ * For an HTTP(S) URL: returns `null` (no local anchor; cache writes skipped). */
+export function resolveEntryDir(entryPath: string): string | null {
+  if (entryPath.startsWith("http://") || entryPath.startsWith("https://")) {
+    return null;
+  }
+  let absolute: string;
+  if (entryPath.startsWith("file://")) {
+    absolute = fileURLToPath(entryPath);
+  } else {
+    absolute = path.resolve(entryPath);
+  }
+  try {
+    const stat = statSync(absolute);
+    return stat.isDirectory() ? absolute : path.dirname(absolute);
+  } catch {
+    return path.dirname(absolute);
+  }
+}