@telorun/ide-support 0.5.0 → 0.6.0

package/dist/completions/import-source.d.ts

@@ -7,9 +7,13 @@ import type { CompletionResult, IdeEnvironmentAdapter } from "../types.js";
  * Branches by prefix shape:
  *   ""                         → relative dirs under the manifest dir, plus `./` / `../` seeds.
  *   "./..", "../", "/..."      → subdirs of the typed path (any subdir; existing manifest gets a hint).
- *   "<word>"                   → registry search by free-text.
- *   "<ns>/<name>@<partial>"    → version list for that module.
- *   "http(s)://", "file://"    → no suggestions (opaque URLs).
+ *   "<word>", "oci://…"        → hub ref autocomplete (fuzzy substring over registered refs).
+ *   "<ref>@<partial>"          → version list for that ref.
+ *   "http(s)://", "file://"    → no suggestions (opaque URLs the author types verbatim).
+ *
+ * `oci://` is deliberately NOT opaque: without an `@` it routes to the ref
+ * search below, whose query is the whole typed prefix — so the hub fuzzy-matches
+ * `oci://ghcr.io/aws/telo-s3` as readily as a bare `s3`.
  *
  * `valueStartColumn` is forwarded onto every result so the host can replace
  * the whole typed value, not just the trailing word (Monaco / VSCode word

package/dist/completions/import-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import-source.d.ts","sourceRoot":"","sources":["../../src/completions/import-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAW3E;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,MAAM,EACxB,OAAO,EAAE,qBAAqB,GAAG,SAAS,GACzC,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAuB7B"}
+{"version":3,"file":"import-source.d.ts","sourceRoot":"","sources":["../../src/completions/import-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAY3E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,MAAM,EACxB,OAAO,EAAE,qBAAqB,GAAG,SAAS,GACzC,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAyB7B"}

package/dist/completions/import-source.js

@@ -1,6 +1,7 @@
-/** Maximum registry hits to surface in a single completion request.
- *  Keeps the popover scannable when a broad `q=` query matches the catalog. */
-const REGISTRY_LIMIT = 50;
+/** Maximum ref hits to surface in a single completion request. Keeps the
+ *  popover scannable when a broad `q=` query matches many registered refs
+ *  (the hub already caps `/refs` server-side; this is a client backstop). */
+const REF_LIMIT = 50;
 /** Caps the number of directory entries we probe with `hasManifest` per
  *  request. Each probe is a host-side filesystem stat; the popover would not
  *  show more than ~50 entries anyway, so probing further only adds latency. */
@@ -13,9 +14,13 @@ const PATH_PROBE_LIMIT = 50;
  * Branches by prefix shape:
  *   ""                         → relative dirs under the manifest dir, plus `./` / `../` seeds.
  *   "./..", "../", "/..."      → subdirs of the typed path (any subdir; existing manifest gets a hint).
- *   "<word>"                   → registry search by free-text.
- *   "<ns>/<name>@<partial>"    → version list for that module.
- *   "http(s)://", "file://"    → no suggestions (opaque URLs).
+ *   "<word>", "oci://…"        → hub ref autocomplete (fuzzy substring over registered refs).
+ *   "<ref>@<partial>"          → version list for that ref.
+ *   "http(s)://", "file://"    → no suggestions (opaque URLs the author types verbatim).
+ *
+ * `oci://` is deliberately NOT opaque: without an `@` it routes to the ref
+ * search below, whose query is the whole typed prefix — so the hub fuzzy-matches
+ * `oci://ghcr.io/aws/telo-s3` as readily as a bare `s3`.
  *
  * `valueStartColumn` is forwarded onto every result so the host can replace
  * the whole typed value, not just the trailing word (Monaco / VSCode word
@@ -33,11 +38,13 @@ export async function importSourceCompletions(prefix, valueStartColumn, adapter)
     if (isRelativeShape) {
         return relativePathCompletions(prefix, valueStartColumn, adapter);
     }
-    const atIdx = prefix.indexOf("@");
+    // The version (or `@sha256:` digest) is the trailing `@`-segment, so split on
+    // the LAST `@` — a digest-pinned ref keeps everything before it as the ref.
+    const atIdx = prefix.lastIndexOf("@");
     if (atIdx > 0) {
         return versionCompletions(prefix, atIdx, valueStartColumn, adapter);
     }
-    return registrySearchCompletions(prefix, valueStartColumn, adapter);
+    return refSearchCompletions(prefix, valueStartColumn, adapter);
 }
 async function relativePathCompletions(prefix, valueStartColumn, adapter) {
     // Empty prefix → seed `./` and `../` so the user gets traction; otherwise
@@ -95,52 +102,63 @@ async function relativePathCompletions(prefix, valueStartColumn, adapter) {
         };
     }));
 }
