@intentius/chant-lexicon-fountain 0.33.0

package/src/describe-resources.ts

@@ -0,0 +1,192 @@
+/**
+ * Live introspection of fountain resources — the read-back seam for chant's
+ * plan/drift machinery.
+ *
+ * Drives core's observer harness (`observeEntities`, #1201) rather than
+ * re-deriving its control flow: bind-or-not-observe-all with a typed reason,
+ * per-entity tri-state routing, and a read throw degrading to `read-failed`
+ * rather than a silent absence that would classify as a spurious `create`.
+ * What this lexicon supplies is the adapter — the transport and the per-entity
+ * read.
+ *
+ * The read is a lookup, not a fetch: fountain has no per-resource-by-name
+ * endpoint, so the adapter lists each declared kind once
+ * (GET /api/environments|vaults|agents) and indexes it by name. The list
+ * promise is cached per kind, so concurrent reads share one request and a
+ * failed list marks only that kind's entities read-failed.
+ *
+ * Ownership comes from the `managed-by: chant` metadata marker (fountain#137
+ * gave all three kinds the channel). Endpoint + auth reuse the applier
+ * verbatim (FOUNTAIN_ENDPOINT / FOUNTAIN_TOKEN), so plan reads the same
+ * instance fountainApply writes. Secret *values* never appear anywhere on
+ * this path — the API is write-only for values; the secrets sub-resource is
+ * not read here at all.
+ */
+
+import type { ObservationResult, ResourceMetadata } from "@intentius/chant/lexicon";
+import {
+  observeEntities,
+  type DeclaredEntity,
+  type EntityObservation,
+  type ObserverAdapter,
+} from "@intentius/chant/observation";
+import {
+  resolveEndpoint,
+  defaultFountainHttp,
+  isChantOwned,
+  OWNERSHIP_KEY,
+  OWNERSHIP_VALUE,
+  type FountainHttp,
+} from "./op/activities/fountain-apply";
+
+const KIND_PATHS: Record<string, string> = {
+  "Fountain::V1::Environment": "environments",
+  "Fountain::V1::Vault": "vaults",
+  "Fountain::V1::Agent": "agents",
+};
+
+/** Thrown by bind() when there is no token to read with. */
+class MissingTokenError extends Error {}
+
+export interface DescribeResourcesOptions {
+  environment: string;
+  buildOutput: string;
+  entityNames: string[];
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  /** Restrict to chant-owned resources. */
+  owned?: boolean;
+  /** Endpoint override (tests). Defaults to resolveEndpoint(). */
+  endpoint?: string;
+}
+
+interface LiveResource {
+  id: string;
+  name: string;
+  metadata?: Record<string, unknown>;
+  inserted_at?: string;
+  updated_at?: string;
+  /** Agents only — the reference edge the catalog reconstructs. */
+  environment_id?: string | null;
+}
+
+/** The transport plus its per-kind list cache. */
+interface FountainClient {
+  http: FountainHttp;
+  /** entityType → in-flight or settled list, indexed by resource name. */
+  lists: Map<string, Promise<Map<string, LiveResource>>>;
+}
+
+function listKind(client: FountainClient, entityType: string): Promise<Map<string, LiveResource>> {
+  const cached = client.lists.get(entityType);
+  if (cached) return cached;
+
+  const path = KIND_PATHS[entityType];
+  const pending = (async () => {
+    const { status, json } = await client.http("GET", `/api/${path}`);
+    if (status !== 200) throw new Error(`list ${path} returned ${status}`);
+    const data = (json as { data?: LiveResource[] })?.data ?? [];
+    return new Map(data.map((r) => [r.name, r]));
+  })();
+
+  client.lists.set(entityType, pending);
+  return pending;
+}
+
+function present(entityType: string, found: LiveResource, owned: boolean): ResourceMetadata {
+  return {
+    type: entityType,
+    physicalId: found.id,
+    status: "PRESENT",
+    ...(found.updated_at ? { lastUpdated: found.updated_at } : {}),
+    attributes: {
+      id: found.id,
+      ...(found.inserted_at ? { inserted_at: found.inserted_at } : {}),
+      ...(found.updated_at ? { updated_at: found.updated_at } : {}),
+      ...(found.environment_id ? { environment_id: found.environment_id } : {}),
+    },
+    ownership: owned ? "owned" : "foreign",
+  };
+}
+
+function createAdapter(
+  options: DescribeResourcesOptions,
+  http?: FountainHttp,
+): ObserverAdapter<FountainClient> {
+  return {
+    async bind() {
+      if (http) return { http, lists: new Map() };
+
+      const token = process.env.FOUNTAIN_TOKEN;
+      if (!token) {
+        throw new MissingTokenError(
+          "FOUNTAIN_TOKEN is not set — cannot read live fountain state",
+        );
+      }
+      return {
+        http: defaultFountainHttp(resolveEndpoint({ endpoint: options.endpoint }), token),
+        lists: new Map(),
+      };
+    },
+
+    classifyBindFailure(err) {
+      // The only whole-lexicon failure fountain has: nothing to authenticate
+      // with. Anything else is a genuine fault and must stay loud.
+      if (err instanceof MissingTokenError) {
+        return { reason: "no-credentials", detail: err.message };
+      }
+      return "rethrow";
+    },
+
+    async read(client, entity): Promise<EntityObservation> {
+      if (!(entity.type in KIND_PATHS)) {
+        return {
+          unobserved: {
+            reason: "unsupported-kind",
+            detail: `no fountain read path for ${entity.type}`,
+          },
+        };
+      }
+
+      // A list failure throws — the harness records read-failed for this
+      // entity, and the cached rejected promise gives the same verdict to
+      // every other entity of the kind without a second request.
+      const live = await listKind(client, entity.type);
+
+      const resourceName =
+        typeof entity.props.name === "string" ? (entity.props.name as string) : entity.name;
+      const found = live.get(resourceName);
+
+      // Observed absent: we asked, fountain said no → eligible for `create`.
+      if (!found) return { absent: true };
+
+      const owned = isChantOwned(found);
+      if (options.owned && !owned) {
+        return {
+          unobserved: {
+            reason: "filtered",
+            detail: `"${resourceName}" exists but does not carry the ${OWNERSHIP_KEY}: ${OWNERSHIP_VALUE} marker`,
+          },
+        };
+      }
+
+      return { present: present(entity.type, found, owned) };
+    },
+  };
+}
+
+/**
+ * `http` is injectable for tests; the default reuses the applier's fetch
+ * client (bearer token from FOUNTAIN_TOKEN).
+ */
+export async function describeResources(
+  options: DescribeResourcesOptions,
+  http?: FountainHttp,
+): Promise<ObservationResult> {
+  const declared: DeclaredEntity[] = [...options.entities].map(([name, entity]) => ({
+    name,
+    type: entity.entityType,
+    props: entity.props,
+  }));
+
+  return observeEntities(declared, createAdapter(options, http));
+}

