@telorun/kernel 0.55.0 → 0.57.0

package/src/transports/registry-transport.ts

@@ -5,8 +5,11 @@ import {
   RegistrySource,
   isRegistryRef,
   parseModuleRef,
+  parseVersionedRef,
   sha256Base64Url,
+  withRefVersion,
   splitIntegrity,
+  type ManifestCacheCoords,
   type ManifestSource,
 } from "@telorun/analyzer";
 import { fetchOrThrow } from "@telorun/sdk";
@@ -21,12 +24,23 @@ import type {
   PublishBundle,
   PublishOptions,
   PublishResult,
-  SiblingIdentity,
   Transport,
 } from "./transport.js";
 
 const DEFAULT_REGISTRY_URL = "https://registry.telo.run";
-const HTTP_NAMESPACE = "__http";
+/** Throwaway origin that lets a bare registry ref use URL path resolution. */
+const JOIN_ORIGIN = "https://ref.invalid";
+
+/** True for an HTTP(S) destination that names a registry root rather than a
+ *  module within it — no path segments to resolve a sibling beside. */
+function isRegistryBase(base: string): boolean {
+  if (!base.startsWith("http://") && !base.startsWith("https://")) return false;
+  try {
+    return new URL(base).pathname.replace(/\/+/g, "/").replace(/^\/|\/$/g, "") === "";
+  } catch {
+    return false;
+  }
+}
 const QUERY_HASH_LENGTH = 12;
 
 /** Mirror `HttpSource.read`'s `fetchUrl` derivation: when the URL does not
@@ -95,19 +109,28 @@ export class RegistryTransport implements Transport {
     return base.startsWith("http://") || base.startsWith("https://") || isRegistryRef(ref);
   }
 
-  cacheLocation(ref: string): string[] | null {
+  cacheCoords(ref: string): ManifestCacheCoords | null {
     const url = splitIntegrity(ref).base;
     const trimmedRegistry = this.registryUrl.replace(/\/+$/, "");
+    const registryHost = this.registryHost();
 
-    // 1. Registry ref form: namespace/name@version
+    // 1. Registry ref form: <path>@<version>. Keyed under the registry's host —
+    //    a ref says nothing about which registry serves it, so without the host
+    //    two registries' copies of the same path/version share one cache entry.
     if (isRegistryRef(url)) {
+      if (!registryHost) return null;
       let parsed: ReturnType<typeof parseModuleRef>;
       try {
         parsed = parseModuleRef(url);
       } catch {
         return null;
       }
-      return [parsed.modulePath, parsed.version, DEFAULT_MANIFEST_FILENAME];
+      return {
+        transport: "registry",
+        host: registryHost,
+        path: parsed.modulePath,
+        version: parsed.version,
+      };
     }
 
     // 2. HTTP(S) URL — a direct registry URL or arbitrary external.
@@ -124,24 +147,49 @@ export class RegistryTransport implements Transport {
       //     registry layout so a ref and a direct URL land on the same file.
       const normalizedUrl = `${parsed.protocol}//${parsed.host}${pathname}`;
       if (
+        registryHost &&
         !parsed.search &&
         !parsed.hash &&
-        (normalizedUrl === trimmedRegistry || normalizedUrl.startsWith(`${trimmedRegistry}/`))
+        normalizedUrl.startsWith(`${trimmedRegistry}/`)
       ) {
-        const rel = normalizedUrl.slice(trimmedRegistry.length + 1);
-        if (!rel) return null;
-        return rel.split("/");
+        // The registry serves `<path…>/<version>/<file>`, where `<file>` is the
+        // module manifest or one of its `include:` partials.
+        const segments = normalizedUrl.slice(trimmedRegistry.length + 1).split("/");
+        const file = segments.pop();
+        const version = segments.pop();
+        if (file && version && segments.length > 0) {
+          return {
+            transport: "registry",
+            host: registryHost,
+            path: segments.join("/"),
+            version,
+            file,
+          };
+        }
       }
 
-      // 2b. Arbitrary HTTP(S) → __http subtree, query-hash suffix on collision.
+      // 2b. Arbitrary HTTP(S) → `url` subtree, query-hash suffix on collision.
+      //     No version segment: a URL addresses exactly one file, and the
+      //     version it declares lives inside bytes the cache maps paths without.
       const cleanPath = pathname.startsWith("/") ? pathname.slice(1) : pathname;
-      const disambiguated = disambiguatePath(cleanPath, parsed.search, parsed.hash);
-      return [HTTP_NAMESPACE, parsed.host, ...disambiguated.split("/")];
+      const segments = disambiguatePath(cleanPath, parsed.search, parsed.hash).split("/");
+      const file = segments.pop();
+      if (!file) return null;
+      return { transport: "url", host: parsed.host, path: segments.join("/"), file };
     }
 
     return null;
   }
 
+  /** Host of the configured registry, or `null` when the URL is unparseable. */
+  private registryHost(): string | null {
+    try {
+      return new URL(this.registryUrl).host || null;
+    } catch {
+      return null;
+    }
+  }
+
   async listVersions(ref: string): Promise<string[] | null> {
     // Only bare registry refs are version-enumerable — a direct `https://` URL
     // has no version-list endpoint.
@@ -165,15 +213,11 @@ export class RegistryTransport implements Transport {
   refVersion(ref: string): string | null {
     // Only bare `namespace/name@version` refs carry an upgradeable version — a
     // direct `https://` URL has no version segment to bump.
-    if (!isRegistryRef(ref)) return null;
-    const { base } = splitIntegrity(ref);
-    const at = base.lastIndexOf("@");
-    return at > 0 ? base.slice(at + 1) : null;
+    return isRegistryRef(ref) ? (parseVersionedRef(ref)?.version ?? null) : null;
   }
 
   withVersion(ref: string, version: string): string {
-    const { modulePath } = parseModuleRef(ref);
-    return `${modulePath}@${version}`;
+    return withRefVersion(ref, version);
   }
 
   /** Mirrors the sources' fetch-URL derivation: a direct URL points at (or
@@ -279,16 +323,31 @@ export class RegistryTransport implements Transport {
   }
 
   canonicalizeSiblingRef(
-    _destination: string,
-    _relativeSource: string,
-    sibling: SiblingIdentity,
+    destination: string,
+    relativeSource: string,
+    version: string,
   ): string {
-    // An HTTP registry path defaults to the sibling's own `<namespace>/<name>`.
-    if (!sibling.namespace || !sibling.name) {
+    // The sibling sits beside the destination module: resolve the relative path
+    // against the destination's own path, then pin the sibling's version. A bare
+    // registry ref (`std/foo`) is a path, not a URL, so it borrows a throwaway
+    // origin for the join and drops it again.
+    const base = splitIntegrity(destination).base.replace(/@[^/@]*$/, "");
+    // A registry *base* (`https://registry.telo.run`) is not a module location,
+    // so there is nothing for `../lib` to resolve beside — joining anyway would
+    // silently produce a ref one path segment short.
+    if (isRegistryBase(base)) {
       throw new Error(
-        "a relative import canonicalized to an HTTP registry needs the sibling's metadata.namespace and metadata.name.",
+        `cannot canonicalize the relative import '${relativeSource}': publish destination ` +
+          `'${destination}' is a registry base, not this module's own location. Pass the ` +
+          `module's full destination (e.g. '${base.replace(/\/+$/, "")}/<namespace>/<name>').`,
       );
     }
-    return `${sibling.namespace}/${sibling.name}@${sibling.version}`;
+    const isUrl = base.startsWith("http://") || base.startsWith("https://");
+    const origin = isUrl ? base : `${JOIN_ORIGIN}/${base.replace(/^\/+/, "")}`;
+    const resolved = new URL(relativeSource, `${origin.replace(/\/+$/, "")}/`);
+    const joined = isUrl
+      ? `${resolved.protocol}//${resolved.host}${resolved.pathname}`
+      : resolved.pathname.replace(/^\/+/, "");
+    return `${joined.replace(/\/+$/, "")}@${version}`;
   }
 }

package/src/transports/transport-registry.ts

@@ -1,4 +1,4 @@
-import type { ManifestSource } from "@telorun/analyzer";
+import type { ManifestCacheCoords, ManifestSource } from "@telorun/analyzer";
 
 import { OciTransport } from "./oci/oci-transport.js";
 import { RegistryTransport } from "./registry-transport.js";
@@ -29,10 +29,10 @@ export class TransportRegistry {
     return this.transports.map((t) => t.source);
   }
 
-  /** Cache-path segments for `ref`, from its owning transport; `null` when no
-   *  transport owns it or the ref is not cacheable. */
-  cacheLocation(ref: string): string[] | null {
-    return this.forRef(ref)?.cacheLocation(ref) ?? null;
+  /** Manifest-cache coordinates for `ref`, from its owning transport; `null`
+   *  when no transport owns it or the ref is not cacheable. */
+  cacheCoords(ref: string): ManifestCacheCoords | null {
+    return this.forRef(ref)?.cacheCoords(ref) ?? null;
   }
 
   /** Published versions for `ref` via its owning transport; `null` when the

package/src/transports/transport.ts

@@ -1,4 +1,4 @@
-import type { ManifestSource } from "@telorun/analyzer";
+import type { ManifestCacheCoords, ManifestSource } from "@telorun/analyzer";
 
 import type { PayloadFile } from "../bundle/files-integrity.js";
 
@@ -28,15 +28,6 @@ export interface PublishResult {
   url: string;
 }
 
-/** Identity of a sibling library, read from its own manifest, that a relative
- *  import canonicalizes to. `version` is always required; `namespace`/`name` are
- *  used only by transports whose location is metadata-derived (HTTP registry). */
-export interface SiblingIdentity {
-  namespace?: string;
-  name?: string;
-  version: string;
-}
-
 export interface PublishOptions {
   /** Bearer token for registries that require auth. */
   token?: string;
@@ -61,7 +52,7 @@ export interface PublishOptions {
  *  `ManifestSource` is the browser-safe resolution primitive (also implemented
  *  by the cache / local / memory sources, which have no versions and nothing to
  *  publish), so it stays in `analyzer`, while the Node-only management methods
- *  (`cacheLocation` and, in later phases, `listVersions` / `fetchArtifact` /
+ *  (`cacheCoords` and, in later phases, `listVersions` / `fetchArtifact` /
  *  `publish`) live on the Transport here in `kernel`. */
 export interface Transport {
   /** True when this transport owns the given ref (or publish destination). */
@@ -72,10 +63,21 @@ export interface Transport {
    *  live in `analyzer`; a Node-only transport has no browser-safe source. */
   readonly source: ManifestSource;
 
-  /** Deterministic cache-path segments for a ref, joined under the cache root by
-   *  the cache source. Returns `null` when the ref is not cacheable here
-   *  (unsupported scheme, malformed ref, or path-traversal in the ref). */
-  cacheLocation(ref: string): string[] | null;
+  /** Where a ref's `telo.yaml` is cached, as the transport-neutral
+   *  `{ transport, host, path, version, file }` coordinates the analyzer's
+   *  `manifestCacheKey` renders into a path. One grammar serves the local
+   *  install cache, the hub's static manifest bucket, and the editor's read
+   *  path, so the three cannot drift on the *shape* of a cache key.
+   *
+   *  They do differ on coordinates, deliberately, for a `url` ref: the hub reads
+   *  the version out of the fetched manifest and keys by it, while this cache
+   *  maps a ref to a path before any fetch and so has no version to supply —
+   *  it names the file instead, since it also stores each `include:` partial.
+   *  Same grammar, different coordinates; not a drift to reconcile.
+   *
+   *  Returns `null` when the ref is not cacheable here (unsupported scheme,
+   *  malformed ref, or path-traversal in the ref). */
+  cacheCoords(ref: string): ManifestCacheCoords | null;
 
   /** The versions published for the module `ref` names, newest-first order not
    *  guaranteed (the caller sorts). Returns `null` when the module is not
@@ -147,13 +149,18 @@ export interface Transport {
 
   /** Canonicalize a relative sibling import (`../lib`) declared in a module
    *  being published to `destination` into the absolute ref it will resolve to
-   *  once published. Owns the scheme-specific "where does a sibling land" rule —
-   *  OCI derives the repo from the destination, HTTP from the sibling's
-   *  `<namespace>/<name>` — so `telo publish` delegates instead of branching on
-   *  transport shape. */
+   *  once published.
+   *
+   *  The sibling lands beside the destination: the destination's last segment is
+   *  the module's own directory, so the relative path resolves against it
+   *  exactly as it does on the publisher's disk — publishing `…/telorun/foo`
+   *  with an import of `../bar` yields `…/telorun/bar`. Only the version comes
+   *  from the sibling's own manifest; nothing is read from its metadata to
+   *  decide where it lives. Each transport owns the join for its ref grammar, so
+   *  `telo publish` delegates instead of branching on transport shape. */
   canonicalizeSiblingRef(
     destination: string,
     relativeSource: string,
-    sibling: SiblingIdentity,
+    version: string,
   ): string;
 }