@plasm_lang/vercel-agent 0.3.63

package/src/stubs/catalog-introspection.ts

@@ -0,0 +1,121 @@
+/** JSON shape from `PlasmEngine.introspectCatalog()` (post-merge CGS). */
+
+export type FieldTypeJson =
+  | "boolean"
+  | "number"
+  | "integer"
+  | "uuid"
+  | "blob"
+  | "string"
+  | "select"
+  | "multi_select"
+  | "date"
+  | "array"
+  | "json"
+  | { entity_ref: { target: string } };
+
+export interface NamedValueSchemaJson {
+  description?: string;
+  field_type: FieldTypeJson;
+  value_format?: string;
+  allowed_values?: string[];
+  string_semantics?: string;
+  array_items?: {
+    value_ref?: string;
+    field_type?: FieldTypeJson;
+    allowed_values?: string[];
+  };
+}
+
+export interface InputFieldSchemaJson {
+  name: string;
+  value_ref?: string;
+  input_type?: InputTypeJson;
+  required?: boolean;
+  description?: string;
+  role?: ParameterRoleJson;
+}
+
+export type ParameterRoleJson =
+  | "filter"
+  | "search"
+  | "sort"
+  | "sort_direction"
+  | "response_control"
+  | "scope";
+
+export type InputTypeJson =
+  | { type: "none" }
+  | {
+      type: "value";
+      field_type: FieldTypeJson;
+      allowed_values?: string[];
+    }
+  | {
+      type: "object";
+      fields: InputFieldSchemaJson[];
+      additional_fields?: boolean;
+    }
+  | {
+      type: "array";
+      element_type: InputTypeJson;
+      min_length?: number;
+      max_length?: number;
+    }
+  | {
+      type: "union";
+      variants: InputVariantSchemaJson[];
+    };
+
+export interface InputVariantSchemaJson {
+  name: string;
+  description?: string;
+  constructor_symbol?: string;
+  fields: InputFieldSchemaJson[];
+  wire: { field: string; value: string };
+}
+
+export interface InputSchemaJson {
+  input_type: InputTypeJson;
+  description?: string;
+}
+
+export interface OutputSchemaJson {
+  type: "side_effect" | "entity" | "collection" | "status" | "custom";
+  description?: string;
+  entity_type?: string;
+}
+
+export interface CapabilityIntrospectionJson {
+  name: string;
+  kind: string;
+  entity: string;
+  invoke_wire_name: string;
+  input_schema: InputSchemaJson | null;
+  provides: string[];
+  output_schema: OutputSchemaJson | null;
+}
+
+export interface EntityFieldIntrospectionJson {
+  name: string;
+  value_ref: string;
+  required: boolean;
+}
+
+export interface EntityIntrospectionJson {
+  name: string;
+  id_field: string;
+  fields: EntityFieldIntrospectionJson[];
+}
+
+export interface CatalogIntrospectionJson {
+  entry_id: string;
+  catalog_cgs_hash: string;
+  entities: EntityIntrospectionJson[];
+  values: Record<string, NamedValueSchemaJson>;
+  capabilities: CapabilityIntrospectionJson[];
+}
+
+export function parseCatalogIntrospection(json: string): CatalogIntrospectionJson {
+  return JSON.parse(json) as CatalogIntrospectionJson;
+}

package/src/stubs/cgs-ts-types.ts