package/src/detect.ts

@@ -0,0 +1,37 @@
+/**
+ * Detection helpers — is this input a fountain artifact?
+ */
+
+const KINDS = new Set(["Environment", "Vault", "Agent"]);
+
+/** A fountain manifest document (parsed): apiVersion fountain.dev/v1 + known kind. */
+export function isFountainManifest(doc: unknown): boolean {
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) return false;
+  const d = doc as Record<string, unknown>;
+  return d.apiVersion === "fountain.dev/v1" && typeof d.kind === "string" && KINDS.has(d.kind);
+}
+
+/** The serializer's fountain-plan.json shape: entity name → { kind, spec }. */
+export function isFountainPlan(data: unknown): boolean {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return false;
+  const entries = Object.values(data as Record<string, unknown>);
+  if (entries.length === 0) return false;
+  return entries.every((e) => {
+    if (!e || typeof e !== "object") return false;
+    const entry = e as Record<string, unknown>;
+    return typeof entry.kind === "string" && KINDS.has(entry.kind) && typeof entry.spec === "object";
+  });
+}
+
+/** Template detection for the plugin: raw string input (YAML or JSON). */
+export function detectFountainTemplate(data: unknown): boolean {
+  if (typeof data === "string") {
+    if (/apiVersion:\s*fountain\.dev\/v1/.test(data)) return true;
+    try {
+      return isFountainPlan(JSON.parse(data));
+    } catch {
+      return false;
+    }
+  }
+  return isFountainManifest(data) || isFountainPlan(data);
+}

package/src/entity-props.ts

@@ -0,0 +1,22 @@
+/**
+ * Read an entity's authored props regardless of representation.
+ *
+ * Real runtime instances (createResource/createProperty) keep authored
+ * props under the non-enumerable `.props` — enumerating the instance
+ * yields its AttrRefs, not its inputs. Plain objects (parsed data, test
+ * fixtures) carry props as own fields. Every fountain consumer of entity
+ * props goes through here so both shapes behave identically.
+ */
+export function propsOf(entity: unknown): Record<string, unknown> {
+  if (!entity || typeof entity !== "object") return {};
+  const anyEntity = entity as Record<string, unknown>;
+  if (anyEntity.props && typeof anyEntity.props === "object" && !Array.isArray(anyEntity.props)) {
+    return anyEntity.props as Record<string, unknown>;
+  }
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(anyEntity)) {
+    if (key === "entityType" || key === "lexicon" || key === "kind" || key === "attributes") continue;
+    out[key] = value;
+  }
+  return out;
+}