-async function registrySearchCompletions(prefix, valueStartColumn, adapter) {
-    // The registry's `q` filter ILIKEs against name / namespace / description —
-    // it doesn't know about the `<namespace>/<name>` shape. Once the user has
-    // typed a `/`, sending the literal `std/htt` as `q` matches nothing because
-    // the slash is not in any of those columns. Split here so `q` carries just
-    // the bit that looks like a name, and apply the namespace constraint
-    // client-side.
-    const slashIdx = prefix.indexOf("/");
-    const namespacePart = slashIdx >= 0 ? prefix.slice(0, slashIdx) : "";
-    const namePart = slashIdx >= 0 ? prefix.slice(slashIdx + 1) : prefix;
-    const hits = await adapter.searchRegistry(namePart);
-    const filtered = namespacePart
-        ? hits.filter((h) => h.namespace.startsWith(namespacePart))
-        : hits;
-    return filtered.slice(0, REGISTRY_LIMIT).map((m) => {
-        const id = `${m.namespace}/${m.name}@${m.version}`;
+async function refSearchCompletions(prefix, valueStartColumn, adapter) {
+    // The whole typed prefix is the fuzzy query — the hub matches it as a
+    // substring over each registered ref, so no client-side splitting is needed
+    // (and `oci://ghcr.io/aws/telo-s3` matches without mangling the `//`).
+    const hits = await adapter.searchRefs(prefix);
+    return hits.slice(0, REF_LIMIT).map((m) => {
+        // Seed the pinned `ref@latestVersion` so the completion is directly usable;
+        // the author can still narrow the version afterwards (the `@` re-triggers
+        // version completion).
+        const id = m.latestVersion ? `${m.ref}@${m.latestVersion}` : m.ref;
+        const name = refDisplayName(m.ref);
+        // Lead the label with the module name so the interesting part isn't cut off
+        // behind the transport/host boilerplate (`oci://ghcr.io/telorun/…`). The
+        // full ref moves to `detail`, and `insertText`/`filterText` stay the ref so
+        // acceptance still inserts it and a fully-typed ref still filters.
         return {
-            label: id,
+            label: m.latestVersion ? `${name}@${m.latestVersion}` : name,
             kind: "module",
-            detail: m.description ?? "registry module",
+            detail: m.description ?? m.ref,
+            documentation: m.description ? m.ref : undefined,
             insertText: id,
             filterText: id,
             replaceFromColumn: valueStartColumn,
         };
     });
 }
+/** The `org/name` tail of a location ref: its last two path segments, with the
+ *  transport scheme (`oci://`, `https://`, …) and registry host dropped.
+ *  `oci://ghcr.io/telorun/telo-console` → `telorun/telo-console`; `std/console`
+ *  → `std/console`. Falls back to fewer segments (or the whole ref) when there
+ *  aren't two. */
+function refDisplayName(ref) {
+    const withoutScheme = ref.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "");
+    const segments = withoutScheme.split("/").filter(Boolean);
+    return segments.slice(-2).join("/") || ref;
+}
 async function versionCompletions(prefix, atIdx, valueStartColumn, adapter) {
-    const beforeAt = prefix.slice(0, atIdx);
+    const ref = prefix.slice(0, atIdx);
     const partialVersion = prefix.slice(atIdx + 1);
-    const slashIdx = beforeAt.indexOf("/");
-    if (slashIdx <= 0 || slashIdx === beforeAt.length - 1)
+    if (ref === "")
         return [];
-    const namespace = beforeAt.slice(0, slashIdx);
-    const name = beforeAt.slice(slashIdx + 1);
-    const versions = await adapter.listRegistryVersions(namespace, name);
+    const versions = await adapter.listVersionsForRef(ref);
     const matches = versions.filter((v) => v.startsWith(partialVersion));
     return matches.map((version, idx) => {
-        const id = `${namespace}/${name}@${version}`;
+        const id = `${ref}@${version}`;
+        // The ref is already typed and visible on the line, so the label is just the
+        // version — no point repeating the full ref on every row. `insertText` /
+        // `filterText` stay the full id so acceptance replaces the whole value and
+        // the already-typed ref prefix keeps the item in the filtered set.
         return {
-            label: id,
+            label: version,
             kind: "value",
-            detail: idx === 0 ? "latest" : `v${version}`,
+            detail: idx === 0 ? "latest" : undefined,
             insertText: id,
             filterText: id,
             replaceFromColumn: valueStartColumn,
-            // Preserve registry's ordering (newest first) so the latest version is
+            // Preserve the hub's ordering (newest first) so the latest version is
             // suggested at the top regardless of lexical comparison.
             sortText: String(idx).padStart(4, "0"),
         };

package/dist/types.d.ts

@@ -18,16 +18,22 @@ export interface CompletionResult {
      *  word boundary would not include in the replaced range. */
     replaceFromColumn?: number;
 }
-export interface RegistryModule {
-    namespace: string;
-    name: string;
-    version: string;
+/** A candidate module ref surfaced by the hub's `/refs` lexical autocomplete.
+ *  Identity is the location ref, never `namespace/name` — an OCI module has no
+ *  addressable `namespace/name`. `latestVersion` seeds a pinned `ref@version`
+ *  insert so a picked completion is directly usable. */
+export interface HubRef {
+    ref: string;
+    latestVersion: string;
     description?: string;
 }
 /** Host-supplied bridge that lets ide-support reach the filesystem and the
- *  module registry without depending on Node, Tauri, or vscode APIs. Each
+ *  federated telo hub without depending on Node, Tauri, or vscode APIs. Each
  *  host (VSCode extension, Telo editor) builds an adapter scoped to the
- *  currently-edited manifest before calling `buildCompletions`. */
+ *  currently-edited manifest before calling `buildCompletions`. Hub lookups are
+ *  ref-keyed: the hub aggregates modules across every transport (OCI, HTTP,
+ *  direct URL), so completion speaks its `/refs` + `/module/versions` verbs
+ *  rather than any single registry. */
 export interface IdeEnvironmentAdapter {
     /** Subdirectory names within `relPath` (resolved against the manifest's
      *  directory). Returns [] if the path doesn't exist or isn't a directory.
@@ -36,12 +42,15 @@ export interface IdeEnvironmentAdapter {
     /** True iff `<relPath>/telo.yaml` exists relative to the manifest dir.
      *  Used to mark directories that are valid import targets. */
     hasManifest(relPath: string): Promise<boolean>;
-    /** Free-text search against the configured module registry. Matches against
-     *  name, namespace, and description. Empty `query` should return the full
-     *  (capped) catalog. */
-    searchRegistry(query: string): Promise<RegistryModule[]>;
-    /** All published versions for a module, newest first. */
-    listRegistryVersions(namespace: string, name: string): Promise<string[]>;
+    /** Fuzzy lexical ref autocomplete against the configured telo hub
+     *  (`GET /refs?q=`). The query is matched as a substring over every
+     *  registered ref, so a bare token (`youtrack`) hits the same ref as its full
+     *  `oci://…` form. Best-effort — hosts swallow network errors and return []. */
+    searchRefs(query: string): Promise<HubRef[]>;
+    /** All tracked versions for a location ref, newest first
+     *  (`GET /module/versions?ref=`). The browser cannot call OCI `tags/list`;
+     *  the hub holds them from ingest. */
+    listVersionsForRef(ref: string): Promise<string[]>;
 }
 export interface NormalizedDiagnostic {
     range: Range;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAGzE,YAAY,EACV,QAAQ,EACR,KAAK,EACL,kBAAkB,EAClB,aAAa,GACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAEpG,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,YAAY,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEjG,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;iEAG6D;IAC7D,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;mEAGmE;AACnE,MAAM,WAAW,qBAAqB;IACpC;;2DAEuD;IACvD,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACpD;kEAC8D;IAC9D,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C;;4BAEwB;IACxB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IACzD,yDAAyD;IACzD,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC1E;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,cAAc,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnE;;;0EAGsE;IACtE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAGzE,YAAY,EACV,QAAQ,EACR,KAAK,EACL,kBAAkB,EAClB,aAAa,GACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAEpG,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,YAAY,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEjG,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;iEAG6D;IAC7D,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;wDAGwD;AACxD,MAAM,WAAW,MAAM;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;uCAMuC;AACvC,MAAM,WAAW,qBAAqB;IACpC;;2DAEuD;IACvD,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACpD;kEAC8D;IAC9D,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C;;;oFAGgF;IAChF,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7C;;0CAEsC;IACtC,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,cAAc,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnE;;;0EAGsE;IACtE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/ide-support",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Editor-host-agnostic IDE support (completions, diagnostic normalization) for Telo manifests.",
   "keywords": [
     "telo",

package/src/completions/import-source.ts

@@ -1,8 +1,9 @@
 import type { CompletionResult, IdeEnvironmentAdapter } from "../types.js";
 
-/** Maximum registry hits to surface in a single completion request.
- *  Keeps the popover scannable when a broad `q=` query matches the catalog. */
-const REGISTRY_LIMIT = 50;
+/** Maximum ref hits to surface in a single completion request. Keeps the
+ *  popover scannable when a broad `q=` query matches many registered refs
+ *  (the hub already caps `/refs` server-side; this is a client backstop). */
+const REF_LIMIT = 50;
 
 /** Caps the number of directory entries we probe with `hasManifest` per
  *  request. Each probe is a host-side filesystem stat; the popover would not
@@ -17,9 +18,13 @@ const PATH_PROBE_LIMIT = 50;
  * Branches by prefix shape:
  *   ""                         → relative dirs under the manifest dir, plus `./` / `../` seeds.
  *   "./..", "../", "/..."      → subdirs of the typed path (any subdir; existing manifest gets a hint).
- *   "<word>"                   → registry search by free-text.
- *   "<ns>/<name>@<partial>"    → version list for that module.
- *   "http(s)://", "file://"    → no suggestions (opaque URLs).
+ *   "<word>", "oci://…"        → hub ref autocomplete (fuzzy substring over registered refs).
+ *   "<ref>@<partial>"          → version list for that ref.
+ *   "http(s)://", "file://"    → no suggestions (opaque URLs the author types verbatim).
+ *
+ * `oci://` is deliberately NOT opaque: without an `@` it routes to the ref
+ * search below, whose query is the whole typed prefix — so the hub fuzzy-matches
+ * `oci://ghcr.io/aws/telo-s3` as readily as a bare `s3`.
  *
  * `valueStartColumn` is forwarded onto every result so the host can replace
  * the whole typed value, not just the trailing word (Monaco / VSCode word
@@ -46,12 +51,14 @@ export async function importSourceCompletions(
     return relativePathCompletions(prefix, valueStartColumn, adapter);
   }
 
-  const atIdx = prefix.indexOf("@");
+  // The version (or `@sha256:` digest) is the trailing `@`-segment, so split on
+  // the LAST `@` — a digest-pinned ref keeps everything before it as the ref.
+  const atIdx = prefix.lastIndexOf("@");
   if (atIdx > 0) {
     return versionCompletions(prefix, atIdx, valueStartColumn, adapter);
   }
 
-  return registrySearchCompletions(prefix, valueStartColumn, adapter);
+  return refSearchCompletions(prefix, valueStartColumn, adapter);
 }
 
 async function relativePathCompletions(
@@ -120,32 +127,31 @@ async function relativePathCompletions(
   );
 }
 
-async function registrySearchCompletions(
+async function refSearchCompletions(
   prefix: string,
   valueStartColumn: number,
   adapter: IdeEnvironmentAdapter,
 ): Promise<CompletionResult[]> {
-  // The registry's `q` filter ILIKEs against name / namespace / description —
-  // it doesn't know about the `<namespace>/<name>` shape. Once the user has
-  // typed a `/`, sending the literal `std/htt` as `q` matches nothing because
-  // the slash is not in any of those columns. Split here so `q` carries just
-  // the bit that looks like a name, and apply the namespace constraint
-  // client-side.
-  const slashIdx = prefix.indexOf("/");
-  const namespacePart = slashIdx >= 0 ? prefix.slice(0, slashIdx) : "";
-  const namePart = slashIdx >= 0 ? prefix.slice(slashIdx + 1) : prefix;
-
-  const hits = await adapter.searchRegistry(namePart);
-  const filtered = namespacePart
-    ? hits.filter((h) => h.namespace.startsWith(namespacePart))
-    : hits;
-
-  return filtered.slice(0, REGISTRY_LIMIT).map((m) => {
-    const id = `${m.namespace}/${m.name}@${m.version}`;
+  // The whole typed prefix is the fuzzy query — the hub matches it as a
+  // substring over each registered ref, so no client-side splitting is needed
+  // (and `oci://ghcr.io/aws/telo-s3` matches without mangling the `//`).
+  const hits = await adapter.searchRefs(prefix);
+
+  return hits.slice(0, REF_LIMIT).map((m) => {
+    // Seed the pinned `ref@latestVersion` so the completion is directly usable;
+    // the author can still narrow the version afterwards (the `@` re-triggers
+    // version completion).
+    const id = m.latestVersion ? `${m.ref}@${m.latestVersion}` : m.ref;
+    const name = refDisplayName(m.ref);
+    // Lead the label with the module name so the interesting part isn't cut off
+    // behind the transport/host boilerplate (`oci://ghcr.io/telorun/…`). The
+    // full ref moves to `detail`, and `insertText`/`filterText` stay the ref so
+    // acceptance still inserts it and a fully-typed ref still filters.
     return {
-      label: id,
+      label: m.latestVersion ? `${name}@${m.latestVersion}` : name,
       kind: "module",
-      detail: m.description ?? "registry module",
+      detail: m.description ?? m.ref,
+      documentation: m.description ? m.ref : undefined,
       insertText: id,
       filterText: id,
       replaceFromColumn: valueStartColumn,
@@ -153,32 +159,44 @@ async function registrySearchCompletions(
   });
 }
 
+/** The `org/name` tail of a location ref: its last two path segments, with the
+ *  transport scheme (`oci://`, `https://`, …) and registry host dropped.
+ *  `oci://ghcr.io/telorun/telo-console` → `telorun/telo-console`; `std/console`
+ *  → `std/console`. Falls back to fewer segments (or the whole ref) when there
+ *  aren't two. */
+function refDisplayName(ref: string): string {
+  const withoutScheme = ref.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "");
+  const segments = withoutScheme.split("/").filter(Boolean);
+  return segments.slice(-2).join("/") || ref;
+}
+
 async function versionCompletions(
   prefix: string,
   atIdx: number,
   valueStartColumn: number,
   adapter: IdeEnvironmentAdapter,
 ): Promise<CompletionResult[]> {
-  const beforeAt = prefix.slice(0, atIdx);
+  const ref = prefix.slice(0, atIdx);
   const partialVersion = prefix.slice(atIdx + 1);
-  const slashIdx = beforeAt.indexOf("/");
-  if (slashIdx <= 0 || slashIdx === beforeAt.length - 1) return [];
+  if (ref === "") return [];
 
-  const namespace = beforeAt.slice(0, slashIdx);
-  const name = beforeAt.slice(slashIdx + 1);
-  const versions = await adapter.listRegistryVersions(namespace, name);
+  const versions = await adapter.listVersionsForRef(ref);
 
   const matches = versions.filter((v) => v.startsWith(partialVersion));
   return matches.map((version, idx) => {
-    const id = `${namespace}/${name}@${version}`;
+    const id = `${ref}@${version}`;
+    // The ref is already typed and visible on the line, so the label is just the
+    // version — no point repeating the full ref on every row. `insertText` /
+    // `filterText` stay the full id so acceptance replaces the whole value and
+    // the already-typed ref prefix keeps the item in the filtered set.
     return {
-      label: id,
+      label: version,
       kind: "value",
-      detail: idx === 0 ? "latest" : `v${version}`,
+      detail: idx === 0 ? "latest" : undefined,
       insertText: id,
       filterText: id,
       replaceFromColumn: valueStartColumn,
-      // Preserve registry's ordering (newest first) so the latest version is
+      // Preserve the hub's ordering (newest first) so the latest version is
       // suggested at the top regardless of lexical comparison.
       sortText: String(idx).padStart(4, "0"),
     };

package/src/types.ts

@@ -31,17 +31,23 @@ export interface CompletionResult {
   replaceFromColumn?: number;
 }
 
-export interface RegistryModule {
-  namespace: string;
-  name: string;
-  version: string;
+/** A candidate module ref surfaced by the hub's `/refs` lexical autocomplete.
+ *  Identity is the location ref, never `namespace/name` — an OCI module has no
+ *  addressable `namespace/name`. `latestVersion` seeds a pinned `ref@version`
+ *  insert so a picked completion is directly usable. */
+export interface HubRef {
+  ref: string;
+  latestVersion: string;
   description?: string;
 }
 
 /** Host-supplied bridge that lets ide-support reach the filesystem and the
- *  module registry without depending on Node, Tauri, or vscode APIs. Each
+ *  federated telo hub without depending on Node, Tauri, or vscode APIs. Each
  *  host (VSCode extension, Telo editor) builds an adapter scoped to the
- *  currently-edited manifest before calling `buildCompletions`. */
+ *  currently-edited manifest before calling `buildCompletions`. Hub lookups are
+ *  ref-keyed: the hub aggregates modules across every transport (OCI, HTTP,
+ *  direct URL), so completion speaks its `/refs` + `/module/versions` verbs
+ *  rather than any single registry. */
 export interface IdeEnvironmentAdapter {
   /** Subdirectory names within `relPath` (resolved against the manifest's
    *  directory). Returns [] if the path doesn't exist or isn't a directory.
@@ -50,12 +56,15 @@ export interface IdeEnvironmentAdapter {
   /** True iff `<relPath>/telo.yaml` exists relative to the manifest dir.
    *  Used to mark directories that are valid import targets. */
   hasManifest(relPath: string): Promise<boolean>;
-  /** Free-text search against the configured module registry. Matches against
-   *  name, namespace, and description. Empty `query` should return the full
-   *  (capped) catalog. */
-  searchRegistry(query: string): Promise<RegistryModule[]>;
-  /** All published versions for a module, newest first. */
-  listRegistryVersions(namespace: string, name: string): Promise<string[]>;
+  /** Fuzzy lexical ref autocomplete against the configured telo hub
+   *  (`GET /refs?q=`). The query is matched as a substring over every
+   *  registered ref, so a bare token (`youtrack`) hits the same ref as its full
+   *  `oci://…` form. Best-effort — hosts swallow network errors and return []. */
+  searchRefs(query: string): Promise<HubRef[]>;
+  /** All tracked versions for a location ref, newest first
+   *  (`GET /module/versions?ref=`). The browser cannot call OCI `tags/list`;
+   *  the hub holds them from ingest. */
+  listVersionsForRef(ref: string): Promise<string[]>;
 }
 
 export interface NormalizedDiagnostic {