@plasm_lang/vercel-agent 0.3.63

package/src/stubs/generator.ts

@@ -0,0 +1,390 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { createEngine, type PlasmEngine } from "../engine/napi-binding.js";
+import { parseCatalogIntrospection, type CatalogIntrospectionJson } from "./catalog-introspection.js";
+import {
+  capabilityNeedsInput,
+  capabilityReturnsScalar,
+  capabilityReturnsVoid,
+  classifyInvokeShape,
+} from "./capability-invoke-shape.js";
+import {
+  capabilityInputTypeName,
+  renderBrandTypes,
+  renderCapabilityInputType,
+  renderEntityRowType,
+} from "./input-type-to-ts.js";
+import { renderProgramStatements } from "./plasm-value-emitter.js";
+import { parseCgsDomain, toLegacyParsedDomain, type ParsedCgsDomain } from "./domain-parser.js";
+import {
+  assignCapabilityBindings,
+  capabilityReturnTypeName,
+  stubEntityNames,
+  type CapabilityBinding,
+} from "./stub-symbols.js";
+
+/** @deprecated Use {@link ParsedCgsDomain} from domain-parser. */
+export interface ParsedEntity {
+  name: string;
+}
+
+/** @deprecated Use {@link ParsedCgsDomain} from domain-parser. */
+export interface ParsedCapability {
+  name: string;
+  entity: string;
+  kind?: string;
+}
+
+/** @deprecated Use {@link ParsedCgsDomain} from domain-parser. */
+export interface ParsedDomain {
+  entryId: string;
+  authScheme?: string;
+  entities: ParsedEntity[];
+  capabilities: ParsedCapability[];
+}
+
+export interface StubGenerationResult {
+  entryId: string;
+  catalogCgsHash: string;
+  outPath: string;
+  generatedAt: string;
+}
+
+const PROVENANCE_RE =
+  /@generated catalog_cgs_hash=([a-f0-9]+) entry_id=([^\s]+)/;
+
+export function computeCatalogCgsHash(domainYaml: string, mappingsYaml: string): string {
+  return createHash("sha256").update(domainYaml).update("\n").update(mappingsYaml).digest("hex");
+}
+
+/** Legacy parser — delegates to {@link parseCgsDomain}. */
+export function parseDomainYaml(raw: string, fallbackEntryId: string): ParsedDomain {
+  return toLegacyParsedDomain(parseCgsDomain(raw, fallbackEntryId));
+}
+
+function toExportName(entryId: string): string {
+  const safe = entryId.replace(/[^a-zA-Z0-9_]/g, "_");
+  return /^[a-zA-Z_]/.test(safe) ? safe : `_${safe}`;
+}
+
+function indent(text: string, spaces: number): string {
+  const pad = " ".repeat(spaces);
+  return text
+    .split("\n")
+    .map((line) => (line ? pad + line : line))
+    .join("\n");
+}
+
+function entityByName(catalog: CatalogIntrospectionJson, name: string) {
+  return catalog.entities.find((e) => e.name === name);
+}
+
+function renderCapabilityFunction(
+  catalog: CatalogIntrospectionJson,
+  binding: CapabilityBinding | undefined,
+): string {
+  const cap = catalog.capabilities.find((c) => c.name === binding?.capability);
+  if (!cap || !binding) {
+    const name = binding?.capability ?? "unknown";
+    return `export async function ${name}(): Promise<unknown> {
+  throw new Error(${JSON.stringify(`${name}: unresolved capability binding`)});
+}`;
+  }
+
+  const entity = entityByName(catalog, cap.entity);
+  if (!entity) {
+    return `export async function ${cap.name}(): Promise<unknown> {
+  throw new Error(${JSON.stringify(`${cap.name}: unknown entity ${cap.entity}`)});
+}`;
+  }
+
+  const shape = binding.invokeShape;
+  const returnType = capabilityReturnTypeName(cap.entity);
+  const scalar = capabilityReturnsScalar(cap);
+  const voidReturn = capabilityReturnsVoid(cap);
+  const needsInput = capabilityNeedsInput(cap, shape, entity.id_field);
+  const inputType = capabilityInputTypeName(cap.name);
+  const optionsArg = "options?: StubInvokeOptions";
+  const params = needsInput ? `input: ${inputType}, ${optionsArg}` : optionsArg;
+
+  const returnTypeTs = voidReturn ? "void" : scalar ? returnType : `${returnType}[]`;
+  const programStmt = renderProgramStatements(
+    binding,
+    cap,
+    catalog.values,
+    shape,
+    entity.id_field,
+    needsInput ? "input" : "input",
+  );
+
+  let programBody: string;
+  if (voidReturn) {
+    programBody = `${programStmt}
+  await executeRows(builder, program, options);`;
+  } else if (needsInput) {
+    programBody = `${programStmt}
+  const result = await executeRows<${returnType}>(builder, program, options);`;
+  } else {
+    programBody = `${programStmt}
+  const result = await executeRows<${returnType}>(builder, program, options);`;
+  }
+
+  let returnStmt = "";
+  if (!voidReturn) {
+    returnStmt = scalar
+      ? `const row = result.rows[0];
+  if (!row) throw new Error(${JSON.stringify(`${cap.name}: empty result`)});
+  return row;`
+      : "return result.rows;";
+  }
+
+  const desc = cap.input_schema?.description ?? cap.name;
+  return `/** ${desc} */
+export async function ${cap.name}(${params}): Promise<${returnTypeTs}> {
+  ${programBody}
+  ${returnStmt}
+}`;
+}
+
+export function renderStubModule(
+  catalog: CatalogIntrospectionJson,
+  generatedAt: string,
+  bindings?: Map<string, CapabilityBinding>,
+): string {
+  const exportName = toExportName(catalog.entry_id);
+  const clientImport = "@plasm_lang/vercel-agent";
+
+  const entityTypes = new Set<string>();
+  const inputTypes = new Set<string>();
+
+  for (const entity of catalog.entities) {
+    const caps = catalog.capabilities.filter((c) => c.entity === entity.name);
+    const fieldNames = new Set<string>();
+    for (const cap of caps) {
+      for (const field of cap.provides) {
+        fieldNames.add(field);
+      }
+    }
+    if (fieldNames.size) {
+      entityTypes.add(renderEntityRowType(entity.name, [...fieldNames], catalog));
+    }
+  }
+
+  for (const cap of catalog.capabilities) {
+    const shape = bindings?.get(cap.name)?.invokeShape ?? classifyInvokeShape(cap);
+    const inputType = renderCapabilityInputType(cap, catalog, shape);
+    if (inputType) inputTypes.add(inputType);
+  }
+
+  const capabilityFns = catalog.capabilities.map((cap) =>
+    renderCapabilityFunction(catalog, bindings?.get(cap.name)),
+  );
+
+  const capsByEntity = new Map<string, typeof catalog.capabilities>();
+  for (const cap of catalog.capabilities) {
+    const list = capsByEntity.get(cap.entity) ?? [];
+    list.push(cap);
+    capsByEntity.set(cap.entity, list);
+  }
+
+  const namespaceBlocks: string[] = [];
+  for (const entity of catalog.entities) {
+    const caps = capsByEntity.get(entity.name) ?? [];
+    if (!caps.length) continue;
+    const entries = caps.map((c) => `${c.name}`).join(",\n");
+    namespaceBlocks.push(`${entity.name}: {\n${indent(entries, 4)},\n  }`);
+  }
+
+  const stubEntities = stubEntityNames(catalog);
+
+  return `/** @generated catalog_cgs_hash=${catalog.catalog_cgs_hash} entry_id=${catalog.entry_id} generated_at=${generatedAt} */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  createCatalogClient,
+  buildDottedArgs,
+  executeRows,
+  plasmBoolean,
+  plasmLiteral,
+  plasmNumber,
+  type StubInvokeOptions,
+} from ${JSON.stringify(clientImport)};
+
+export const catalogCgsHash = ${JSON.stringify(catalog.catalog_cgs_hash)};
+export const entryId = ${JSON.stringify(catalog.entry_id)};
+
+const catalogRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../../catalogs/${catalog.entry_id}",
+);
+
+const stubEntities = ${JSON.stringify(stubEntities)} as const;
+
+const builder = createCatalogClient({
+  entryId,
+  cgsHash: catalogCgsHash,
+  catalogRoot,
+  stubEntities: [...stubEntities],
+});
+
+${renderBrandTypes(catalog)}
+
+${[...entityTypes, ...inputTypes].join("\n\n")}
+
+${capabilityFns.join("\n\n")}
+
+export const ${exportName} = {
+${indent(namespaceBlocks.join(",\n"), 2)},
+  builder,
+  catalogCgsHash,
+  entryId,
+} as const;
+
+export default ${exportName};
+`;
+}
+
+export async function generateStubForCatalog(
+  catalogDir: string,
+  outDir: string,
+  engine?: PlasmEngine,
+): Promise<StubGenerationResult> {
+  const fallbackEntryId = path.basename(catalogDir);
+  const domainYaml = await readFile(path.join(catalogDir, "domain.yaml"), "utf8");
+  const domainMeta = parseCgsDomain(domainYaml, fallbackEntryId);
+  const generatedAt = new Date().toISOString();
+
+  const activeEngine = engine ?? createEngine();
+  await activeEngine.loadCatalog({
+    rootDir: catalogDir,
+    manifest: { entryId: domainMeta.entryId, label: fallbackEntryId },
+  });
+
+  const raw = await activeEngine.introspectCatalog(domainMeta.entryId);
+  const catalog = parseCatalogIntrospection(raw);
+  const bindings = assignCapabilityBindings(catalog);
+  const source = renderStubModule(catalog, generatedAt, bindings);
+
+  await mkdir(outDir, { recursive: true });
+  const outPath = path.join(outDir, `${catalog.entry_id}.ts`);
+  await writeFile(outPath, source, "utf8");
+
+  return {
+    entryId: catalog.entry_id,
+    catalogCgsHash: catalog.catalog_cgs_hash,
+    outPath,
+    generatedAt,
+  };
+}
+
+export async function generateAllStubs(
+  agentRoot: string,
+  options?: { engine?: PlasmEngine },
+): Promise<StubGenerationResult[]> {
+  const catalogsDir = path.join(agentRoot, "catalogs");
+  const outDir = path.join(agentRoot, ".plasm", "stubs");
+  const { access, readdir, stat } = await import("node:fs/promises");
+
+  const engine = options?.engine ?? createEngine();
+
+  let entries;
+  try {
+    entries = await readdir(catalogsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const results: StubGenerationResult[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    const rootDir = path.join(catalogsDir, entry.name);
+    try {
+      const info = await stat(rootDir);
+      if (!info.isDirectory()) continue;
+      await access(path.join(rootDir, "domain.yaml"));
+      await access(path.join(rootDir, "mappings.yaml"));
+    } catch {
+      continue;
+    }
+    results.push(await generateStubForCatalog(rootDir, outDir, engine));
+  }
+  results.sort((a, b) => a.entryId.localeCompare(b.entryId));
+  return results;
+}
+
+/** Generate stub from an arbitrary catalog directory (fixtures / matrix smoke). */
+export async function generateStubFromCatalogDir(
+  catalogDir: string,
+  outDir: string,
+  engine?: PlasmEngine,
+): Promise<StubGenerationResult> {
+  return generateStubForCatalog(catalogDir, outDir, engine);
+}
+
+export interface StubProvenance {
+  catalogCgsHash: string;
+  entryId: string;
+  generatedAt?: string;
+}
+
+export async function readStubProvenance(stubPath: string): Promise<StubProvenance | null> {
+  try {
+    const raw = await readFile(stubPath, "utf8");
+    const match = raw.match(PROVENANCE_RE);
+    if (!match) return null;
+    const generatedMatch = raw.match(/generated_at=([^\s*]+)/);
+    return {
+      catalogCgsHash: match[1],
+      entryId: match[2],
+      generatedAt: generatedMatch?.[1],
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function stubFreshness(
+  liveHash: string,
+  stubPath: string,
+): Promise<{
+  stubPath: string;
+  liveCatalogCgsHash: string;
+  generatedCatalogCgsHash: string | null;
+  fresh: boolean;
+  lastBuiltAt: string | null;
+  validationErrors: string[];
+}> {
+  const validationErrors: string[] = [];
+  let lastBuiltAt: string | null = null;
+  let generatedCatalogCgsHash: string | null = null;
+
+  try {
+    const info = await stat(stubPath);
+    lastBuiltAt = info.mtime.toISOString();
+  } catch {
+    validationErrors.push("stub file missing");
+  }
+
+  const provenance = await readStubProvenance(stubPath);
+  if (!provenance) {
+    validationErrors.push("stub provenance comment missing or invalid");
+  } else {
+    generatedCatalogCgsHash = provenance.catalogCgsHash;
+  }
+
+  const fresh = generatedCatalogCgsHash === liveHash && validationErrors.length === 0;
+  return {
+    stubPath,
+    liveCatalogCgsHash: liveHash,
+    generatedCatalogCgsHash,
+    fresh,
+    lastBuiltAt,
+    validationErrors,
+  };
+}
+
+export type { ParsedCgsDomain } from "./domain-parser.js";
+export { parseCgsDomain } from "./domain-parser.js";

package/src/stubs/input-type-to-ts.ts

@@ -0,0 +1,233 @@
+import type {
+  CapabilityIntrospectionJson,
+  CatalogIntrospectionJson,
+  FieldTypeJson,
+  InputFieldSchemaJson,
+  InputTypeJson,
+  NamedValueSchemaJson,
+} from "./catalog-introspection.js";
+import type { CapabilityInvokeShape } from "./capability-invoke-shape.js";
+import {
+  invokeBodyFields,
+  objectFieldsFromCap,
+  searchFieldName,
+} from "./capability-invoke-shape.js";
+
+export type BrandRegistry = Map<string, string>;
+
+export function entityTypeName(entityName: string): string {
+  return entityName.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+
+export function refBrandName(entityName: string): string {
+  return `Ref${entityTypeName(entityName)}`;
+}
+
+export function idBrandName(entityName: string): string {
+  return `${entityTypeName(entityName)}Id`;
+}
+
+export function buildBrandRegistry(catalog: CatalogIntrospectionJson): BrandRegistry {
+  const out = new Map<string, string>();
+  for (const entity of catalog.entities) {
+    out.set(entity.name, refBrandName(entity.name));
+  }
+  return out;
+}
+
+function resolveFieldType(
+  field: InputFieldSchemaJson,
+  values: Record<string, NamedValueSchemaJson>,
+): FieldTypeJson | InputTypeJson | undefined {
+  if (field.value_ref) {
+    return values[field.value_ref]?.field_type;
+  }
+  return field.input_type;
+}
+
+function fieldTypeToTs(
+  ft: FieldTypeJson | InputTypeJson | undefined,
+  values: Record<string, NamedValueSchemaJson>,
+  brands: BrandRegistry,
+  /** Input positions brand entity_ref; output uses wire string. */
+  inputContext: boolean,
+  allowedValues?: string[],
+): string {
+  if (!ft) return "unknown";
+
+  if (typeof ft === "object" && "type" in ft) {
+    return inputTypeToTs(ft, values, brands, inputContext);
+  }
+
+  const fieldType = ft as FieldTypeJson;
+  if (typeof fieldType === "object" && "entity_ref" in fieldType) {
+    const target = fieldType.entity_ref.target;
+    if (inputContext && brands.has(target)) {
+      return brands.get(target)!;
+    }
+    return "string";
+  }
+
+  switch (fieldType) {
+    case "boolean":
+      return "boolean";
+    case "integer":
+    case "number":
+      return "number";
+    case "string":
+    case "uuid":
+    case "date":
+      return "string";
+    case "blob":
+    case "json":
+      return "unknown";
+    case "select": {
+      const allowed = allowedValues ?? [];
+      if (!allowed.length) return "string";
+      return allowed.map((v) => JSON.stringify(v)).join(" | ");
+    }
+    case "multi_select":
+      return "string[]";
+    case "array":
+      return "unknown[]";
+    default:
+      return "unknown";
+  }
+}
+
+export function inputTypeToTs(
+  input: InputTypeJson,
+  values: Record<string, NamedValueSchemaJson>,
+  brands: BrandRegistry,
+  inputContext = true,
+): string {
+  switch (input.type) {
+    case "none":
+      return "void";
+    case "value": {
+      const allowed = input.allowed_values;
+      return fieldTypeToTs(input.field_type, values, brands, inputContext, allowed);
+    }
+    case "object": {
+      const lines = input.fields.map((f) => {
+        const ft = resolveFieldType(f, values);
+        const allowed =
+          typeof ft === "string" || (typeof ft === "object" && !("type" in ft))
+            ? values[f.value_ref ?? ""]?.allowed_values
+            : undefined;
+        const ts = fieldTypeToTs(ft, values, brands, inputContext, allowed);
+        return `${f.name}${f.required ? "" : "?"}: ${ts};`;
+      });
+      return `{\n  ${lines.join("\n  ")}\n}`;
+    }
+    case "array":
+      return `${inputTypeToTs(input.element_type, values, brands, inputContext)}[]`;
+    case "union": {
+      const variants = input.variants.map((v) => {
+        const body = inputTypeToTs(
+          { type: "object", fields: v.fields },
+          values,
+          brands,
+          inputContext,
+        );
+        const tag = v.constructor_symbol ?? v.name;
+        return `{ readonly kind: ${JSON.stringify(tag)}; ${body.slice(1, -1).trim()} }`;
+      });
+      return variants.join(" | ");
+    }
+    default:
+      return "unknown";
+  }
+}
+
+export function capabilityInputTypeName(capName: string): string {
+  const base = capName
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part[0]!.toUpperCase() + part.slice(1))
+    .join("");
+  return `${base}Input`;
+}
+
+export function renderBrandTypes(catalog: CatalogIntrospectionJson): string {
+  const lines = [
+    "type Brand<B extends string, T> = T & { readonly __brand: B };",
+  ];
+  for (const entity of catalog.entities) {
+    const id = idBrandName(entity.name);
+    const ref = refBrandName(entity.name);
+    lines.push(`export type ${id} = Brand<${JSON.stringify(id)}, string>;`);
+    lines.push(`export type ${ref} = ${id};`);
+  }
+  return lines.join("\n");
+}
+
+export function renderEntityRowType(
+  entityName: string,
+  fieldNames: string[],
+  catalog: CatalogIntrospectionJson,
+): string {
+  const entity = catalog.entities.find((e) => e.name === entityName);
+  if (!entity) return `export type ${entityTypeName(entityName)} = Record<string, unknown>;`;
+
+  const values = catalog.values;
+  const lines: string[] = [];
+  for (const fieldName of fieldNames) {
+    const field = entity.fields.find((f) => f.name === fieldName);
+    if (!field) {
+      lines.push(`${fieldName}?: unknown;`);
+      continue;
+    }
+    const nv = values[field.value_ref];
+    const ts = fieldTypeToTs(nv?.field_type, values, buildBrandRegistry(catalog), false, nv?.allowed_values);
+    lines.push(`${fieldName}${field.required ? "" : "?"}: ${ts};`);
+  }
+  const typeName = entityTypeName(entityName);
+  return `export type ${typeName} = {\n  ${lines.join("\n  ")}\n};`;
+}
+
+export function renderCapabilityInputType(
+  cap: CapabilityIntrospectionJson,
+  catalog: CatalogIntrospectionJson,
+  shape: CapabilityInvokeShape,
+): string | null {
+  const entity = catalog.entities.find((e) => e.name === cap.entity);
+  if (!entity) return null;
+
+  const brands = buildBrandRegistry(catalog);
+  const values = catalog.values;
+  const lines: string[] = [];
+
+  if (
+    shape === "GetById" ||
+    shape === "ScopedUpdate" ||
+    shape === "ScopedAction" ||
+    shape === "ScopedDelete"
+  ) {
+    const ref = brands.get(cap.entity) ?? "string";
+    lines.push(`${entity.id_field}: ${ref};`);
+  }
+
+  const bodyFields = invokeBodyFields(cap, shape, entity.id_field);
+  for (const field of bodyFields) {
+    const ft = resolveFieldType(field, values);
+    const allowed = field.value_ref ? values[field.value_ref]?.allowed_values : undefined;
+    const ts = fieldTypeToTs(ft, values, brands, true, allowed);
+    lines.push(`${field.name}${field.required ? "" : "?"}: ${ts};`);
+  }
+
+  if (shape === "SearchText" || shape === "SearchFiltered") {
+    const q = searchFieldName(cap);
+    if (q && !lines.some((l) => l.startsWith(`${q}:`))) {
+      const field = objectFieldsFromCap(cap).find((f) => f.name === q);
+      if (field) {
+        const ft = resolveFieldType(field, values);
+        const ts = fieldTypeToTs(ft, values, brands, true);
+        lines.unshift(`${q}${field.required ? "" : "?"}: ${ts};`);
+      }
+    }
+  }
+
+  if (!lines.length) return null;
+  return `export type ${capabilityInputTypeName(cap.name)} = {\n  ${lines.join("\n  ")}\n};`;
+}