@intentius/chant-lexicon-fountain 0.33.0

package/src/lint/post-synth/ftn015-mcp-secret-env-substitution.ts

@@ -0,0 +1,49 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { propsOf } from "../../entity-props";
+
+/**
+ * FTN015: secret-shaped MCP server env keys must use `${VAR}` references.
+ *
+ * A literal value under TOKEN/SECRET/KEY/PASSWORD-shaped keys in
+ * `mcp_servers.*.env` is a credential in source and in fountain's stored
+ * agent config. FTN001 catches known credential *shapes* at the AST;
+ * this catches the key-name signal regardless of value shape.
+ */
+
+const SECRET_KEY_RE = /(TOKEN|SECRET|PASSWORD|API_?KEY|CREDENTIAL)/i;
+const SUBSTITUTION_RE = /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/;
+
+export const mcpSecretEnvSubstitutionCheck: PostSynthCheck = {
+  id: "FTN015",
+  description: "Secret-shaped MCP env keys must be ${VAR} references, not literals",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of ctx.entities) {
+      if (entity.entityType !== "Fountain::V1::Agent") continue;
+      const servers = propsOf(entity).mcp_servers as Record<string, unknown> | undefined;
+      if (!servers || typeof servers !== "object") continue;
+
+      for (const [serverName, server] of Object.entries(servers)) {
+        const env = (server as { env?: Record<string, unknown> })?.env;
+        if (!env || typeof env !== "object") continue;
+        for (const [key, value] of Object.entries(env)) {
+          if (!SECRET_KEY_RE.test(key)) continue;
+          if (typeof value === "string" && SUBSTITUTION_RE.test(value)) continue;
+          diagnostics.push({
+            checkId: "FTN015",
+            severity: "error",
+            message:
+              `Agent "${name}" mcp_servers.${serverName}.env.${key} looks secret-shaped ` +
+              `but is not a \${VAR} reference — literals here land in stored agent config`,
+            entity: name,
+            lexicon: "fountain",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/ftn016-runtime-model-valid.ts

@@ -0,0 +1,50 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { propsOf } from "../../entity-props";
+
+/**
+ * FTN016: runtime and model must be valid before apply.
+ *
+ * The generated types make these compile-time checks for typed authoring;
+ * this backstops untyped construction (imported templates, hand-built
+ * plans) so a typo fails the build instead of a 422 at apply.
+ */
+
+const RUNTIMES = new Set(["claude", "codex", "gemini", "opencode"]);
+const MODEL_RE = /^[a-z0-9_-]+\/[a-z0-9._-]+$/;
+
+export const runtimeModelValidCheck: PostSynthCheck = {
+  id: "FTN016",
+  description: "Agent runtime must be a known runtime and model canonical provider/model_id",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of ctx.entities) {
+      if (entity.entityType !== "Fountain::V1::Agent") continue;
+      const agent = propsOf(entity) as { runtime?: unknown; model?: unknown };
+
+      if (typeof agent.runtime === "string" && !RUNTIMES.has(agent.runtime)) {
+        diagnostics.push({
+          checkId: "FTN016",
+          severity: "error",
+          message:
+            `Agent "${name}" runtime "${agent.runtime}" is not one of ` +
+            `${[...RUNTIMES].join(", ")}`,
+          entity: name,
+          lexicon: "fountain",
+        });
+      }
+      if (typeof agent.model === "string" && !MODEL_RE.test(agent.model)) {
+        diagnostics.push({
+          checkId: "FTN016",
+          severity: "error",
+          message: `Agent "${name}" model "${agent.model}" is not canonical provider/model_id form`,
+          entity: name,
+          lexicon: "fountain",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/ftn017-unique-resource-names.ts

@@ -0,0 +1,43 @@
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { propsOf } from "../../entity-props";
+
+/**
+ * FTN017: resource names must be unique per kind.
+ *
+ * fountainApply reconciles by name; two entities of the same kind
+ * resolving to the same fountain name would fight over one live
+ * resource — the second apply step silently becomes an update of the
+ * first one's creation.
+ */
+export const uniqueResourceNamesCheck: PostSynthCheck = {
+  id: "FTN017",
+  description: "Two declarations of the same kind must not resolve to the same fountain name",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const seen = new Map<string, string>();
+
+    for (const [entityName, entity] of ctx.entities) {
+      if (!entity.entityType.startsWith("Fountain::V1::")) continue;
+      const props = propsOf(entity);
+      const resourceName = typeof props.name === "string" ? props.name : entityName;
+      const key = `${entity.entityType}/${resourceName}`;
+      const first = seen.get(key);
+      if (first) {
+        diagnostics.push({
+          checkId: "FTN017",
+          severity: "error",
+          message:
+            `"${entityName}" and "${first}" both resolve to ${key} — apply would ` +
+            `reconcile them onto one live resource`,
+          entity: entityName,
+          lexicon: "fountain",
+        });
+      } else {
+        seen.set(key, entityName);
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/index.ts

@@ -0,0 +1,21 @@
+// Code generated by chant generate. DO NOT EDIT.
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+import { networkingExplicitCheck } from "./ftn010-networking-explicit";
+import { noUnrestrictedNetworkingCheck } from "./ftn011-no-unrestricted-networking";
+import { noCloudCredentialEnvCheck } from "./ftn012-no-cloud-credential-env";
+import { substitutionResolvableCheck } from "./ftn013-substitution-resolvable";
+import { vaultShadowingCheck } from "./ftn014-vault-shadowing";
+import { mcpSecretEnvSubstitutionCheck } from "./ftn015-mcp-secret-env-substitution";
+import { runtimeModelValidCheck } from "./ftn016-runtime-model-valid";
+import { uniqueResourceNamesCheck } from "./ftn017-unique-resource-names";
+
+export const postSynthChecks: PostSynthCheck[] = [
+  networkingExplicitCheck,
+  noUnrestrictedNetworkingCheck,
+  noCloudCredentialEnvCheck,
+  substitutionResolvableCheck,
+  vaultShadowingCheck,
+  mcpSecretEnvSubstitutionCheck,
+  runtimeModelValidCheck,
+  uniqueResourceNamesCheck,
+];

package/src/lint/post-synth/post-synth.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import type { Declarable } from "@intentius/chant";
+// From the check modules, not the barrel — the barrel is generated and
+// exports only the `postSynthChecks` array.
+import { noUnrestrictedNetworkingCheck } from "./ftn011-no-unrestricted-networking";
+import { substitutionResolvableCheck } from "./ftn013-substitution-resolvable";
+import { vaultShadowingCheck } from "./ftn014-vault-shadowing";
+import { mcpSecretEnvSubstitutionCheck } from "./ftn015-mcp-secret-env-substitution";
+import { runtimeModelValidCheck } from "./ftn016-runtime-model-valid";
+import { uniqueResourceNamesCheck } from "./ftn017-unique-resource-names";
+
+function ctx(entities: Record<string, Record<string, unknown>>): PostSynthContext {
+  const map = new Map<string, Declarable>();
+  for (const [name, props] of Object.entries(entities)) {
+    map.set(name, { lexicon: "fountain", ...props } as unknown as Declarable);
+  }
+  return { outputs: new Map(), entities: map, buildResult: { warnings: [], errors: [] } } as unknown as PostSynthContext;
+}
+
+const ENV = "Fountain::V1::Environment";
+const VAULT = "Fountain::V1::Vault";
+const AGENT = "Fountain::V1::Agent";
+
+describe("FTN011 no-unrestricted-networking", () => {
+  it("warns on unrestricted, silent on limited", () => {
+    expect(noUnrestrictedNetworkingCheck.check(ctx({ e: { entityType: ENV, networking_type: "unrestricted" } }))).toHaveLength(1);
+    expect(noUnrestrictedNetworkingCheck.check(ctx({ e: { entityType: ENV, networking_type: "limited" } }))).toHaveLength(0);
+  });
+});
+
+describe("FTN013 substitution-resolvable", () => {
+  const env = { entityType: ENV, name: "e", env_vars: { DECLARED: "x" }, secrets: [{ key: "SECRET_ONE", value: "v" }] };
+
+  it("warns on an unresolvable reference", () => {
+    const diags = substitutionResolvableCheck.check(
+      ctx({ e: env, a: { entityType: AGENT, environment: "e", mcp_servers: { s: { env: { T: "${MISSING}" } } } } }),
+    );
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("MISSING");
+  });
+
+  it("resolves against env_vars and secrets keys", () => {
+    const diags = substitutionResolvableCheck.check(
+      ctx({ e: env, a: { entityType: AGENT, environment: "e", mcp_servers: { s: { env: { A: "${DECLARED}", B: "${SECRET_ONE}" } } } } }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+
+  it("silent when the environment is external", () => {
+    const diags = substitutionResolvableCheck.check(
+      ctx({ a: { entityType: AGENT, environment: "not-declared-here", mcp_servers: { s: { env: { T: "${X}" } } } } }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+});
+
+describe("FTN014 vault-shadowing", () => {
+  it("warns when a vault key collides with an environment key", () => {
+    const diags = vaultShadowingCheck.check(
+      ctx({
+        e: { entityType: ENV, env_vars: { DATABASE_URL: "prod" } },
+        v: { entityType: VAULT, secrets: [{ key: "DATABASE_URL", value: "staging" }] },
+      }),
+    );
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("DATABASE_URL");
+  });
+
+  it("silent without collisions", () => {
+    const diags = vaultShadowingCheck.check(
+      ctx({
+        e: { entityType: ENV, env_vars: { A: "1" } },
+        v: { entityType: VAULT, secrets: [{ key: "B", value: "2" }] },
+      }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+});
+
+describe("FTN015 mcp-secret-env-substitution", () => {
+  it("errors on a literal under a secret-shaped key", () => {
+    const diags = mcpSecretEnvSubstitutionCheck.check(
+      ctx({ a: { entityType: AGENT, mcp_servers: { gh: { env: { GITHUB_TOKEN: "literal" } } } } }),
+    );
+    expect(diags).toHaveLength(1);
+  });
+
+  it("accepts ${VAR} references and non-secret keys", () => {
+    const diags = mcpSecretEnvSubstitutionCheck.check(
+      ctx({ a: { entityType: AGENT, mcp_servers: { gh: { env: { GITHUB_TOKEN: "${GH}", LOG_LEVEL: "debug" } } } } }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+});
+
+describe("FTN016 runtime-model-valid", () => {
+  it("errors on unknown runtime and malformed model", () => {
+    const diags = runtimeModelValidCheck.check(
+      ctx({ a: { entityType: AGENT, runtime: "cursor", model: "not-canonical" } }),
+    );
+    expect(diags).toHaveLength(2);
+  });
+
+  it("silent on valid values", () => {
+    const diags = runtimeModelValidCheck.check(
+      ctx({ a: { entityType: AGENT, runtime: "claude", model: "anthropic/claude-sonnet-4-6" } }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+});
+
+describe("FTN017 unique-resource-names", () => {
+  it("errors when two entities of a kind share a fountain name", () => {
+    const diags = uniqueResourceNamesCheck.check(
+      ctx({
+        a: { entityType: ENV, name: "same" },
+        b: { entityType: ENV, name: "same" },
+      }),
+    );
+    expect(diags).toHaveLength(1);
+  });
+
+  it("allows the same name across kinds", () => {
+    const diags = uniqueResourceNamesCheck.check(
+      ctx({
+        a: { entityType: ENV, name: "same" },
+        b: { entityType: VAULT, name: "same" },
+      }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/lint/rules/ftn001-no-secret-literals.ts

@@ -0,0 +1,71 @@
+import ts from "typescript";
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+
+/**
+ * FTN001: no secret literals in fountain resource declarations.
+ *
+ * Environment/Vault secrets and MCP server env values must be substitution
+ * references (`${VAR}`) or provider references — never literal credential
+ * values. A literal in source is a credential in git history.
+ *
+ * Fires on string literals matching well-known credential shapes anywhere
+ * inside a `new Environment/Vault/Agent(...)` expression.
+ */
+
+const FOUNTAIN_KINDS = new Set(["Environment", "Vault", "Agent"]);
+
+const CREDENTIAL_SHAPES: Array<{ pattern: RegExp; label: string }> = [
+  { pattern: /^AKIA[0-9A-Z]{16}$/, label: "AWS access key id" },
+  { pattern: /^(ghp|gho|ghs|ghu)_[A-Za-z0-9]{20,}$/, label: "GitHub token" },
+  { pattern: /^github_pat_[A-Za-z0-9_]{20,}$/, label: "GitHub fine-grained token" },
+  { pattern: /^sk-[A-Za-z0-9_-]{20,}$/, label: "secret API key (sk-)" },
+  { pattern: /^ftn_[A-Za-z0-9]{16,}$/, label: "fountain API key" },
+  { pattern: /^xox[baprs]-[A-Za-z0-9-]{10,}$/, label: "Slack token" },
+  { pattern: /^-----BEGIN [A-Z ]*PRIVATE KEY-----/, label: "private key material" },
+];
+
+export const noSecretLiteralsRule: LintRule = {
+  id: "FTN001",
+  severity: "error",
+  category: "security",
+  description:
+    "No literal credential values in fountain declarations — use ${VAR} substitution or a secret provider",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const source = context.sourceFile;
+
+    const visit = (node: ts.Node, insideFountainNew: boolean) => {
+      let inside = insideFountainNew;
+
+      if (ts.isNewExpression(node)) {
+        const name = node.expression.getText(source);
+        const short = name.split(".").pop() ?? name;
+        if (FOUNTAIN_KINDS.has(short)) inside = true;
+      }
+
+      if (inside && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))) {
+        const value = node.text;
+        for (const { pattern, label } of CREDENTIAL_SHAPES) {
+          if (pattern.test(value)) {
+            const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
+            diagnostics.push({
+              ruleId: "FTN001",
+              severity: "error",
+              message: `Literal ${label} in a fountain declaration — use \${VAR} substitution or a secret provider`,
+              file: context.filePath,
+              line: line + 1,
+              column: character + 1,
+            });
+            break;
+          }
+        }
+      }
+
+      ts.forEachChild(node, (child) => visit(child, inside));
+    };
+
+    visit(source, false);
+    return diagnostics;
+  },
+};

package/src/lint/rules/index.ts

@@ -0,0 +1,7 @@
+import type { LintRule } from "@intentius/chant/lint/rule";
+import { noSecretLiteralsRule } from "./ftn001-no-secret-literals";
+
+export { noSecretLiteralsRule } from "./ftn001-no-secret-literals";
+
+/** All lint rules provided by this lexicon (imported by plugin.ts's lintRules()). */
+export const rules: LintRule[] = [noSecretLiteralsRule];

package/src/lint/rules/rules.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from "vitest";
+import ts from "typescript";
+import { noSecretLiteralsRule } from "./ftn001-no-secret-literals";
+import { networkingExplicitCheck } from "../post-synth/ftn010-networking-explicit";
+import { noCloudCredentialEnvCheck } from "../post-synth/ftn012-no-cloud-credential-env";
+import type { LintContext } from "@intentius/chant/lint/rule";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import type { Declarable } from "@intentius/chant";
+
+function lintCtx(code: string): LintContext {
+  return {
+    sourceFile: ts.createSourceFile("infra.ts", code, ts.ScriptTarget.Latest, true),
+    entities: [],
+    filePath: "infra.ts",
+    lexicon: "fountain",
+  } as LintContext;
+}
+
+function synthCtx(entities: Record<string, Record<string, unknown>>): PostSynthContext {
+  const map = new Map<string, Declarable>();
+  for (const [name, props] of Object.entries(entities)) {
+    map.set(name, { lexicon: "fountain", ...props } as unknown as Declarable);
+  }
+  return { outputs: new Map(), entities: map, buildResult: { warnings: [], errors: [] } } as unknown as PostSynthContext;
+}
+
+describe("FTN001 no-secret-literals", () => {
+  it("flags a literal AWS key inside a fountain declaration", () => {
+    const diags = noSecretLiteralsRule.check(
+      lintCtx(`export const e = new Environment({ env_vars: { K: "AKIAIOSFODNN7EXAMPLE" } });`),
+    );
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("FTN001");
+  });
+
+  it("flags a GitHub token inside an Agent's mcp env", () => {
+    const diags = noSecretLiteralsRule.check(
+      lintCtx(
+        `export const a = new Agent({ mcp_servers: { gh: { env: { T: "ghp_abcdefghijklmnopqrstuv" } } } });`,
+      ),
+    );
+    expect(diags).toHaveLength(1);
+  });
+
+  it("does not flag substitution references", () => {
+    const diags = noSecretLiteralsRule.check(
+      lintCtx(`export const a = new Agent({ mcp_servers: { gh: { env: { T: "\${GITHUB_PAT}" } } } });`),
+    );
+    expect(diags).toHaveLength(0);
+  });
+
+  it("ignores credential-shaped literals outside fountain declarations", () => {
+    const diags = noSecretLiteralsRule.check(
+      lintCtx(`const fixture = "AKIAIOSFODNN7EXAMPLE";`),
+    );
+    expect(diags).toHaveLength(0);
+  });
+});
+
+describe("FTN010 networking-explicit", () => {
+  it("warns on an Environment without networking_type", () => {
+    const diags = networkingExplicitCheck.check(
+      synthCtx({ env: { entityType: "Fountain::V1::Environment", name: "e" } }),
+    );
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("FTN010");
+  });
+
+  it("is silent when networking_type is explicit", () => {
+    const diags = networkingExplicitCheck.check(
+      synthCtx({
+        env: { entityType: "Fountain::V1::Environment", name: "e", networking_type: "limited" },
+      }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+
+  it("ignores non-Environment kinds", () => {
+    const diags = networkingExplicitCheck.check(
+      synthCtx({ v: { entityType: "Fountain::V1::Vault", name: "v" } }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+});
+
+describe("FTN012 no-cloud-credential-env", () => {
+  it("errors on a credential key in env_vars", () => {
+    const diags = noCloudCredentialEnvCheck.check(
+      synthCtx({
+        env: {
+          entityType: "Fountain::V1::Environment",
+          name: "e",
+          env_vars: { AWS_SECRET_ACCESS_KEY: "whatever" },
+        },
+      }),
+    );
+    expect(diags).toHaveLength(1);
+    expect(diags[0].severity).toBe("error");
+  });
+
+  it("errors on a credential-shaped value under an innocent key", () => {
+    const diags = noCloudCredentialEnvCheck.check(
+      synthCtx({
+        env: {
+          entityType: "Fountain::V1::Environment",
+          name: "e",
+          env_vars: { UPSTREAM: "AKIAIOSFODNN7EXAMPLE" },
+        },
+      }),
+    );
+    expect(diags).toHaveLength(1);
+  });
+
+  it("is silent on ordinary env vars", () => {
+    const diags = noCloudCredentialEnvCheck.check(
+      synthCtx({
+        env: {
+          entityType: "Fountain::V1::Environment",
+          name: "e",
+          env_vars: { LOG_LEVEL: "info" },
+        },
+      }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/lsp/completions.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import type { CompletionContext } from "@intentius/chant/lsp/types";
+import { completions } from "./completions";
+
+function ctx(partial: Partial<CompletionContext>): CompletionContext {
+  return {
+    uri: "file:///infra.ts",
+    content: "",
+    position: { line: 0, character: 0 },
+    wordAtCursor: "",
+    linePrefix: "",
+    ...partial,
+  };
+}
+
+describe("LSP completions", () => {
+  it("suggests the fountain kinds after `new `", () => {
+    const items = completions(ctx({ linePrefix: "export const e = new " }));
+    const labels = items.map((i) => i.label);
+
+    expect(labels).toContain("Environment");
+    expect(labels).toContain("Vault");
+    expect(labels).toContain("Agent");
+    expect(items.every((i) => i.kind === "resource")).toBe(true);
+  });
+
+  it("narrows on a typed prefix", () => {
+    const items = completions(ctx({ linePrefix: "new Env", wordAtCursor: "Env" }));
+
+    expect(items.map((i) => i.label)).toEqual(["Environment"]);
+    expect(items[0].detail).toBe("Fountain::V1::Environment");
+  });
+
+  it("suggests properties inside a constructor", () => {
+    const content = "const a = new Agent({\n  ";
+    const items = completions(
+      ctx({ content, position: { line: 1, character: 2 }, linePrefix: "  " }),
+    );
+    const labels = items.map((i) => i.label);
+
+    // Property names come off propertyConstraints — the key the core
+    // LexiconEntry contract reads. A rename there silently empties this.
+    expect(labels).toContain("runtime");
+    expect(labels).toContain("model");
+    expect(items.every((i) => i.kind === "property")).toBe(true);
+  });
+
+  it("returns nothing in an unrelated position", () => {
+    expect(completions(ctx({ linePrefix: "const x = 1" }))).toEqual([]);
+  });
+});

package/src/lsp/completions.ts

@@ -0,0 +1,21 @@
+import { createRequire } from "module";
+import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconCompletions, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(import.meta.url);
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const data = require("../generated/lexicon-fountain.json") as Record<string, LexiconEntry>;
+  cachedIndex = new LexiconIndex(data);
+  return cachedIndex;
+}
+
+/**
+ * Provide LSP completions for fountain resources — class names after
+ * `new `, property names inside a constructor.
+ */
+export function completions(ctx: CompletionContext): CompletionItem[] {
+  return lexiconCompletions(ctx, getIndex(), "fountain resource");
+}

package/src/lsp/hover.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import type { HoverContext } from "@intentius/chant/lsp/types";
+import { hover } from "./hover";
+
+function ctx(word: string): HoverContext {
+  return {
+    uri: "file:///infra.ts",
+    content: "",
+    position: { line: 0, character: 0 },
+    word,
+    lineText: "",
+  };
+}
+
+describe("LSP hover", () => {
+  it("returns undefined for an unknown word", () => {
+    expect(hover(ctx("Conversation"))).toBeUndefined();
+    expect(hover(ctx(""))).toBeUndefined();
+  });
+
+  it("describes a resource with its fountain type", () => {
+    const info = hover(ctx("Environment"));
+
+    expect(info?.contents).toContain("**Environment**");
+    expect(info?.contents).toContain("Fountain::V1::Environment");
+  });
+
+  it("carries the networking semantics an author cannot infer from the prop name", () => {
+    const info = hover(ctx("Environment"));
+
+    expect(info?.contents).toContain("denies all egress");
+    expect(info?.contents).toContain("`networking_type`: `unrestricted` | `limited`");
+  });
+
+  it("spells out allowed_vault_ids' three-state meaning", () => {
+    const info = hover(ctx("Agent"));
+
+    expect(info?.contents).toContain("allowed_vault_ids");
+    expect(info?.contents).toContain("`runtime`: `claude` | `codex` | `gemini` | `opencode`");
+  });
+
+  it("marks property types as non-declarable", () => {
+    const info = hover(ctx("Repository"));
+
+    expect(info?.contents).toContain("Property type");
+  });
+});