@telorun/ide-support 0.5.0 → 0.7.0

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

@@ -1,4 +1,4 @@
-import type { CompletionResult, IdeEnvironmentAdapter } from "../types.js";
+import type { CompletionResult, IdeEnvironmentAdapter, ReplaceRange } from "../types.js";
 /**
  * Completions for an import source — an `imports:` map entry on a module doc
  * (either the scalar shorthand `Alias: <src>` or the `source:` under the
@@ -7,13 +7,17 @@ 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).
  *
- * `valueStartColumn` is forwarded onto every result so the host can replace
- * the whole typed value, not just the trailing word (Monaco / VSCode word
- * boundaries don't cross `/` or `@`).
+ * `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`.
+ *
+ * `replaceRange` is forwarded onto every result so the host replaces the whole
+ * value, not just the trailing word (Monaco / VSCode word boundaries don't
+ * cross `/` or `@`).
  */
-export declare function importSourceCompletions(prefix: string, valueStartColumn: number, adapter: IdeEnvironmentAdapter | undefined): Promise<CompletionResult[]>;
+export declare function importSourceCompletions(prefix: string, replaceRange: ReplaceRange, adapter: IdeEnvironmentAdapter | undefined): Promise<CompletionResult[]>;
 //# sourceMappingURL=import-source.d.ts.map

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,YAAY,EAAE,MAAM,aAAa,CAAC;AAYzF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,YAAY,EAC1B,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,15 +14,19 @@ 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).
  *
- * `valueStartColumn` is forwarded onto every result so the host can replace
- * the whole typed value, not just the trailing word (Monaco / VSCode word
- * boundaries don't cross `/` or `@`).
+ * `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`.
+ *
+ * `replaceRange` is forwarded onto every result so the host replaces the whole
+ * value, not just the trailing word (Monaco / VSCode word boundaries don't
+ * cross `/` or `@`).
  */
-export async function importSourceCompletions(prefix, valueStartColumn, adapter) {
+export async function importSourceCompletions(prefix, replaceRange, adapter) {
     if (!adapter)
         return [];
     if (prefix.startsWith("http://") ||
@@ -31,15 +36,17 @@ export async function importSourceCompletions(prefix, valueStartColumn, adapter)
     }
     const isRelativeShape = prefix === "" || prefix.startsWith(".") || prefix.startsWith("/");
     if (isRelativeShape) {
-        return relativePathCompletions(prefix, valueStartColumn, adapter);
+        return relativePathCompletions(prefix, replaceRange, 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 versionCompletions(prefix, atIdx, replaceRange, adapter);
     }
-    return registrySearchCompletions(prefix, valueStartColumn, adapter);
+    return refSearchCompletions(prefix, replaceRange, adapter);
 }
-async function relativePathCompletions(prefix, valueStartColumn, adapter) {
+async function relativePathCompletions(prefix, replaceRange, adapter) {
     // Empty prefix → seed `./` and `../` so the user gets traction; otherwise
     // we'd return an unfiltered dump of the manifest directory which is rarely
     // what the user wants for an import source.
@@ -50,14 +57,14 @@ async function relativePathCompletions(prefix, valueStartColumn, adapter) {
                 kind: "folder",
                 insertText: "./",
                 sortText: "0_./",
-                replaceFromColumn: valueStartColumn,
+                replaceRange,
             },
             {
                 label: "../",
                 kind: "folder",
                 insertText: "../",
                 sortText: "0_../",
-                replaceFromColumn: valueStartColumn,
+                replaceRange,
             },
         ];
     }
@@ -88,59 +95,70 @@ async function relativePathCompletions(prefix, valueStartColumn, adapter) {
             detail: isModule ? "telo module" : "folder",
             insertText: fullPath,
             filterText: fullPath,
-            replaceFromColumn: valueStartColumn,
+            replaceRange,
             // Modules sort above plain folders so they surface first when the user
             // is browsing a `modules/` tree mixed with non-Telo siblings.
             sortText: isModule ? `0_${name}` : `1_${name}`,
         };
     }));
 }
-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, replaceRange, 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,
+            replaceRange,
         };
     });
 }