package/src/export-resources.ts

@@ -0,0 +1,103 @@
+/**
+ * Live export — read fountain resources back as import IR for
+ * `chant import --from`. The adoption path: an org with UI-built
+ * environments/vaults/agents gets typed leaf files.
+ *
+ * Server-written fields are stripped to the authored shape; an agent's
+ * `environment_id` is resolved back to the exported environment's logical
+ * name so the generated code carries a reviewable reference. Secret
+ * *values* never leave fountain (write-only upstream) and secret *keys*
+ * cannot round-trip into typed code yet — the request schema has no
+ * secrets field (they are a sub-resource; fountain#148's reference model
+ * would change this) — so environments export without their secrets and
+ * the caller is warned per environment that carries any.
+ */
+
+import type { ExportedTemplate, ResourceSelector } from "@intentius/chant/lexicon";
+import type { ResourceIR } from "@intentius/chant/import/parser";
+import {
+  resolveEndpoint,
+  defaultFountainHttp,
+  isChantOwned,
+  type FountainHttp,
+} from "./op/activities/fountain-apply";
+import { SERVER_FIELDS } from "./import/parser";
+
+const KINDS: Array<{ type: string; path: string; kind: string }> = [
+  { type: "Fountain::V1::Environment", path: "environments", kind: "Environment" },
+  { type: "Fountain::V1::Vault", path: "vaults", kind: "Vault" },
+  { type: "Fountain::V1::Agent", path: "agents", kind: "Agent" },
+];
+
+export interface ExportResourcesOptions {
+  environment: string;
+  selector?: ResourceSelector;
+  owned?: boolean;
+  verbatim?: boolean;
+  endpoint?: string;
+  /** Injectable for tests. */
+  http?: FountainHttp;
+  /** Warning sink (defaults to console.error). */
+  warn?: (msg: string) => void;
+}
+
+export async function exportResources(options: ExportResourcesOptions): Promise<ExportedTemplate> {
+  const warn = options.warn ?? ((msg: string) => console.error(`[fountain] ${msg}`));
+  const token = process.env.FOUNTAIN_TOKEN;
+  const http =
+    options.http ??
+    defaultFountainHttp(resolveEndpoint({ endpoint: options.endpoint }), token ?? "");
+  if (!options.http && !token) {
+    throw new Error("fountain export: FOUNTAIN_TOKEN is not set");
+  }
+
+  const resources: ResourceIR[] = [];
+  const envNameById = new Map<string, string>();
+
+  for (const { type, path, kind } of KINDS) {
+    if (options.selector?.type && options.selector.type !== type && options.selector.type !== kind) continue;
+
+    const { status, json } = await http("GET", `/api/${path}`);
+    if (status !== 200) throw new Error(`fountain export: list ${path} returned ${status}`);
+    const data = ((json as { data?: Array<Record<string, unknown>> })?.data ?? []);
+
+    for (const live of data) {
+      const name = typeof live.name === "string" ? live.name : "";
+      if (!name) continue;
+      if (options.selector?.name && options.selector.name !== name) continue;
+      if (options.owned && !isChantOwned(live)) continue;
+
+      const properties: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(live)) {
+        if (!options.verbatim && SERVER_FIELDS.includes(key)) continue;
+        if (value === null || value === undefined) continue;
+        properties[key] = value;
+      }
+
+      if (kind === "Environment") {
+        envNameById.set(String(live.id), name);
+        // Secrets are write-only and not expressible on the typed surface.
+        const { status: sStatus, json: sJson } = await http("GET", `/api/${path}/${live.id}/secrets`);
+        const secretCount = sStatus === 200 ? (((sJson as { data?: unknown[] })?.data ?? []).length) : 0;
+        if (secretCount > 0) {
+          warn(
+            `environment "${name}" carries ${secretCount} secret(s) — values are write-only and ` +
+              `keys are not part of the typed surface; re-declare them via your secret provider`,
+          );
+        }
+      }
+
+      if (kind === "Agent" && typeof properties.environment_id === "string") {
+        const envName = envNameById.get(properties.environment_id);
+        if (envName) {
+          delete properties.environment_id;
+          properties.environment = envName;
+        }
+      }
+
+      resources.push({ logicalId: name, type, properties });
+    }
+  }
+
+  return { resources, parameters: [] } as ExportedTemplate;
+}

package/src/generated/index.d.ts

