@telorun/ide-support 0.6.0 → 0.7.1

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
@@ -15,9 +15,9 @@ import type { CompletionResult, IdeEnvironmentAdapter } from "../types.js";
  * 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
- * boundaries don't cross `/` or `@`).
+ * `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;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"}
+{"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

@@ -22,11 +22,11 @@ const PATH_PROBE_LIMIT = 50;
  * 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
- * boundaries don't cross `/` or `@`).
+ * `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://") ||
@@ -36,17 +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);
     }
     // 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 refSearchCompletions(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.
@@ -57,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,
             },
         ];
     }
@@ -95,14 +95,14 @@ 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 refSearchCompletions(prefix, valueStartColumn, adapter) {
+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 `//`).
@@ -124,7 +124,7 @@ async function refSearchCompletions(prefix, valueStartColumn, adapter) {
             documentation: m.description ? m.ref : undefined,
             insertText: id,
             filterText: id,
-            replaceFromColumn: valueStartColumn,
+            replaceRange,
         };
     });
 }
@@ -138,7 +138,7 @@ function refDisplayName(ref) {
     const segments = withoutScheme.split("/").filter(Boolean);
     return segments.slice(-2).join("/") || ref;
 }
-async function versionCompletions(prefix, atIdx, valueStartColumn, adapter) {
+async function versionCompletions(prefix, atIdx, replaceRange, adapter) {
     const ref = prefix.slice(0, atIdx);
     const partialVersion = prefix.slice(atIdx + 1);
     if (ref === "")
@@ -157,7 +157,7 @@ async function versionCompletions(prefix, atIdx, valueStartColumn, adapter) {
             detail: idx === 0 ? "latest" : undefined,
             insertText: id,
             filterText: id,
-            replaceFromColumn: valueStartColumn,
+            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"}

package/dist/definition/build-definition.js

@@ -0,0 +1,98 @@
+import { parseToAst, } from "@telorun/analyzer";
+import { resolveNodeAtPosition } from "../completions/resolve-node.js";
+/** The module whose owner or partials includes `filePath`. */
+function moduleForFile(graph, filePath) {
+    for (const mod of graph.modules.values()) {
+        if (mod.owner.source === filePath)
+            return mod;
+        if (mod.partials.some((p) => p.source === filePath))
+            return mod;
+    }
+    return undefined;
+}
+/** First resource named `name` across `files`, located at its `metadata.name`
+ *  (or its first line as a fallback). Names are unique within a module scope, so
+ *  the first hit is the definition. */
+function locateResource(files, name) {
+    for (const file of files) {
+        for (let i = 0; i < file.manifests.length; i++) {
+            const manifest = file.manifests[i];
+            if (!manifest || manifest.metadata?.name !== name)
+                continue;
+            const pos = file.positions[i];
+            const range = pos?.positionIndex.get("metadata.name") ??
+                pos?.positionIndex.get("@key:metadata.name") ??
+                (pos ? { start: { line: pos.sourceLine, character: 0 }, end: { line: pos.sourceLine, character: 0 } } : undefined);
+            if (range)
+                return { uri: file.source, range };
+        }
+    }
+    return undefined;
+}
+/** The `exports.resources` list of a module's owner doc (empty when absent). */
+function exportedResources(mod) {
+    const doc = mod.owner.manifests.find((m) => m?.kind === "Telo.Library" || m?.kind === "Telo.Application");
+    const list = doc?.exports?.resources;
+    return Array.isArray(list) ? list.filter((e) => typeof e === "string") : [];
+}
+/** Follow `name` into `moduleSource` across the export boundary, honoring the
+ *  `exports.resources` gate and re-export chains (`app → api → domain → …`). A
+ *  terminal match is a locally-owned instance the module actually exports; a
+ *  re-export entry `InnerAlias.name` hops through that module's own import edge.
+ *  `seen` bounds cyclic import graphs. */
+function resolveExported(graph, moduleSource, name, seen = new Set()) {
+    if (seen.has(moduleSource))
+        return undefined;
+    seen.add(moduleSource);
+    const mod = graph.modules.get(moduleSource);
+    if (!mod)
+        return undefined;
+    const exports = exportedResources(mod);
+    // No `exports.resources` block → ungated (the module hasn't opted into the
+    // gate, same as `exports.kinds`): a plain name match keeps navigation working
+    // for modules that predate explicit exports.
+    if (exports.length === 0) {
+        return locateResource([mod.owner, ...mod.partials], name);
+    }
+    if (exports.includes(name)) {
+        const local = locateResource([mod.owner, ...mod.partials], name);
+        if (local)
+            return local;
+    }
+    const reexport = exports.find((e) => e.endsWith(`.${name}`));
+    if (!reexport)
+        return undefined;
+    const innerAlias = reexport.slice(0, reexport.length - name.length - 1);
+    const edge = graph.importEdges.get(mod.owner.source)?.get(innerAlias);
+    return edge ? resolveExported(graph, edge.targetSource, name, seen) : undefined;
+}
+/** 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 function buildDefinition(text, line, character, graph, currentFilePath, docs) {
+    const astDocs = docs ?? parseToAst(text);
+    const node = resolveNodeAtPosition(text, astDocs, line, character)?.node;
+    if (!node || node.kind !== "scalar" || node.tag !== "!ref")
+        return undefined;
+    // The scalar's range covers the ref target text (the value after `!ref`).
+    const source = text.slice(node.range[0], node.range[1]).trim();
+    if (!source)
+        return undefined;
+    const currentModule = moduleForFile(graph, currentFilePath) ?? graph.entry;
+    const dot = source.indexOf(".");
+    const alias = dot === -1 ? undefined : source.slice(0, dot);
+    const name = dot === -1 ? source : source.slice(dot + 1);
+    if (alias === undefined || alias === "Self") {
+        return locateResource([currentModule.owner, ...currentModule.partials], name);
+    }
+    const edge = graph.importEdges.get(currentModule.owner.source)?.get(alias);
+    if (!edge)
+        return undefined;
+    return resolveExported(graph, edge.targetSource, name);
+}

package/dist/definition/index.d.ts

@@ -0,0 +1,2 @@
+export { buildDefinition } from "./build-definition.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/definition/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/definition/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/definition/index.js

@@ -0,0 +1 @@
+export { buildDefinition } from "./build-definition.js";

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

@@ -0,0 +1,4 @@
+import { type AnalysisRegistry, type AstDocument } from "@telorun/analyzer";
+import type { HoverResult } from "../types.js";
+export declare function buildHover(text: string, line: number, character: number, registry: AnalysisRegistry | undefined, docs?: AstDocument[]): HoverResult | undefined;
+//# sourceMappingURL=build-hover.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build-hover.d.ts","sourceRoot":"","sources":["../../src/hover/build-hover.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,WAAW,EACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAoF/C,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,gBAAgB,GAAG,SAAS,EACtC,IAAI,CAAC,EAAE,WAAW,EAAE,GACnB,WAAW,GAAG,SAAS,CAOzB"}