@@ -0,0 +1,164 @@
+import type {
+  CgsCapability,
+  CgsEntity,
+  CgsField,
+  CgsParameter,
+  CgsValueDomain,
+  ParsedCgsDomain,
+} from "./domain-parser.js";
+
+export function valueDomainToTsType(
+  domain: CgsValueDomain | undefined,
+  entityTypes: Map<string, string>,
+): string {
+  if (!domain) return "unknown";
+  switch (domain.type) {
+    case "string":
+    case "uuid":
+    case "date":
+      return "string";
+    case "integer":
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "json":
+      return "unknown";
+    case "entity_ref": {
+      const target = domain.target;
+      if (target && entityTypes.has(target)) {
+        return entityTypes.get(target)!;
+      }
+      return "string";
+    }
+    case "select": {
+      const allowed = domain.allowedValues ?? [];
+      if (!allowed.length) return "string";
+      return allowed.map((v) => JSON.stringify(v)).join(" | ");
+    }
+    case "array":
+      return "unknown[]";
+    default:
+      return "unknown";
+  }
+}
+
+function fieldByName(entity: CgsEntity, name: string): CgsField | undefined {
+  return entity.fields.find((f) => f.name === name);
+}
+
+function resolveFieldTsType(
+  fieldName: string,
+  entity: CgsEntity,
+  values: Map<string, CgsValueDomain>,
+  entityTypes: Map<string, string>,
+  /** Wire row JSON uses string ids for entity_ref fields, not nested objects. */
+  outputField = false,
+): { type: string; optional: boolean } {
+  const field = fieldByName(entity, fieldName);
+  if (!field) return { type: "unknown", optional: true };
+  const domain = values.get(field.valueRef);
+  if (outputField && domain?.type === "entity_ref") {
+    return { type: "string", optional: !field.required };
+  }
+  return {
+    type: valueDomainToTsType(domain, entityTypes),
+    optional: !field.required,
+  };
+}
+
+export function entityTypeName(entityName: string): string {
+  return entityName.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+
+export function buildEntityTypeMap(domain: ParsedCgsDomain): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const entity of domain.entities) {
+    out.set(entity.name, entityTypeName(entity.name));
+  }
+  return out;
+}
+
+export function renderEntityType(
+  entity: CgsEntity,
+  domain: ParsedCgsDomain,
+  fieldNames: string[],
+): string {
+  const entityTypes = buildEntityTypeMap(domain);
+  const lines: string[] = [];
+  for (const fieldName of fieldNames) {
+    const { type, optional } = resolveFieldTsType(
+      fieldName,
+      entity,
+      domain.values,
+      entityTypes,
+      true,
+    );
+    lines.push(`${fieldName}${optional ? "?" : ""}: ${type};`);
+  }
+  const typeName = entityTypeName(entity.name);
+  return `export type ${typeName} = {\n  ${lines.join("\n  ")}\n};`;
+}
+
+export function effectiveProvides(cap: CgsCapability, entity: CgsEntity): string[] {
+  if (cap.provides.length) return cap.provides;
+  const names = entity.fields.map((f) => f.name);
+  const idIdx = names.indexOf(entity.idField);
+  if (idIdx > 0) {
+    names.splice(idIdx, 1);
+    names.unshift(entity.idField);
+  }
+  return names;
+}
+
+export function capabilityInputTypeName(cap: CgsCapability): string {
+  const base = cap.name
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part[0]!.toUpperCase() + part.slice(1))
+    .join("");
+  return `${base}Input`;
+}
+
+export function renderCapabilityInputType(
+  cap: CgsCapability,
+  entity: CgsEntity,
+  domain: ParsedCgsDomain,
+): string | null {
+  const entityTypes = buildEntityTypeMap(domain);
+  const kind = cap.kind.toLowerCase();
+  const lines: string[] = [];
+
+  if (kind === "get") {
+    const idField = fieldByName(entity, entity.idField);
+    const idType = idField
+      ? valueDomainToTsType(domain.values.get(idField.valueRef), entityTypes)
+      : "string";
+    lines.push(`${entity.idField}: ${idType};`);
+  } else {
+    for (const param of cap.parameters) {
+      const domainRow = domain.values.get(param.valueRef);
+      const optional = !param.required;
+      lines.push(
+        `${param.name}${optional ? "?" : ""}: ${valueDomainToTsType(domainRow, entityTypes)};`,
+      );
+    }
+  }
+
+  if (!lines.length) return null;
+  return `export type ${capabilityInputTypeName(cap)} = {\n  ${lines.join("\n  ")}\n};`;
+}
+
+export function capabilityNeedsInput(cap: CgsCapability): boolean {
+  const kind = cap.kind.toLowerCase();
+  if (kind === "get") return true;
+  return cap.parameters.length > 0;
+}
+
+export function parameterTsType(
+  param: CgsParameter,
+  domain: ParsedCgsDomain,
+): string {
+  const entityTypes = buildEntityTypeMap(domain);
+  return valueDomainToTsType(domain.values.get(param.valueRef), entityTypes);
+}

package/src/stubs/domain-parser.ts