@@ -0,0 +1,60 @@
+// Code generated by chant fly generate. DO NOT EDIT.
+
+// --- Fly Resource classes ---
+
+export declare class Agent {
+  constructor(props: {
+    model: string;
+    name: string;
+    runtime: "claude" | "codex" | "gemini" | "opencode";
+    /** Vaults a conversation may attach to this agent. null (default) allows any vault the tenant owns; an empty list forbids attaching any vault; a non-empty list is an allowlist. */
+    allowed_vault_ids?: string[];
+    description?: string;
+    environment_id?: string;
+    mcp_servers?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    /** Each entry is either inline (`{name, content}` — full SKILL.md text written to the sprite) or github (`{source, ref?, name?}` — installed on the sprite via the skills.sh CLI, optionally pinned to a tag/branch/sha via `ref`). Exactly one of `content` or `source` must be set on each entry. */
+    skills?: Record<string, unknown>[];
+    system?: string;
+  });
+  readonly id: string;
+  readonly inserted_at: string;
+  readonly updated_at: string;
+}
+
+export declare class Environment {
+  constructor(props: {
+    name: string;
+    env_vars?: Record<string, string>;
+    metadata?: Record<string, unknown>;
+    /** Refines networking_type: limited. allowed_hosts is the only key honored today; unknown keys are ignored. Under limited, egress is restricted to the allowlisted domains. With no allowed_hosts (or an empty list), the sandbox denies all egress by default — this is a deny-all, not an allow-all. */
+    networking_config?: Record<string, unknown>;
+    networking_type?: "limited" | "unrestricted";
+    packages?: Record<string, unknown>;
+    repositories?: Repository[];
+    setup_script?: string;
+  });
+  readonly id: string;
+  readonly inserted_at: string;
+  readonly updated_at: string;
+}
+
+export declare class Vault {
+  constructor(props: {
+    name: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+  });
+  readonly id: string;
+  readonly inserted_at: string;
+  readonly updated_at: string;
+}
+
+// --- Property type classes ---
+
+export declare class Repository {
+  constructor(props: {
+    mount_path: string;
+    url: string;
+  });
+}

package/src/generated/index.ts

@@ -0,0 +1,10 @@
+// Code generated by chant generate. DO NOT EDIT.
+import { createResource, createProperty } from "./runtime";
+
+export const Agent = createResource("Fountain::V1::Agent", "fountain", {"id":"id","inserted_at":"inserted_at","updated_at":"updated_at"});
+export const Environment = createResource("Fountain::V1::Environment", "fountain", {"id":"id","inserted_at":"inserted_at","updated_at":"updated_at"});
+export const Vault = createResource("Fountain::V1::Vault", "fountain", {"id":"id","inserted_at":"inserted_at","updated_at":"updated_at"});
+
+export const Repository = createProperty("Fountain::V1::Repository", "fountain");
+
+// Re-exports for convenience

package/src/generated/lexicon-fountain.json

@@ -0,0 +1,69 @@
+{
+  "Agent": {
+    "resourceType": "Fountain::V1::Agent",
+    "kind": "resource",
+    "lexicon": "fountain",
+    "propertyConstraints": {
+      "environment_id": {
+        "format": "uuid"
+      },
+      "model": {
+        "pattern": "^[a-z0-9_-]+/[a-z0-9._-]+$"
+      },
+      "name": {
+        "minLength": 1,
+        "maxLength": 200
+      },
+      "runtime": {
+        "enum": [
+          "claude",
+          "codex",
+          "gemini",
+          "opencode"
+        ]
+      }
+    }
+  },
+  "Environment": {
+    "resourceType": "Fountain::V1::Environment",
+    "kind": "resource",
+    "lexicon": "fountain",
+    "propertyConstraints": {
+      "name": {
+        "minLength": 1,
+        "maxLength": 200
+      },
+      "networking_type": {
+        "enum": [
+          "unrestricted",
+          "limited"
+        ]
+      }
+    }
+  },
+  "Repository": {
+    "resourceType": "Fountain::V1::Repository",
+    "kind": "property",
+    "lexicon": "fountain",
+    "propertyConstraints": {
+      "mount_path": {
+        "pattern": "^/"
+      },
+      "url": {
+        "pattern": "^https://",
+        "format": "uri"
+      }
+    }
+  },
+  "Vault": {
+    "resourceType": "Fountain::V1::Vault",
+    "kind": "resource",
+    "lexicon": "fountain",
+    "propertyConstraints": {
+      "name": {
+        "minLength": 1,
+        "maxLength": 200
+      }
+    }
+  }
+}

package/src/generated/runtime.ts

