@highstate/cli 0.9.16 → 0.9.19

package/src/shared/library-loader.ts

@@ -1,21 +1,21 @@
 import type { Logger } from "pino"
+import console from "node:console"
 import {
   type Component,
   type ComponentModel,
   type Entity,
+  type EntityModel,
   isComponent,
   isEntity,
   isUnitModel,
-  originalCreate,
 } from "@highstate/contract"
-import { serializeFunction } from "@pulumi/pulumi/runtime/index.js"
 import { Crc32, crc32 } from "@aws-crypto/crc32"
 import { encode } from "@msgpack/msgpack"
-import { int32ToBytes } from "@highstate/backend/shared"
+import { int32ToBytes } from "./utils"
 
 export type Library = Readonly<{
   components: Readonly<Record<string, ComponentModel>>
-  entities: Readonly<Record<string, Entity>>
+  entities: Readonly<Record<string, EntityModel>>
 }>
 
 export async function loadLibrary(logger: Logger, modulePaths: string[]): Promise<Library> {
@@ -26,13 +26,15 @@ export async function loadLibrary(logger: Logger, modulePaths: string[]): Promis
       modules[modulePath] = await import(modulePath)
 
       logger.debug({ modulePath }, "module loaded")
-    } catch (err) {
-      logger.error({ modulePath, err }, "module load failed")
+    } catch (error) {
+      console.error(error)
+
+      throw new Error(`Failed to load module "${modulePath}"`, { cause: error })
     }
   }
 
   const components: Record<string, ComponentModel> = {}
-  const entities: Record<string, Entity> = {}
+  const entities: Record<string, EntityModel> = {}
 
   await _loadLibrary(modules, components, entities)
 