@@ -0,0 +1,203 @@
+import yaml from "js-yaml";
+
+export interface CgsValueDomain {
+  key: string;
+  type: string;
+  target?: string;
+  allowedValues?: string[];
+  description?: string;
+  stringSemantics?: string;
+}
+
+export interface CgsField {
+  name: string;
+  valueRef: string;
+  required: boolean;
+  description?: string;
+}
+
+export interface CgsEntity {
+  name: string;
+  description?: string;
+  idField: string;
+  fields: CgsField[];
+}
+
+export interface CgsParameter {
+  name: string;
+  valueRef: string;
+  required: boolean;
+  role?: string;
+  description?: string;
+}
+
+export interface CgsCapability {
+  name: string;
+  entity: string;
+  kind: string;
+  description?: string;
+  parameters: CgsParameter[];
+  provides: string[];
+}
+
+export interface ParsedCgsDomain {
+  entryId: string;
+  authScheme?: string;
+  entities: CgsEntity[];
+  capabilities: CgsCapability[];
+  values: Map<string, CgsValueDomain>;
+}
+
+type RawDomain = {
+  entry_id?: string;
+  auth?: { scheme?: string };
+  entities?: Record<
+    string,
+    {
+      description?: string;
+      id_field?: string;
+      fields?: Record<
+        string,
+        {
+          value_ref?: string;
+          required?: boolean;
+          description?: string;
+        }
+      >;
+    }
+  >;
+  capabilities?: Record<
+    string,
+    {
+      description?: string;
+      kind?: string;
+      entity?: string;
+      parameters?: Array<{
+        name?: string;
+        value_ref?: string;
+        required?: boolean;
+        role?: string;
+        description?: string;
+      }>;
+      provides?: string[];
+    }
+  >;
+  values?: Record<
+    string,
+    {
+      type?: string;
+      target?: string;
+      allowed_values?: string[];
+      description?: string;
+      string_semantics?: string;
+    }
+  >;
+};
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+/** Parse `domain.yaml` into a CGS-shaped model for stub generation. */
+export function parseCgsDomain(raw: string, fallbackEntryId: string): ParsedCgsDomain {
+  const doc = yaml.load(raw) as RawDomain | null;
+  if (!doc || typeof doc !== "object") {
+    throw new Error("domain.yaml: expected mapping at root");
+  }
+
+  const entryId = asString(doc.entry_id)?.trim() || fallbackEntryId;
+  const authScheme = asString(doc.auth?.scheme);
+
+  const values = new Map<string, CgsValueDomain>();
+  for (const [key, row] of Object.entries(doc.values ?? {})) {
+    if (!row || typeof row !== "object") continue;
+    const type = asString(row.type);
+    if (!type) continue;
+    values.set(key, {
+      key,
+      type,
+      target: asString(row.target),
+      allowedValues: Array.isArray(row.allowed_values)
+        ? row.allowed_values.filter((v): v is string => typeof v === "string")
+        : undefined,
+      description: asString(row.description),
+      stringSemantics: asString(row.string_semantics),
+    });
+  }
+
+  const entities: CgsEntity[] = [];
+  for (const [name, entity] of Object.entries(doc.entities ?? {})) {
+    if (!entity || typeof entity !== "object") continue;
+    const fields: CgsField[] = [];
+    for (const [fieldName, field] of Object.entries(entity.fields ?? {})) {
+      if (!field || typeof field !== "object") continue;
+      const valueRef = asString(field.value_ref);
+      if (!valueRef) continue;
+      fields.push({
+        name: fieldName,
+        valueRef,
+        required: field.required === true,
+        description: asString(field.description),
+      });
+    }
+    entities.push({
+      name,
+      description: asString(entity.description),
+      idField: asString(entity.id_field) ?? "id",
+      fields,
+    });
+  }
+
+  const capabilities: CgsCapability[] = [];
+  for (const [name, cap] of Object.entries(doc.capabilities ?? {})) {
+    if (!cap || typeof cap !== "object") continue;
+    const entity = asString(cap.entity);
+    const kind = asString(cap.kind);
+    if (!entity || !kind) continue;
+    const parameters: CgsParameter[] = [];
+    for (const param of cap.parameters ?? []) {
+      if (!param || typeof param !== "object") continue;
+      const paramName = asString(param.name);
+      const valueRef = asString(param.value_ref);
+      if (!paramName || !valueRef) continue;
+      parameters.push({
+        name: paramName,
+        valueRef,
+        required: param.required === true,
+        role: asString(param.role),
+        description: asString(param.description),
+      });
+    }
+    capabilities.push({
+      name,
+      entity,
+      kind,
+      description: asString(cap.description),
+      parameters,
+      provides: Array.isArray(cap.provides)
+        ? cap.provides.filter((v): v is string => typeof v === "string")
+        : [],
+    });
+  }
+
+  return { entryId, authScheme, entities, capabilities, values };
+}
+
+/** Legacy shape for operator routes (entity/capability counts). */
+export function toLegacyParsedDomain(domain: ParsedCgsDomain): {
+  entryId: string;
+  authScheme?: string;
+  entities: Array<{ name: string }>;
+  capabilities: Array<{ name: string; entity: string; kind?: string }>;
+} {
+  return {
+    entryId: domain.entryId,
+    authScheme: domain.authScheme,
+    entities: domain.entities.map((e) => ({ name: e.name })),
+    capabilities: domain.capabilities.map((c) => ({
+      name: c.name,
+      entity: c.entity,
+      kind: c.kind,
+    })),
+  };
+}