@@ -0,0 +1,4 @@
+/**
+ * Runtime factory constructors — re-exported from core.
+ */
+export { createResource, createProperty } from "@intentius/chant/runtime";

package/src/import/generator.ts

@@ -0,0 +1,112 @@
+/**
+ * Fountain TypeScript generator.
+ *
+ * Converts import IR from {@link FountainParser} into typed chant
+ * TypeScript: `import { Environment, ... } from
+ * "@intentius/chant-lexicon-fountain";` plus one `export const` per
+ * resource. `repositories` entries are wrapped in `new Repository({...})`
+ * — the one nested property declarable on the fountain surface.
+ */
+
+import type { TypeScriptGenerator, GeneratedFile } from "@intentius/chant/import/generator";
+import type { TemplateIR } from "@intentius/chant/import/parser";
+
+type Nested = { kind: "single" | "array"; cls: string };
+
+const NESTED_DECLARABLES: Record<string, Record<string, Nested>> = {
+  Environment: {
+    repositories: { kind: "array", cls: "Repository" },
+  },
+};
+
+export class FountainGenerator implements TypeScriptGenerator {
+  generate(ir: TemplateIR): GeneratedFile[] {
+    const imports = new Set<string>();
+    const bodyLines: string[] = [];
+
+    for (const resource of ir.resources) {
+      const parts = resource.type.split("::");
+      const className = parts.length >= 3 ? parts[2] : resource.type;
+      imports.add(className);
+      const varName = camelCase(resource.logicalId);
+      const props = formatProps(resource.properties, 0, className, imports);
+      bodyLines.push(`export const ${varName} = new ${className}(${props});`);
+      bodyLines.push("");
+    }
+
+    const lines: string[] = [];
+    if (imports.size > 0) {
+      lines.push(`import { ${[...imports].sort().join(", ")} } from "@intentius/chant-lexicon-fountain";`);
+      lines.push("");
+    }
+    lines.push(...bodyLines);
+
+    return [{ path: "main.ts", content: lines.join("\n") + "\n" }];
+  }
+}
+
+function camelCase(str: string): string {
+  return str.replace(/[-_.](.)/g, (_, c) => c.toUpperCase()).replace(/^(.)/, (_, c) => c.toLowerCase());
+}
+
+function formatProps(props: Record<string, unknown>, indent: number, ownerClass: string, imports: Set<string>): string {
+  const entries = Object.entries(props);
+  if (entries.length === 0) return "{}";
+
+  const pad = "  ".repeat(indent + 1);
+  const closePad = "  ".repeat(indent);
+  const nested = NESTED_DECLARABLES[ownerClass];
+
+  const lines = entries.map(([key, value]) => {
+    const spec = nested?.[key];
+    const rendered = spec !== undefined ? formatNested(value, indent + 1, spec, imports) : formatValue(value, indent + 1);
+    return `${pad}${objectKey(key)}: ${rendered},`;
+  });
+
+  return `{\n${lines.join("\n")}\n${closePad}}`;
+}
+
+function formatNested(value: unknown, indent: number, spec: Nested, imports: Set<string>): string {
+  const construct = (obj: unknown, at: number): string => {
+    if (!obj || typeof obj !== "object" || Array.isArray(obj)) return formatValue(obj, at);
+    imports.add(spec.cls);
+    return `new ${spec.cls}(${formatProps(obj as Record<string, unknown>, at, spec.cls, imports)})`;
+  };
+
+  if (spec.kind === "single") return construct(value, indent);
+
+  if (!Array.isArray(value) || value.length === 0) return "[]";
+  const pad = "  ".repeat(indent + 1);
+  const closePad = "  ".repeat(indent);
+  const items = value.map((v) => `${pad}${construct(v, indent + 1)},`);
+  return `[\n${items.join("\n")}\n${closePad}]`;
+}
+
+function formatValue(value: unknown, indent: number): string {
+  if (value === null || value === undefined) return "undefined";
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    const pad = "  ".repeat(indent + 1);
+    const closePad = "  ".repeat(indent);
+    const items = value.map((v) => `${pad}${formatValue(v, indent + 1)},`);
+    return `[\n${items.join("\n")}\n${closePad}]`;
+  }
+
+  if (typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>);
+    if (entries.length === 0) return "{}";
+    const pad = "  ".repeat(indent + 1);
+    const closePad = "  ".repeat(indent);
+    const lines = entries.map(([key, v]) => `${pad}${objectKey(key)}: ${formatValue(v, indent + 1)},`);
+    return `{\n${lines.join("\n")}\n${closePad}}`;
+  }
+
+  return String(value);
+}
+
+function objectKey(key: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
+}