@@ -52,13 +54,13 @@ export async function loadLibrary(logger: Logger, modulePaths: string[]): Promis
 async function _loadLibrary(
   value: unknown,
   components: Record<string, ComponentModel>,
-  entities: Record<string, Entity>,
+  entities: Record<string, EntityModel>,
 ): Promise<void> {
   if (isComponent(value)) {
     const entityHashes: number[] = []
     for (const entity of value.entities.values()) {
-      entity.definitionHash ??= calculateEntityDefinitionHash(entity)
-      entityHashes.push(entity.definitionHash)
+      entity.model.definitionHash ??= calculateEntityDefinitionHash(entity)
+      entityHashes.push(entity.model.definitionHash)
     }
 
     components[value.model.type] = value.model
@@ -68,11 +70,11 @@ async function _loadLibrary(
   }
 
   if (isEntity(value)) {
-    entities[value.type] = value
+    entities[value.type] = value.model
     entities[value.type].definitionHash ??= calculateEntityDefinitionHash(value)
 
     // @ts-expect-error remove the schema since it's not needed in the designer
-    delete value.schema
+    delete value.model.schema
     return
   }
 
@@ -80,6 +82,19 @@ async function _loadLibrary(
     return
   }
 
+  if ("_zod" in value) {
+    // this is a zod schema, we can skip it
+    return
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      await _loadLibrary(item, components, entities)
+    }
+
+    return
+  }
+
   for (const key in value) {
     await _loadLibrary((value as Record<string, unknown>)[key], components, entities)
   }
@@ -96,7 +111,8 @@ async function calculateComponentDefinitionHash(
 
   if (!isUnitModel(component.model)) {
     // 2. for composite components, include the content of the serialized create function
-    const serializedCreate = await serializeFunction(component[originalCreate])
+    // const serializedCreate = await serializeFunction(component[originalCreate])
+    const serializedCreate = { text: "TODO: investigate why serializeFunction hangs" }
     result.update(Buffer.from(serializedCreate.text))
   }
 
@@ -109,5 +125,5 @@ async function calculateComponentDefinitionHash(
 }
 
 function calculateEntityDefinitionHash(entity: Entity): number {
-  return crc32(encode(entity))
+  return crc32(encode(entity.model))
 }

package/src/shared/schema-transformer.spec.ts

@@ -2,7 +2,7 @@ import { describe, it, expect } from "vitest"
 import { applySchemaTransformations } from "./schema-transformer"
 
 describe("applySchemaTransformations", () => {
-  it("should transform simple values to entity/schema structure", async () => {
+  it("should transform simple values using helper functions", async () => {
     const input = `
 const spec = {
   inputs: {
@@ -21,13 +21,16 @@ const spec = {
 
     const result = await applySchemaTransformations(input)
 
-    expect(result).toContain("entity: clusterEntity")
-    expect(result).toContain("schema: Type.Number()")
-    expect(result).toContain("description: `The Kubernetes cluster to deploy on.`")
-    expect(result).toContain("description: `The port number to use.`")
+    expect(result).toContain(
+      "$addInputDescription(clusterEntity, `The Kubernetes cluster to deploy on.`)",
+    )
+    expect(result).toContain("$addArgumentDescription(Type.Number(), `The port number to use.`)")
+    expect(result).toContain(
+      'import { $addArgumentDescription, $addInputDescription } from "@highstate/contract"',
+    )
   })
 
-  it("should inject description into existing meta field", async () => {
+  it("should wrap existing structured objects with helper functions", async () => {
     const input = `
 const spec = {
   args: {
@@ -46,14 +49,13 @@ const spec = {
 
     const result = await applySchemaTransformations(input)
 
+    expect(result).toContain("$addArgumentDescription({")
     expect(result).toContain('displayName: "API Token"')
     expect(result).toContain("sensitive: true")
-    expect(result).toContain("description: `The API token for authentication.`")
-    expect(result).not.toContain("...obj")
-    expect(result).not.toContain("((obj) =>")
+    expect(result).toContain("}, `The API token for authentication.`)")
   })
 
-  it("should add meta field if it doesn't exist in structured object", async () => {
+  it("should wrap structured objects with helper functions", async () => {
     const input = `
 const spec = {
   inputs: {
@@ -69,10 +71,10 @@ const spec = {
 
     const result = await applySchemaTransformations(input)
 
+    expect(result).toContain("$addInputDescription({")
     expect(result).toContain("entity: endpointEntity")
     expect(result).toContain("required: false")
-    expect(result).toContain("meta: {")
-    expect(result).toContain("description: `The target endpoint.`")
+    expect(result).toContain("}, `The target endpoint.`)")
   })
 
   it("should handle $args marker function", async () => {
@@ -88,8 +90,9 @@ const spec = {
 
     const result = await applySchemaTransformations(input)
 
-    expect(result).toContain("schema: Type.String()")
-    expect(result).toContain("description: `The configuration file path.`")
+    expect(result).toContain(
+      "$addArgumentDescription(Type.String(), `The configuration file path.`)",
+    )
   })
 
   it("should handle $inputs marker function", async () => {
@@ -105,8 +108,7 @@ const spec = {
 
     const result = await applySchemaTransformations(input)
 
-    expect(result).toContain("entity: dataEntity")
-    expect(result).toContain("description: `The source data.`")
+    expect(result).toContain("$addInputDescription(dataEntity, `The source data.`)")
   })
 
   it("should handle $outputs marker function", async () => {
@@ -122,8 +124,7 @@ const spec = {
 
     const result = await applySchemaTransformations(input)
 
-    expect(result).toContain("entity: resultEntity")
-    expect(result).toContain("description: `The processed result.`")
+    expect(result).toContain("$addInputDescription(resultEntity, `The processed result.`)")
   })
 
   it("should handle $secrets marker function", async () => {
@@ -139,8 +140,7 @@ const spec = {
 
     const result = await applySchemaTransformations(input)
 
-    expect(result).toContain("schema: Type.String()")
-    expect(result).toContain("description: `The database password.`")
+    expect(result).toContain("$addArgumentDescription(Type.String(), `The database password.`)")
   })
 
   it("should ignore properties without JSDoc comments", async () => {
@@ -158,8 +158,7 @@ const spec = {
     const result = await applySchemaTransformations(input)
 
     expect(result).toContain("cluster: clusterEntity") // unchanged
-    expect(result).toContain("entity: endpointEntity") // transformed
-    expect(result).toContain("description: `Only this one has a comment.`")
+    expect(result).toContain("$addInputDescription(endpointEntity, `Only this one has a comment.`)") // transformed
   })
 
   it("should ignore properties not in target objects", async () => {
@@ -183,7 +182,7 @@ const spec = {
     const result = await applySchemaTransformations(input)
 
     expect(result).toContain('someProperty: "value"') // unchanged
-    expect(result).toContain("entity: clusterEntity") // transformed
+    expect(result).toContain("$addInputDescription(clusterEntity, `This should be transformed.`)") // transformed
   })
 
   it("should clean JSDoc comments properly", async () => {
@@ -200,10 +199,434 @@ const spec = {
 
     const result = await applySchemaTransformations(input)
 
-    expect(result).toContain("schema: Type.String()")
     expect(result).toContain(
-      "description: `This is a description with \\`backticks\\` and \\${template} literals.",
+      "$addArgumentDescription(Type.String(), `This is a description with \\`backticks\\` and \\${template} literals.",
+    )
+    expect(result).toContain("It also has multiple lines.`)")
+  })
+
+  it("should add .meta() to z.object fields with JSDoc comments", async () => {
+    const input = `
+const userSchema = z.object({
+  /**
+   * The user's unique identifier.
+   */
+  id: z.string(),
+  /**
+   * The user's email address.
+   */
+  email: z.string().email(),
+  name: z.string(), // no comment, should not be transformed
+})`
+
+    const result = await applySchemaTransformations(input)
+
+    // Should add import at the top
+    expect(result).toContain(
+      'import { camelCaseToHumanReadable as __camelCaseToHumanReadable } from "@highstate/contract"',
+    )
+
+    // Should add .meta() with both title and description
+    expect(result).toContain(
+      'id: z.string().meta({ title: __camelCaseToHumanReadable("id"), description: `The user\'s unique identifier.` })',
+    )
+    expect(result).toContain(
+      'email: z.string().email().meta({ title: __camelCaseToHumanReadable("email"), description: `The user\'s email address.` })',
+    )
+    expect(result).toContain("name: z.string(), // no comment") // unchanged
+  })
+
+  it("should not add .meta() if already present in z.object fields", async () => {
+    const input = `
+const userSchema = z.object({
+  /**
+   * The user's identifier.
+   */
+  id: z.string().meta({ displayName: "ID" }),
+})`
+
+    const result = await applySchemaTransformations(input)
+
+    // Should not modify the field that already has .meta()
+    expect(result).toContain('id: z.string().meta({ displayName: "ID" })')
+    expect(result).not.toContain("description:")
+  })
+
+  it("should handle nested z.object patterns", async () => {
+    const input = `
+const schema = z.object({
+  user: z.object({
+    /**
+     * The user's name.
+     */
+    name: z.string(),
+    profile: z.object({
+      /**
+       * The user's age.
+       */
+      age: z.number(),
+    }),
+  }),
+})`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).toContain(
+      'name: z.string().meta({ title: __camelCaseToHumanReadable("name"), description: `The user\'s name.` })',
     )
-    expect(result).toContain("It also has multiple lines.`")
+    expect(result).toContain(
+      'age: z.number().meta({ title: __camelCaseToHumanReadable("age"), description: `The user\'s age.` })',
+    )
+  })
+
+  it("should handle multiple JSDoc-commented fields in the same z.object without conflicts", async () => {
+    const input = `
+const networkSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("dhcp"),
+  }),
+  z.object({
+    type: z.literal("static"),
+
+    /**
+     * The IPv4 address to assign to the virtual machine.
+     */
+    address: z.string().optional(),
+
+    /**
+     * The CIDR prefix for the IPv4 address.
+     *
+     * By default, this is set to 24.
+     */
+    prefix: z.number().default(24),
+
+    /**
+     * The IPv4 gateway for the virtual machine.
+     *
+     * If not specified, will be set to the first address in the subnet.
+     */
+    gateway: z.string().optional(),
+  }),
+]).default({ type: "dhcp" })`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).toContain(
+      'address: z.string().optional().meta({ title: __camelCaseToHumanReadable("address"), description: `The IPv4 address to assign to the virtual machine.` })',
+    )
+    expect(result).toContain(
+      'prefix: z.number().default(24).meta({ title: __camelCaseToHumanReadable("prefix"), description: `The CIDR prefix for the IPv4 address.',
+    )
+    expect(result).toContain("By default, this is set to 24.` })")
+    expect(result).toContain(
+      'gateway: z.string().optional().meta({ title: __camelCaseToHumanReadable("gateway"), description: `The IPv4 gateway for the virtual machine.',
+    )
+    expect(result).toContain(
+      "If not specified, will be set to the first address in the subnet.` })",
+    )
+    expect(result).toContain('type: z.literal("static"),') // unchanged, no comment
+  })
+
+  it("should handle z.object fields inside z.discriminatedUnion", async () => {
+    const input = `
+const schema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("dhcp"),
+  }),
+  z.object({
+    type: z.literal("static"),
+    /**
+     * The IPv4 address to assign to the virtual machine.
+     */
+    address: z.string().optional(),
+    /**
+     * The CIDR prefix for the IPv4 address.
+     */
+    prefix: z.number().default(24),
+  }),
+]).default({ type: "dhcp" })`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).toContain(
+      'address: z.string().optional().meta({ title: __camelCaseToHumanReadable("address"), description: `The IPv4 address to assign to the virtual machine.` })',
+    )
+    expect(result).toContain(
+      'prefix: z.number().default(24).meta({ title: __camelCaseToHumanReadable("prefix"), description: `The CIDR prefix for the IPv4 address.` })',
+    )
+    expect(result).toContain('type: z.literal("dhcp"),') // unchanged, no comment
+    expect(result).toContain('type: z.literal("static"),') // unchanged, no comment
+  })
+
+  it("should handle the full defineUnit case with discriminated union and mixed transformations", async () => {
+    const input = `
+var virtualMachine = defineUnit({
+  type: "proxmox.virtual-machine",
+  args: {
+    nodeName: z.string().optional(),
+    cpuType: z.string().default("host"),
+    cores: z.number().default(1),
+    sockets: z.number().default(1),
+    memory: z.number().default(512),
+    /**
+     * The IPv4 address configuration for the virtual machine.
+     */
+    ipv4: {
+      schema: z.discriminatedUnion("type", [
+        z.object({
+          type: z.literal("dhcp")
+        }),
+        z.object({
+          type: z.literal("static"),
+          /**
+           * The IPv4 address to assign to the virtual machine.
+           */
+          address: z.string().optional(),
+          /**
+           * The CIDR prefix for the IPv4 address.
+           *
+           * By default, this is set to 24.
+           */
+          prefix: z.number().default(24),
+          /**
+           * The IPv4 gateway for the virtual machine.
+           *
+           * If not specified, will be set to the first address in the subnet.
+           */
+          gateway: z.string().optional()
+        })
+      ]).default({ type: "dhcp" })
+    },
+    dns: z.string().array().optional(),
+    datastoreId: z.string().optional(),
+    diskSize: z.number().default(8),
+    bridge: z.string().default("vmbr0"),
+    sshPort: z.number().default(22),
+    sshUser: z.string().default("root"),
+    waitForAgent: z.boolean().default(true),
+    vendorData: z.string().optional()
+  },
+  secrets: {
+    sshPassword: z.string().optional()
+  },
+  inputs: {
+    proxmoxCluster: clusterEntity,
+    image: imageEntity,
+    sshKeyPair: {
+      entity: keyPairEntity,
+      required: false
+    },
+    /**
+     * The cloud-init vendor data to use for the virtual machine.
+     *
+     * You can provide a cloud-config from the distribution component.
+     */
+    vendorData: {
+      entity: fileEntity,
+      required: false,
+    }
+  },
+  outputs: serverOutputs,
+  meta: {
+    title: "Proxmox Virtual Machine",
+    description: "The virtual machine on a Proxmox cluster.",
+    category: "Proxmox",
+    icon: "simple-icons:proxmox",
+    iconColor: "#e56901",
+    secondaryIcon: "codicon:vm"
+  },
+  source: {
+    package: "@highstate/proxmox",
+    path: "virtual-machine"
+  }
+});`
+
+    const result = await applySchemaTransformations(input)
+
+    // Should transform args.ipv4 using $addArgumentDescription helper
+    expect(result).toContain("ipv4: $addArgumentDescription({")
+    expect(result).toContain("schema: z.discriminatedUnion")
+    expect(result).toContain("}, `The IPv4 address configuration for the virtual machine.`)")
+
+    // Should add .meta() to z.object fields with JSDoc comments inside the discriminated union
+    expect(result).toContain(
+      'address: z.string().optional().meta({ title: __camelCaseToHumanReadable("address"), description: `The IPv4 address to assign to the virtual machine.` })',
+    )
+    expect(result).toContain(
+      'prefix: z.number().default(24).meta({ title: __camelCaseToHumanReadable("prefix"), description: `The CIDR prefix for the IPv4 address.',
+    )
+    expect(result).toContain("By default, this is set to 24.` })")
+    expect(result).toContain(
+      'gateway: z.string().optional().meta({ title: __camelCaseToHumanReadable("gateway"), description: `The IPv4 gateway for the virtual machine.',
+    )
+    expect(result).toContain(
+      "If not specified, will be set to the first address in the subnet.` })",
+    )
+
+    // Should NOT transform fields without JSDoc comments
+    expect(result).toContain("nodeName: z.string().optional(),") // unchanged
+    expect(result).toContain('cpuType: z.string().default("host"),') // unchanged
+    expect(result).toContain("cores: z.number().default(1),") // unchanged
+    expect(result).toContain("dns: z.string().array().optional(),") // unchanged
+    expect(result).toContain('type: z.literal("dhcp")') // unchanged
+    expect(result).toContain('type: z.literal("static"),') // unchanged
+
+    // Should properly handle inputs.vendorData using $addInputDescription helper
+    expect(result).toContain("vendorData: $addInputDescription({")
+    expect(result).toContain("entity: fileEntity,")
+    expect(result).toContain("required: false,")
+    expect(result).toContain("}, `The cloud-init vendor data to use for the virtual machine.")
+    expect(result).toContain("You can provide a cloud-config from the distribution component.`)")
+
+    // Should NOT transform other inputs without JSDoc
+    expect(result).toContain("proxmoxCluster: clusterEntity,") // unchanged
+    expect(result).toContain("image: imageEntity,") // unchanged
+  })
+
+  it("should add description to defineUnit function with JSDoc", async () => {
+    const input = `
+/**
+ * Installs the Gateway API CRDs to the cluster.
+ */
+export const gatewayApi = defineUnit({
+  type: "k8s.gateway-api",
+  inputs: {
+    k8sCluster: clusterEntity,
+  },
+  outputs: {
+    k8sCluster: clusterEntity,
+  },
+  meta: {
+    title: "Gateway API",
+    icon: "devicon:kubernetes",
+    secondaryIcon: "mdi:api",
+    secondaryIconColor: "#4CAF50",
+    category: "Kubernetes",
+  },
+  source: {
+    package: "@highstate/k8s",
+    path: "units/gateway-api",
+  },
+})`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).toContain("description: `Installs the Gateway API CRDs to the cluster.`")
+    expect(result).toContain('title: "Gateway API"')
+    expect(result).toContain('icon: "devicon:kubernetes"')
+  })
+
+  it("should add meta field to defineEntity without existing meta", async () => {
+    const input = `
+/**
+ * Represents a Kubernetes cluster.
+ */
+export const clusterEntity = defineEntity({
+  type: "k8s.cluster",
+  schema: z.object({
+    name: z.string(),
+    endpoint: z.string(),
+  }),
+})`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).toContain("meta: {")
+    expect(result).toContain("description: `Represents a Kubernetes cluster.`")
+    expect(result).toContain("schema: z.object({")
+  })
+
+  it("should add description to defineComponent function", async () => {
+    const input = `
+/**
+ * A reusable database component.
+ */
+export const database = defineComponent({
+  type: "database",
+  components: {
+    server: serverUnit,
+    storage: storageUnit,
+  },
+  meta: {
+    category: "Database",
+  },
+})`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).toContain("description: `A reusable database component.`")
+    expect(result).toContain('category: "Database"')
+  })
+
+  it("should not transform define functions without JSDoc", async () => {
+    const input = `
+export const simpleUnit = defineUnit({
+  type: "simple",
+  meta: {
+    title: "Simple Unit",
+  },
+})`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).not.toContain("description:")
+    expect(result).toContain('title: "Simple Unit"')
+  })
+
+  it("should not create nested meta.meta.description structure", async () => {
+    const input = `
+/**
+ * Traefik Gateway unit definition for Kubernetes.
+ */
+var traefikGateway = defineUnit({
+  type: "k8s.apps.traefik-gateway.v1",
+  meta: {
+    title: "Traefik Gateway",
+    icon: "simple-icons:traefikproxy",
+    category: "Network",
+  },
+})`
+
+    const result = await applySchemaTransformations(input)
+
+    // Should have description at the correct level
+    expect(result).toContain("meta: {")
+    expect(result).toContain("description: `Traefik Gateway unit definition for Kubernetes.`")
+    expect(result).toContain('title: "Traefik Gateway"')
+    expect(result).toContain('icon: "simple-icons:traefikproxy"')
+    expect(result).toContain('category: "Network"')
+
+    // Should NOT have nested meta.meta structure
+    expect(result).not.toContain("meta: {\\s*meta: {")
+
+    // Verify the structure more precisely - should only have one meta object
+    const metaMatches = (result.match(/meta\s*:\s*\{/g) || []).length
+    expect(metaMatches).toBe(1)
+  })
+
+  it("should replace existing description in defineUnit meta object", async () => {
+    const input = `
+/**
+ * Updated description for the unit.
+ */
+export const testUnit = defineUnit({
+  type: "test",
+  meta: {
+    title: "Test Unit",
+    description: \`Old description.\`,
+    category: "Test",
+  },
+})`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).toContain("description: `Updated description for the unit.`")
+    expect(result).not.toContain("Old description")
+    expect(result).toContain('title: "Test Unit"')
+    expect(result).toContain('category: "Test"')
+
+    // Should still only have one meta object
+    const metaMatches = (result.match(/meta\s*:\s*\{/g) || []).length
+    expect(metaMatches).toBe(1)
   })
 })