-async function versionCompletions(prefix, atIdx, valueStartColumn, adapter) {
-    const beforeAt = prefix.slice(0, atIdx);
+/** 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, replaceRange, adapter) {
+    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
+            replaceRange,
+            // 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/completions/resolve-node.d.ts

@@ -0,0 +1,50 @@
+import { type AstDocument, type AstMap, type AstNode, type CelSegment, type Position } from "@telorun/analyzer";
+/** The cursor's resolved position against the read-only AST. `locate` produces
+ *  this; `detect-context` maps it onto a `CompletionCtx`. Structure comes from
+ *  the AST; the cursor *column* is used only to resolve empty-space (blank /
+ *  trailing-indent) key positions, where indentation is the sole signal for
+ *  "which container am I typing into". */
+export interface ResolvedCursor {
+    docIndex: number;
+    /** Top-level `kind:` value of the cursor's document, when present. */
+    docKind?: string;
+    slot: "key" | "value";
+    /** Value slot: ancestor keys + the field key (last element is the field).
+     *  Key slot: the container map's ancestor key chain. */
+    path: string[];
+    node?: AstNode;
+    container?: AstMap;
+    replaceRange?: {
+        start: Position;
+        end: Position;
+    };
+    /** Value slot: text from the value start up to the cursor. */
+    prefix?: string;
+    /** Value slot: true when whitespace separates the key's colon from the value
+     *  (distinguishes `Console: ` — a value — from `Tiny:` — a bare header). */
+    spaceAfterColon?: boolean;
+    /** Value slot: the value of a sibling `kind:` in the same map (object-form
+     *  ref name completion). */
+    siblingKind?: string;
+    /** Key slot: keys already present in the container (the key under the cursor
+     *  excluded so it still suggests itself). */
+    existingKeys?: Set<string>;
+    /** Key slot: the kind of the nearest enclosing inline resource (or the root
+     *  resource), whose schema the prop keys are completed against. Falls back to
+     *  the document kind at the root. */
+    resourceKind?: string;
+    /** Key slot: number of `path` segments that reach `resourceKind`'s map, so
+     *  the schema-relative path is `path.slice(resourceDepth)`. */
+    resourceDepth?: number;
+    /** Set when the cursor sits inside a CEL body (closed or open). Populated for
+     *  a future CEL-completion feature; this refactor does not consume it. */
+    cel?: {
+        segment: CelSegment;
+        offset: number;
+    };
+}
+export declare function scalarString(node: AstNode | undefined): string | undefined;
+/** Resolve `(line, character)` against the AST (Approach B: AST for structure,
+ *  cursor column only to place empty-space key positions). */
+export declare function resolveNodeAtPosition(text: string, docs: AstDocument[], line: number, character: number): ResolvedCursor | undefined;
+//# sourceMappingURL=resolve-node.d.ts.map

package/dist/completions/resolve-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-node.d.ts","sourceRoot":"","sources":["../../src/completions/resolve-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,MAAM,EACX,KAAK,OAAO,EAEZ,KAAK,UAAU,EACf,KAAK,QAAQ,EACd,MAAM,mBAAmB,CAAC;AAE3B;;;;0CAI0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC;IACtB;4DACwD;IACxD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE;QAAE,KAAK,EAAE,QAAQ,CAAC;QAAC,GAAG,EAAE,QAAQ,CAAA;KAAE,CAAC;IAClD,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;gFAC4E;IAC5E,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;gCAC4B;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;iDAC6C;IAC7C,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B;;yCAEqC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;mEAC+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;8EAC0E;IAC1E,GAAG,CAAC,EAAE;QAAE,OAAO,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAMD,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAG1E;AAwPD;8DAC8D;AAC9D,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,WAAW,EAAE,EACnB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,cAAc,GAAG,SAAS,CA4F5B"}

package/dist/completions/resolve-node.js

@@ -0,0 +1,269 @@
+import { buildLineOffsets, offsetToPosition, } from "@telorun/analyzer";
+function within(range, offset) {
+    return offset >= range[0] && offset <= range[1];
+}
+export function scalarString(node) {
+    if (node?.kind === "scalar" && typeof node.value === "string")
+        return node.value;
+    return undefined;
+}
+/** The `kind:` value of a document's root map, if any. */
+function docKindOf(doc) {
+    if (doc.root?.kind !== "map")
+        return undefined;
+    for (const pair of doc.root.entries) {
+        if (scalarString(pair.key) === "kind")
+            return scalarString(pair.value);
+    }
+    return undefined;
+}
+/** Value of a sibling `kind:` entry in `map`, for object-form ref detection. */
+function siblingKindOf(map) {
+    for (const pair of map.entries) {
+        if (scalarString(pair.key) === "kind")
+            return scalarString(pair.value);
+    }
+    return undefined;
+}
+/** The map's `kind:` value when it names a resource kind (`Alias.Kind`), i.e.
+ *  the map is an inline resource. A prop-key position inside such a map is
+ *  completed against *this* kind's schema, not the outer ref slot's. */
+function resourceKindOf(map) {
+    const kind = siblingKindOf(map);
+    return kind && /^\w+\.\w+/.test(kind) ? kind : undefined;
+}
+function enter(scope, map, ancestorsLen) {
+    const kind = resourceKindOf(map);
+    return kind ? { kind, depth: ancestorsLen } : scope;
+}
+function descend(node, ancestors, offset, scope) {
+    if (node.kind === "map") {
+        const mapScope = enter(scope, node, ancestors.length);
+        for (const pair of node.entries) {
+            const keyName = scalarString(pair.key);
+            if (within(pair.key.range, offset)) {
+                return {
+                    type: "key",
+                    container: node,
+                    path: ancestors,
+                    keyNode: pair.key,
+                    keyName,
+                    scope: mapScope,
+                };
+            }
+            if (pair.value && within(pair.value.range, offset)) {
+                const childAncestors = keyName != null ? [...ancestors, keyName] : ancestors;
+                if (pair.value.kind === "map" || pair.value.kind === "seq") {
+                    return descend(pair.value, childAncestors, offset, mapScope) ?? { type: "empty" };
+                }
+                return {
+                    type: "value",
+                    container: node,
+                    path: ancestors,
+                    keyName,
+                    keyEnd: pair.key.range[1],
+                    valueNode: pair.value,
+                };
+            }
+        }
+        return undefined;
+    }
+    if (node.kind === "seq") {
+        // Sequence items are transparent to the key path (mirrors the schema
+        // walker, which auto-descends arrays).
+        for (const item of node.items) {
+            if (within(item.range, offset)) {
+                if (item.kind === "map" || item.kind === "seq") {
+                    return descend(item, ancestors, offset, scope) ?? { type: "empty" };
+                }
+                // A bare scalar list item (`targets:\n  - One`) has no enclosing map of
+                // keyed siblings — leave `container` undefined rather than treating the
+                // seq as a map.
+                return { type: "value", container: undefined, path: ancestors, keyEnd: item.range[0], valueNode: item };
+            }
+        }
+        return undefined;
+    }
+    return undefined;
+}
+function collectScopes(node, ancestors, scope, lineOffsets, maps, pairs) {
+    if (node.kind === "map") {
+        const mapScope = enter(scope, node, ancestors.length);
+        const keys = new Set();
+        let childColumn = -1;
+        for (const pair of node.entries) {
+            const keyName = scalarString(pair.key);
+            if (keyName != null)
+                keys.add(keyName);
+            if (childColumn < 0)
+                childColumn = offsetToPosition(pair.key.range[0], lineOffsets).character;
+        }
+        if (childColumn >= 0) {
+            maps.push({ path: ancestors, childColumn, keys, rangeStart: node.range[0], scope: mapScope });
+        }
+        for (const pair of node.entries) {
+            const keyName = scalarString(pair.key);
+            const fullPath = keyName != null ? [...ancestors, keyName] : ancestors;
+            const childKeys = new Set();
+            if (pair.value?.kind === "map") {
+                for (const p of pair.value.entries) {
+                    const k = scalarString(p.key);
+                    if (k != null)
+                        childKeys.add(k);
+                }
+            }
+            pairs.push({
+                path: fullPath,
+                keyColumn: offsetToPosition(pair.key.range[0], lineOffsets).character,
+                keyOffset: pair.key.range[0],
+                childKeys,
+                scope: mapScope,
+            });
+            if (pair.value)
+                collectScopes(pair.value, fullPath, mapScope, lineOffsets, maps, pairs);
+        }
+    }
+    else if (node.kind === "seq") {
+        for (const item of node.items)
+            collectScopes(item, ancestors, scope, lineOffsets, maps, pairs);
+    }
+}
+/** Resolve the container a new key at `cursorColumn` belongs to. Prefers an
+ *  existing sibling level (a map whose child keys sit at exactly `cursorColumn`);
+ *  otherwise nests under the nearest-preceding shallower key. */
+function columnSearch(root, cursorColumn, cursorOffset, lineOffsets) {
+    const maps = [];
+    const pairs = [];
+    collectScopes(root, [], { depth: 0 }, lineOffsets, maps, pairs);
+    // Sibling level: a map whose children already sit at the cursor's column.
+    let sibling;
+    for (const m of maps) {
+        if (m.childColumn === cursorColumn && m.rangeStart < cursorOffset) {
+            if (!sibling || m.rangeStart > sibling.rangeStart)
+                sibling = m;
+        }
+    }
+    if (sibling)
+        return { path: sibling.path, existingKeys: sibling.keys, scope: sibling.scope };
+    // Nest under the nearest-preceding key shallower than the cursor.
+    let nest;
+    for (const p of pairs) {
+        if (p.keyColumn < cursorColumn && p.keyOffset < cursorOffset) {
+            if (!nest ||
+                p.keyColumn > nest.keyColumn ||
+                (p.keyColumn === nest.keyColumn && p.keyOffset > nest.keyOffset)) {
+                nest = p;
+            }
+        }
+    }
+    if (nest)
+        return { path: nest.path, existingKeys: nest.childKeys, scope: nest.scope };
+    return { path: [], existingKeys: new Set(), scope: { depth: 0 } };
+}
+// ---------------------------------------------------------------------------
+function selectDoc(docs, offset) {
+    let best = -1;
+    for (let i = 0; i < docs.length; i++) {
+        if (docs[i].range[0] <= offset)
+            best = i;
+    }
+    return best < 0 ? (docs.length > 0 ? 0 : -1) : best;
+}
+function celAt(node, offset) {
+    for (const segment of node.celSegments()) {
+        if (offset >= segment.range[0] && offset <= segment.range[1])
+            return { segment, offset };
+    }
+    return undefined;
+}
+/** Resolve `(line, character)` against the AST (Approach B: AST for structure,
+ *  cursor column only to place empty-space key positions). */
+export function resolveNodeAtPosition(text, docs, line, character) {
+    if (docs.length === 0)
+        return undefined;
+    const lineOffsets = buildLineOffsets(text);
+    const offset = (lineOffsets[line] ?? 0) + character;
+    const toPos = (o) => offsetToPosition(o, lineOffsets);
+    const docIndex = selectDoc(docs, offset);
+    if (docIndex < 0)
+        return undefined;
+    const doc = docs[docIndex];
+    const docKind = docKindOf(doc);
+    const found = doc.root ? descend(doc.root, [], offset, { depth: 0 }) : undefined;
+    // Cursor sits on an existing map key → key/prop-key position.
+    if (found?.type === "key") {
+        const existingKeys = new Set();
+        for (const pair of found.container.entries) {
+            const k = scalarString(pair.key);
+            if (k != null && k !== found.keyName)
+                existingKeys.add(k);
+        }
+        return {
+            docIndex,
+            docKind,
+            slot: "key",
+            path: found.path,
+            node: found.keyNode,
+            replaceRange: { start: toPos(found.keyNode.range[0]), end: toPos(found.keyNode.range[1]) },
+            container: found.container,
+            existingKeys,
+            resourceKind: found.scope.kind,
+            resourceDepth: found.scope.depth,
+        };
+    }
+    // Cursor sits on a scalar value.
+    if (found?.type === "value" && found.valueNode.kind === "scalar") {
+        const value = found.valueNode;
+        const cel = celAt(value, offset);
+        // A bare identifier on its own line with no colon is a partial *key* being
+        // typed as a first child (yaml parses it as the parent's value). Route to a
+        // key position via column search — the documented cursor-line carve-out.
+        const lineText = text.slice(lineOffsets[line] ?? 0, lineOffsets[line + 1] ?? text.length);
+        const isPartialKey = typeof value.value === "string" &&
+            !lineText.includes(":") &&
+            /^\s*[A-Za-z_][\w-]*\s*$/.test(lineText) &&
+            toPos(value.range[0]).line !== toPos(found.keyEnd).line;
+        if (isPartialKey && doc.root) {
+            const col = toPos(value.range[0]).character;
+            const { path, existingKeys, scope } = columnSearch(doc.root, col, offset, lineOffsets);
+            return {
+                docIndex,
+                docKind,
+                slot: "key",
+                path,
+                container: found.container,
+                existingKeys,
+                resourceKind: scope.kind,
+                resourceDepth: scope.depth,
+            };
+        }
+        const clampedEnd = Math.min(offset, value.range[1]);
+        return {
+            docIndex,
+            docKind,
+            slot: "value",
+            path: found.keyName != null ? [...found.path, found.keyName] : found.path,
+            node: value,
+            container: found.container,
+            prefix: text.slice(value.range[0], clampedEnd),
+            spaceAfterColon: value.range[0] - found.keyEnd >= 2,
+            siblingKind: found.container ? siblingKindOf(found.container) : undefined,
+            replaceRange: { start: toPos(value.range[0]), end: toPos(value.range[1]) },
+            cel,
+        };
+    }
+    // Empty space (blank line, trailing indent, empty document) → key position,
+    // resolved by cursor column.
+    const resolution = doc.root
+        ? columnSearch(doc.root, character, offset, lineOffsets)
+        : { path: [], existingKeys: new Set(), scope: { depth: 0 } };
+    return {
+        docIndex,
+        docKind,
+        slot: "key",
+        path: resolution.path,
+        existingKeys: resolution.existingKeys,
+        resourceKind: resolution.scope.kind,
+        resourceDepth: resolution.scope.depth,
+    };
+}

package/dist/completions/valid-capabilities.d.ts

@@ -1,2 +1,5 @@
 export declare const CAPABILITY_VALUES: readonly ["Telo.Service", "Telo.Runnable", "Telo.Invocable", "Telo.Provider", "Telo.Mount", "Telo.Type"];
+/** One-line role summary per capability, surfaced on hover. Kept in sync with
+ *  the capability list in `CLAUDE.md` / the kernel builtins. */
+export declare const CAPABILITY_DOCS: Record<string, string>;
 //# sourceMappingURL=valid-capabilities.d.ts.map

package/dist/completions/valid-capabilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"valid-capabilities.d.ts","sourceRoot":"","sources":["../../src/completions/valid-capabilities.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,0GAOpB,CAAC"}
+{"version":3,"file":"valid-capabilities.d.ts","sourceRoot":"","sources":["../../src/completions/valid-capabilities.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,0GAOpB,CAAC;AAEX;gEACgE;AAChE,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAOlD,CAAC"}

package/dist/completions/valid-capabilities.js

@@ -6,3 +6,13 @@ export const CAPABILITY_VALUES = [
     "Telo.Mount",
     "Telo.Type",
 ];
+/** One-line role summary per capability, surfaced on hover. Kept in sync with
+ *  the capability list in `CLAUDE.md` / the kernel builtins. */
+export const CAPABILITY_DOCS = {
+    "Telo.Service": "Long-lived resource: `init()` + optional `teardown()` (servers, pools).",
+    "Telo.Runnable": "One-shot task: `run()` (pipelines, boot steps).",
+    "Telo.Invocable": "Request handler: `invoke(inputs)` (scripts, endpoints).",
+    "Telo.Provider": "Value-flow source: `init()` + optional `provide()` (config, secrets).",
+    "Telo.Mount": "Mounted into a Service (HTTP APIs, middleware).",
+    "Telo.Type": "Pure schema definition — no runtime instance.",
+};

package/dist/definition/build-definition.d.ts

@@ -0,0 +1,13 @@
+import { type AstDocument, type LoadedGraph } from "@telorun/analyzer";
+import type { DefinitionResult } from "../types.js";
+/** Resolve the `!ref` under the cursor to its target resource's definition.
+ *
+ *  The ref grammar mirrors `resolveRefSentinels`: the tag's value is split on
+ *  the first dot — a bare name (or `Self.name`) is a local resource in the
+ *  current module; `Alias.name` is an exported instance of the module the import
+ *  `Alias` points at, followed transitively through re-exports and gated on each
+ *  module's `exports.resources`. Returns `undefined` when the cursor isn't on a
+ *  `!ref`, or the target can't be found (e.g. a scope-local name, an unexported
+ *  instance, or an import that failed to load). */
+export declare function buildDefinition(text: string, line: number, character: number, graph: LoadedGraph, currentFilePath: string, docs?: AstDocument[]): DefinitionResult | undefined;
+//# sourceMappingURL=build-definition.d.ts.map

package/dist/definition/build-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-definition.d.ts","sourceRoot":"","sources":["../../src/definition/build-definition.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EAEhB,KAAK,WAAW,EAGjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AA6EpD;;;;;;;;mDAQmD;AACnD,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,WAAW,EAClB,eAAe,EAAE,MAAM,EACvB,IAAI,CAAC,EAAE,WAAW,EAAE,GACnB,gBAAgB,GAAG,SAAS,CAqB9B"}