@intentius/chant-lexicon-fountain 0.76.0 → 0.78.0

package/src/spec/parse.ts

@@ -20,9 +20,11 @@
  *     add one that reaches the API only as a path parameter (a schedule's
  *     teammate), into a by-name reference the serializer resolves and FTN021
  *     proves resolvable — the same shape an Agent's `environment` has.
- *   - Extensions. A prop chant accepts ahead of upstream, declared here so the
- *     generated type documents it instead of leaving authors to smuggle it
- *     through `metadata`. Today that is the ACP runtime.
+ *   - Extensions. A prop chant accepts that the request schema does not
+ *     describe, declared here so the generated type documents it instead of
+ *     leaving authors to smuggle it through `metadata` or a cast. Today that is
+ *     the inline `secrets` on Environment and Vault, which upstream documents
+ *     on its manifest format rather than on either request schema.
  */
 
 import {
@@ -96,7 +98,7 @@ interface RefSpec {
   description: string;
 }
 
-/** A prop chant accepts that the pinned spec does not describe yet. */
+/** A prop chant accepts that the kind's request schema does not describe. */
 interface ExtensionSpec {
   name: string;
   tsType: string;
@@ -109,23 +111,29 @@ interface ResourceSpec {
   request: string;
   response: string;
   refs?: RefSpec[];
-  /** Extra accepted values, per enum-valued request property. */
-  enumExtensions?: Record<string, string[]>;
   extensions?: ExtensionSpec[];
 }
 
 /**
- * The ACP runtime (BinaryBourbon/fountain#1634).
+ * The inline secrets a manifest document carries (Environment and Vault).
  *
- * `runtime: "acp"` and `runtime_command` are not in the pinned spec; the
- * upstream PR that adds them is open. chant models them anyway, because
- * `chant acp` is what a steward's agent runs, and an author who cannot name
- * the runtime has nowhere to put it but `metadata`. An instance without #1634
- * rejects them at apply — a 422 with an obvious cause, which is better than a
- * generated type that cannot express the deployment this lexicon is for.
+ * Neither request schema has the field: secrets are a write-only
+ * sub-resource with routes of their own. Upstream's `ManifestResource` says a
+ * manifest spec is the create schema "plus an inline `secrets` map
+ * (Environment and Vault)", and `fountainApply` turns the authored list into
+ * that map. Without the extension the generated types have no field for what
+ * the chant-fountain-secrets skill tells an author to write.
  */
-const ACP_NOTE =
-  "chant extension, pending BinaryBourbon/fountain#1634 — an instance without that PR rejects it at apply.";
+const SECRETS_EXTENSION: ExtensionSpec = {
+  name: "secrets",
+  tsType: "{ key: string; value: string }[]",
+  required: false,
+  description:
+    "Secrets upserted with the resource at apply, as key/value pairs; fountainApply sends them as the manifest's " +
+    "inline `secrets` map. Values are write-only upstream and can never be read back or diffed. Write a reference " +
+    "that resolves at build (an env var, a secret-manager lookup), never a literal: FTN001 flags a literal here " +
+    "as it does anywhere else in a declaration.",
+};
 
 const REF_TARGET = {
   agent: `Fountain::${SERVICE}::Agent`,
@@ -135,22 +143,19 @@ const REF_TARGET = {
 };
 
 const RESOURCES: ResourceSpec[] = [
-  { typeName: `Fountain::${SERVICE}::Environment`, request: "EnvironmentRequest", response: "Environment" },
-  { typeName: `Fountain::${SERVICE}::Vault`, request: "VaultRequest", response: "Vault" },
   {
-    typeName: `Fountain::${SERVICE}::Agent`,
-    request: "AgentRequest",
-    response: "Agent",
-    enumExtensions: { runtime: ["acp"] },
-    extensions: [
-      {
-        name: "runtime_command",
-        tsType: "string",
-        required: false,
-        description: `The command line an "acp" agent speaks the Agent Client Protocol over, e.g. "chant acp". ${ACP_NOTE}`,
-      },
-    ],
+    typeName: `Fountain::${SERVICE}::Environment`,
+    request: "EnvironmentRequest",
+    response: "Environment",
+    extensions: [SECRETS_EXTENSION],
   },
+  {
+    typeName: `Fountain::${SERVICE}::Vault`,
+    request: "VaultRequest",
+    response: "Vault",
+    extensions: [SECRETS_EXTENSION],
+  },
+  { typeName: `Fountain::${SERVICE}::Agent`, request: "AgentRequest", response: "Agent" },
   {
     typeName: `Fountain::${SERVICE}::Teammate`,
     request: "TeamAddRequest",
@@ -254,20 +259,12 @@ export function parseFountainOpenAPI(data: string | Buffer): FountainParseResult
         properties.push(refProperty(ref));
         continue;
       }
-      const extraEnum = rspec.enumExtensions?.[name];
-      const constraints = coreExtractConstraints(prop as JsonSchemaProperty);
-      let tsType = resolve(prop);
-      if (extraEnum && extraEnum.length > 0) {
-        const values = [...(prop.enum ?? []), ...extraEnum];
-        constraints.enum = values;
-        tsType = [...values].sort().map((v) => JSON.stringify(v)).join(" | ");
-      }
       properties.push({
         name,
-        tsType,
+        tsType: resolve(prop),
         required: requiredSet.has(name),
         description: prop.description,
-        constraints,
+        constraints: coreExtractConstraints(prop as JsonSchemaProperty),
       });
     }
 
@@ -278,6 +275,15 @@ export function parseFountainOpenAPI(data: string | Buffer): FountainParseResult
     }
 
     for (const ext of rspec.extensions ?? []) {
+      // An extension exists because the spec lacks the prop. Once upstream
+      // describes it, the extension would emit a second copy with chant's
+      // type in place of upstream's, so the build stops and says so.
+      if (ext.name in reqProps) {
+        throw new Error(
+          `fountain parse: ${rspec.request} now declares "${ext.name}", which ${fountainShortName(rspec.typeName)} ` +
+            `carries as a chant extension. Remove the extension from RESOURCES in src/spec/parse.ts.`,
+        );
+      }
       properties.push({
         name: ext.name,
         tsType: ext.tsType,
@@ -386,9 +392,33 @@ function collectRefs(node: unknown, acc: Set<string> = new Set()): Set<string> {
   return acc;
 }
 
-/** An object schema with properties (not a pure enum). */
+/**
+ * An object schema with properties (not a pure enum, and not an open map).
+ *
+ * A schema with named properties and a typed `additionalProperties` is a map
+ * that reserves a few keys, like v0.21.0's `PermissionPolicy`: tool names to
+ * verdicts, plus `ask_timeout`. Emitting it as a class would keep the reserved
+ * keys and drop the map, so it resolves to a `Record` instead.
+ */
 function isObjectSchema(def: OpenAPISchema): boolean {
-  return !!def.properties && Object.keys(def.properties).length > 0 && !isEnumDefinition(def);
+  return (
+    !!def.properties &&
+    Object.keys(def.properties).length > 0 &&
+    !isEnumDefinition(def) &&
+    !isOpenMap(def)
+  );
+}
+
+/** An object whose `additionalProperties` is a schema, not `true` or absent. */
+function isOpenMap(def: OpenAPISchema): boolean {
+  return !!def.additionalProperties && typeof def.additionalProperties === "object";
+}
+
+/** The TypeScript union of a set of member types, deduplicated and sorted. */
+function unionOf(types: string[]): string {
+  const parts = new Set(types.flatMap((t) => t.split(" | ")));
+  if (parts.has("any")) return "any";
+  return [...parts].sort().join(" | ");
 }
 
 // ── Type resolution ────────────────────────────────────────────────
@@ -411,6 +441,12 @@ function resolveType(
     return [...prop.enum].sort().map((v) => JSON.stringify(v)).join(" | ");
   }
 
+  const members = (prop as { oneOf?: OpenAPISchema[]; anyOf?: OpenAPISchema[] }).oneOf ??
+    (prop as { anyOf?: OpenAPISchema[] }).anyOf;
+  if (members && members.length > 0) {
+    return unionOf(members.map((m) => resolveType(m, schemas, emitted)));
+  }
+
   const pt = primaryType(prop.type);
   switch (pt) {
     case "string":
@@ -450,6 +486,13 @@ function resolveRefType(ref: string, schemas: Record<string, OpenAPISchema>, emi
     return [...(def.enum ?? [])].sort().map((v) => JSON.stringify(v)).join(" | ");
   }
 
+  if (isOpenMap(def)) {
+    const value = resolveType(def.additionalProperties as OpenAPISchema, schemas, emitted);
+    // Reserved keys ride in the same map, so their types join the value union.
+    const reserved = Object.values(def.properties ?? {}).map((p) => resolveType(p, schemas, emitted));
+    return `Record<string, ${unionOf([value, ...reserved])}>`;
+  }
+
   if (def.properties) return "Record<string, any>";
 
   const pt = primaryType(def.type);

package/src/spec/spec.test.ts

@@ -0,0 +1,163 @@
+import { afterAll, describe, expect, it, vi } from "vitest";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import ts from "typescript";
+import { join, dirname } from "path";
+import { tmpdir } from "os";
+import { fileURLToPath } from "url";
+import { FOUNTAIN_SPEC_VERSION, fetchSchemas, readSnapshot } from "./fetch";
+
+// No network here, so fetchSchemas always takes the snapshot fallback.
+vi.mock("@intentius/chant/codegen/fetch", () => ({
+  fetchWithCache: () => Promise.reject(new Error("offline (test)")),
+}));
+import { parseFountainOpenAPI, type ParsedProperty } from "./parse";
+
+const snapshotFile = join(dirname(fileURLToPath(import.meta.url)), "fountain-openapi.snapshot.json");
+const snapshot = readFileSync(snapshotFile, "utf-8");
+
+const scratch = mkdtempSync(join(tmpdir(), "fountain-spec-"));
+afterAll(() => rmSync(scratch, { recursive: true, force: true }));
+
+/** Write a spec whose info.version is `version` and return its path. */
+function specAt(version: unknown): string {
+  const file = join(scratch, `spec-${String(version)}.json`);
+  writeFileSync(file, JSON.stringify({ openapi: "3.0.0", info: { title: "fountain", version } }));
+  return file;
+}
+
+describe("snapshot fallback (#2389)", () => {
+  it("is the pinned release", () => {
+    // The committed snapshot is what an offline generate reads. If it lags
+    // the pin, every other assertion in this file is about the wrong spec.
+    expect(() => readSnapshot()).not.toThrow();
+    expect(`v${JSON.parse(snapshot).info.version}`).toBe(FOUNTAIN_SPEC_VERSION);
+  });
+
+  it("refuses a snapshot from another release, naming both versions", () => {
+    expect(() => readSnapshot(specAt("0.16.0"), "v0.21.0")).toThrow(/0\.16\.0.*v0\.21\.0/);
+  });
+
+  it("is what fetchSchemas falls back through when the pinned release cannot be fetched", async () => {
+    await expect(fetchSchemas({ snapshotFile: specAt("0.16.0") })).rejects.toThrow(
+      new RegExp(`fountain 0\\.16\\.0, but the pin is ${FOUNTAIN_SPEC_VERSION.replace(/\./g, "\\.")}`),
+    );
+    const served = await fetchSchemas();
+    expect(JSON.parse(served.get("fountain-openapi.json")!.toString("utf-8")).info.version).toBe("0.21.0");
+  });
+
+  it("refuses a snapshot with no info.version", () => {
+    expect(() => readSnapshot(specAt(undefined), "v0.21.0")).toThrow(/no info\.version.*v0\.21\.0/);
+  });
+
+  it("accepts the tag and the bare version as the same release", () => {
+    expect(readSnapshot(specAt("0.21.0"), "v0.21.0").length).toBeGreaterThan(0);
+    expect(readSnapshot(specAt("v0.21.0"), "v0.21.0").length).toBeGreaterThan(0);
+  });
+});
+
+describe("the generated surface at v0.21.0", () => {
+  const parsed = parseFountainOpenAPI(snapshot);
+  const propsOf = (kind: string): Map<string, ParsedProperty> => {
+    const result = parsed.find((r) => r.resource.typeName === `Fountain::V1::${kind}`);
+    if (!result) throw new Error(`no ${kind} in the parse`);
+    return new Map(result.resource.properties.map((p) => [p.name, p]));
+  };
+
+  it("gives Environment setup_timeout_seconds, with upstream's bounds", () => {
+    const timeout = propsOf("Environment").get("setup_timeout_seconds");
+    expect(timeout?.tsType).toBe("number");
+    expect(timeout?.required).toBe(false);
+    expect(timeout?.constraints).toMatchObject({ minimum: 1, maximum: 900 });
+  });
+
+  it.each(["Environment", "Vault"])("types %s secrets as the authored key/value list", (kind) => {
+    const secrets = propsOf(kind).get("secrets");
+    expect(secrets?.tsType).toBe("{ key: string; value: string }[]");
+    expect(secrets?.required).toBe(false);
+    expect(secrets?.description).toContain("FTN001");
+  });
+
+  it("takes the acp runtime and runtime_command from the spec, with model optional", () => {
+    const agent = propsOf("Agent");
+    expect(agent.get("runtime")?.tsType).toBe('"acp" | "claude" | "codex" | "gemini" | "opencode"');
+    expect(agent.get("runtime")?.required).toBe(true);
+    // Upstream's own description, not chant's extension note.
+    expect(agent.get("runtime_command")?.description).toContain("Required when runtime is acp");
+    expect(agent.get("runtime_command")?.description).not.toContain("extension");
+    expect(agent.get("model")?.required).toBe(false);
+  });
+
+  it("keeps permission_policy a map, with ask_timeout's number in the value union", () => {
+    // v0.21.0 moved the policy behind a PermissionPolicy $ref that has one
+    // named property and a typed additionalProperties. Emitted as a class it
+    // would have only ask_timeout, and { default: "auto_allow" } would stop
+    // compiling.
+    expect(propsOf("Agent").get("permission_policy")?.tsType).toBe(
+      'Record<string, "ask" | "auto_allow" | "auto_deny" | number>',
+    );
+    expect(parsed.some((r) => r.resource.typeName === "Fountain::V1::PermissionPolicy")).toBe(false);
+  });
+
+  it("refuses an extension once upstream declares the prop itself", () => {
+    const spec = JSON.parse(snapshot);
+    spec.components.schemas.VaultRequest.properties.secrets = { type: "object" };
+    expect(() => parseFountainOpenAPI(JSON.stringify(spec))).toThrow(/VaultRequest now declares "secrets"/);
+  });
+});
+
+describe("the generated declarations accept what the skill tells an author to write", () => {
+  // The .d.ts is what a consumer of the published package compiles against.
+  // In-repo, "../generated/index" resolves to the untyped runtime barrel, so a
+  // plain import would check nothing. This compiles a probe against a copy of
+  // the declaration instead. Every accepted line needed a cast at v0.16.0.
+  const dts = join(dirname(snapshotFile), "..", "generated", "index.d.ts");
+
+  function compile(body: string): string[] {
+    const dir = mkdtempSync(join(scratch, "dts-"));
+    writeFileSync(join(dir, "decl.d.ts"), readFileSync(dts, "utf-8"));
+    writeFileSync(
+      join(dir, "probe.ts"),
+      `import type { Agent, Environment, Vault } from "./decl";\n` +
+        `type EnvProps = ConstructorParameters<typeof Environment>[0];\n` +
+        `type VaultProps = ConstructorParameters<typeof Vault>[0];\n` +
+        `type AgentProps = ConstructorParameters<typeof Agent>[0];\n` +
+        body,
+    );
+    const program = ts.createProgram([join(dir, "probe.ts")], {
+      strict: true,
+      noEmit: true,
+      target: ts.ScriptTarget.ES2022,
+      module: ts.ModuleKind.ESNext,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+      types: [],
+    });
+    return ts
+      .getPreEmitDiagnostics(program)
+      .map((d) => ts.flattenDiagnosticMessageText(d.messageText, "\n"));
+  }
+
+  it.skipIf(!existsSync(dts))("with no cast", () => {
+    const errors = compile(`
+      export const env: EnvProps = {
+        name: "box",
+        setup_timeout_seconds: 900,
+        secrets: [{ key: "GITHUB_TOKEN", value: "infisical:///dev/GITHUB_TOKEN" }],
+      };
+      export const vault: VaultProps = { name: "creds", secrets: [{ key: "NPM_TOKEN", value: "infisical:///dev/NPM_TOKEN" }] };
+      // No model: v0.21.0 stopped requiring one, and an acp agent has none.
+      export const agent: AgentProps = {
+        name: "steward",
+        runtime: "acp",
+        runtime_command: "chant acp",
+        permission_policy: { default: "auto_allow", ask_timeout: 600 },
+      };
+    `);
+    expect(errors).toEqual([]);
+  });
+
+  it.skipIf(!existsSync(dts))("and refuse the wire map in place of the authored list", () => {
+    // The probe has to be able to fail, or the case above proves nothing.
+    const errors = compile(`export const vault: VaultProps = { name: "creds", secrets: { NPM_TOKEN: "x" } };`);
+    expect(errors.join("\n")).toMatch(/NPM_TOKEN.*\{ key: string; value: string; \}\[\]/);
+  });
+});