@highstate/contract 0.19.1 → 0.20.0

package/src/instance.ts

@@ -1,7 +1,10 @@
-import type { Entity, EntityTypes } from "./entity"
-import type { boundaryInput, boundaryInputs } from "./evaluation"
+/** biome-ignore-all lint/suspicious/noExplicitAny: for simplicity of the API, maybe fix later */
+
+import type { Entity, EntityIncludeRef, EntityTypes } from "./entity"
 import { z } from "zod"
 import { componentKindSchema } from "./component"
+import { boundaryInput } from "./evaluation"
+import { createInput, createNonProvidedInput } from "./instance-input"
 import {
   type GenericName,
   genericNameSchema,
@@ -12,31 +15,235 @@ import {
 
 declare const type: unique symbol
 
-export type InstanceInput<TTypes extends EntityTypes = EntityTypes> = {
+export type InstanceInput = z.infer<typeof instanceInputSchema>
+
+export type RuntimeInput<
+  TTypes extends EntityTypes = EntityTypes,
+  TPath extends string | undefined = string | undefined,
+> = {
   [type]?: TTypes
-  [boundaryInput]?: InstanceInput
-  instanceId: InstanceId
-  output: string
+  [boundaryInput]: InstanceInput
+} & (
+  | ({
+      provided: true
+      instanceId: InstanceId
+      output: string
+    } & (undefined extends TPath ? { path?: string } : { path: TPath }))
+  | {
+      provided: false
+      path?: string
+    }
+)
+
+export type MultipleInput<
+  TInput extends RuntimeInput = RuntimeInput,
+  TSelectors extends Record<string, unknown> = Record<never, never>,
+> = TInput[] &
+  TSelectors & {
+    [boundaryInput]: InstanceInput
+    path?: string
+  }
+
+type RequiredInputChildValue<TValue> = TValue extends RuntimeInput
+  ? RequiredInput<TValue>
+  : TValue extends MultipleInput<infer TItem, infer TSelectors>
+    ? MultipleInput<RequiredInput<TItem>, RequiredInputChildSelectors<TSelectors>>
+    : TValue extends Array<infer TItem>
+      ? Array<RequiredInputChildValue<TItem>>
+      : TValue
+
+type RequiredInputChildSelectors<TSelectors extends Record<string, unknown>> = {
+  [K in keyof TSelectors]: RequiredInputChildValue<TSelectors[K]>
+}
+
+type RequiredInputChildren<TInput extends RuntimeInput> = {
+  [K in keyof TInput as K extends
+    | "instanceId"
+    | "output"
+    | "path"
+    | "provided"
+    | typeof boundaryInput
+    | typeof type
+    ? never
+    : K]: RequiredInputChildValue<TInput[K]>
 }
 
+type RequiredInputProvidedBranch<TInput extends RuntimeInput> = Extract<TInput, { provided: true }>
+
+type StrictRequiredInput<TInput extends RuntimeInput> = RequiredInputProvidedBranch<TInput> &
+  RequiredInputChildren<RequiredInputProvidedBranch<TInput>>
+
+export type RequiredInput<TInput extends RuntimeInput = RuntimeInput> = StrictRequiredInput<TInput>
+
+type RequiredMultipleInputSelectors<TInput extends RuntimeInput> = LiftMultipleSelectorFields<
+  RequiredInputChildren<RequiredInputProvidedBranch<TInput>>
+>
+
+export type RequiredMultipleInput<TInput extends RuntimeInput = RuntimeInput> = MultipleInput<
+  RequiredInput<TInput>,
+  RequiredMultipleInputSelectors<TInput>
+>
+
+export type RequiredMultipleInputs<TInput extends RuntimeInput = RuntimeInput> =
+  RequiredMultipleInput<TInput>
+
 export type EntityInput<TEntity extends Entity> = TEntity extends Entity<
   VersionedName,
-  infer TImplementedTypes
+  infer TImplementedTypes,
+  z.ZodTypeAny,
+  unknown,
+  unknown,
+  infer TIncludes
 >
-  ? InstanceInput<TImplementedTypes>
+  ? RuntimeInput<TImplementedTypes, undefined> &
+      (TIncludes extends Record<string, EntityIncludeRef>
+        ? EntityInputIncludes<TIncludes>
+        : Record<never, never>)
   : never
 
-export type OptionalInstanceInput<TTypes extends EntityTypes = EntityTypes> =
-  | ({ provided: true } & InstanceInput<TTypes>)
-  | { provided: false; [boundaryInput]?: InstanceInput }
+export type RequiredEntityInput<TEntity extends Entity> = RequiredInput<EntityInput<TEntity>>
+
+type EntityInputDepth = [1, 1, 1, 1]
+
+type DecDepth<T extends readonly unknown[]> = T extends readonly [unknown, ...infer Rest]
+  ? Rest
+  : readonly []
+
+type ResolveIncludeEntity<TIncludeRef> = TIncludeRef extends { entity: infer E }
+  ? E extends () => infer ER
+    ? ER
+    : E
+  : TIncludeRef
+
+type IncludeMultiple<TIncludeRef> = TIncludeRef extends { multiple?: infer M }
+  ? M extends true
+    ? true
+    : false
+  : false
+
+type IncludeRequired<TIncludeRef> = TIncludeRef extends { required?: infer R }
+  ? R extends false
+    ? false
+    : true
+  : true
+
+type IncludeRefValue<
+  TIncludeRef,
+  TDepth extends readonly unknown[],
+> = ResolveIncludeEntity<TIncludeRef> extends infer TEntity
+  ? TEntity extends Entity
+    ? IncludeMultiple<TIncludeRef> extends true
+      ? MultipleInput<
+          EntityInputWithDepth<TEntity, TDepth>,
+          TDepth extends readonly []
+            ? Record<never, never>
+            : TEntity extends Entity<
+                  VersionedName,
+                  EntityTypes,
+                  z.ZodTypeAny,
+                  unknown,
+                  unknown,
+                  infer TIncludes
+                >
+              ? TIncludes extends Record<string, EntityIncludeRef>
+                ? LiftMultipleSelectorFields<EntityInputIncludes<TIncludes, DecDepth<TDepth>>>
+                : Record<never, never>
+              : Record<never, never>
+        >
+      : IncludeRequired<TIncludeRef> extends false
+        ? OptionalEntityInput<TEntity, TDepth>
+        : EntityInputWithDepth<TEntity, TDepth>
+    : never
+  : never
 
-export type InstanceInputGroup<TTypes extends EntityTypes = EntityTypes> =
-  InstanceInput<TTypes>[] & {
-    [boundaryInputs]?: InstanceInputGroup<TTypes>
-  }
+type OptionalEntityInput<TEntity extends Entity, TDepth extends readonly unknown[]> =
+  | ({ provided: true } & EntityInputWithDepth<TEntity, TDepth>)
+  | ({ provided: false; [boundaryInput]: InstanceInput } & OptionalizedInputFields<
+      EntityInputWithDepth<TEntity, TDepth>
+    >)
+
+type OptionalizeInputValue<T> = [T] extends [InstanceInput]
+  ? RuntimeInput
+  : T extends MultipleInput<infer TItem, infer TSelectors>
+    ? MultipleInput<OptionalizeInputValue<TItem>, OptionalizedSelectorFields<TSelectors>>
+    : T extends Array<infer TItem>
+      ? Array<OptionalizeInputValue<TItem>>
+      : T
+
+type OptionalizedSelectorFields<TSelectors extends Record<string, unknown>> = {
+  [K in keyof TSelectors]: OptionalizeInputValue<TSelectors[K]>
+}
+
+type RuntimeInputSelectorFields<TInput extends RuntimeInput> = {
+  [K in keyof TInput as K extends
+    | "instanceId"
+    | "output"
+    | "path"
+    | "provided"
+    | typeof boundaryInput
+    | typeof type
+    ? never
+    : K]: LiftMultipleSelectorValue<TInput[K]>
+}
+
+type LiftMultipleSelectorValue<T> = T extends MultipleInput<infer TItem, infer TSelectors>
+  ? MultipleInput<TItem, LiftMultipleSelectorFields<TSelectors>>
+  : T extends RuntimeInput
+    ? MultipleInput<T, RuntimeInputSelectorFields<T>>
+    : T
+
+type LiftMultipleSelectorFields<TSelectors extends Record<string, unknown>> = {
+  [K in keyof TSelectors]: LiftMultipleSelectorValue<TSelectors[K]>
+}
+
+type OptionalizedInputFields<TInput extends RuntimeInput> = {
+  [K in keyof TInput as K extends "instanceId" | "output" | "provided" | typeof boundaryInput
+    ? never
+    : K]: OptionalizeInputValue<TInput[K]>
+}
+
+type EntityInputWithDepth<
+  TEntity extends Entity,
+  TDepth extends readonly unknown[],
+> = TEntity extends Entity<
+  VersionedName,
+  infer TImplementedTypes,
+  z.ZodTypeAny,
+  unknown,
+  unknown,
+  infer TIncludes
+>
+  ? RuntimeInput<TImplementedTypes, undefined> &
+      (TDepth extends readonly []
+        ? Record<never, never>
+        : TIncludes extends Record<string, EntityIncludeRef>
+          ? EntityInputIncludes<TIncludes, DecDepth<TDepth>>
+          : Record<never, never>)
+  : never
+
+type EntityInputIncludes<
+  TIncludes extends Record<string, EntityIncludeRef>,
+  TDepth extends readonly unknown[] = EntityInputDepth,
+> = TIncludes extends Record<string, never>
+  ? Record<never, never>
+  : string extends keyof TIncludes
+    ? Record<never, never>
+    : {
+        [K in keyof TIncludes]: IncludeRefValue<TIncludes[K], TDepth>
+      }
+
+export type InstanceInputGroup<TTypes extends EntityTypes = EntityTypes> = MultipleInput<
+  RuntimeInput<TTypes>
+>
+
+type SelectInputResult<TInput extends RuntimeInput> = TInput extends RequiredInput<infer TRuntime>
+  ? TRuntime
+  : TInput
 
 export function inputKey(input: InstanceInput): string {
-  return `${input.instanceId}:${input.output}`
+  return input.path
+    ? `${input.instanceId}:${input.output}:${input.path}`
+    : `${input.instanceId}:${input.output}`
 }
 
 export const positionSchema = z.object({
@@ -53,6 +260,7 @@ export type InstanceId = z.infer<typeof instanceIdSchema>
 export const instanceInputSchema = z.object({
   instanceId: instanceIdSchema,
   output: z.string(),
+  path: z.string().optional(),
 })
 
 export const hubInputSchema = z.object({
@@ -209,52 +417,52 @@ export function parseInstanceId(
   return parts as [VersionedName, GenericName]
 }
 
-export function findInput<T extends EntityTypes>(
-  inputs: InstanceInput<T>[],
+/**
+ * Selects a single input from a group by instance id or instance name.
+ *
+ * The function accepts a plain array but still preserves Highstate boundary semantics.
+ * It first tries to read boundary metadata from the array object itself and then falls back
+ * to the first item boundary when needed.
+ *
+ * @param inputs The input group to search in.
+ * @param name The instance id or instance name to select.
+ * @returns The selected input with inherited group boundary, or a provided-false input when missing.
+ */
+export function selectInput<TInput extends RuntimeInput>(
+  inputs: TInput[] & Partial<{ [boundaryInput]: InstanceInput }>,
   name: string,
-): InstanceInput<T> | null {
-  const matchedInputs = inputs.filter(
-    input => parseInstanceId(input.instanceId)[1] === name || input.instanceId === name,
-  )
+): SelectInputResult<TInput> {
+  const groupBoundary = inputs[boundaryInput] ?? inputs[0]?.[boundaryInput]
 
-  if (matchedInputs.length === 0) {
-    return null
-  }
-
-  if (matchedInputs.length > 1) {
+  if (inputs.length === 0 && !groupBoundary) {
     throw new Error(
-      `Multiple inputs found for "${name}": ${matchedInputs.map(input => input.instanceId).join(", ")}. Specify the full instance id to disambiguate.`,
+      `Cannot select input "${name}": empty input group has no boundary metadata to build a missing input reference.`,
     )
   }
 
-  return matchedInputs[0]
-}
-
-export function findRequiredInput<T extends EntityTypes>(
-  inputs: InstanceInput<T>[],
-  name: string,
-): InstanceInput<T> {
-  const input = findInput(inputs, name)
+  const input = inputs.find(
+    input =>
+      input.provided &&
+      (input.instanceId === name || parseInstanceId(input.instanceId)[1] === name),
+  )
 
-  if (input === null) {
-    throw new Error(`Required input "${name}" not found.`)
-  }
+  if (!input || !input.provided) {
+    const fallbackBoundary =
+      groupBoundary ??
+      inputs.find(input => Boolean(input[boundaryInput]))?.[boundaryInput] ??
+      inputs[0]?.[boundaryInput]
 
-  return input
-}
+    if (!fallbackBoundary) {
+      throw new Error(
+        `Cannot select input "${name}": input group has no boundary metadata to build a missing input reference.`,
+      )
+    }
 
-export function findInputs<T extends EntityTypes>(
-  inputs: InstanceInput<T>[],
-  names: string[],
-): InstanceInput<T>[] {
-  return names.map(name => findInput(inputs, name)).filter(Boolean) as InstanceInput<T>[]
-}
+    return createNonProvidedInput(fallbackBoundary) as SelectInputResult<TInput>
+  }
 
-export function findRequiredInputs<T extends EntityTypes>(
-  inputs: InstanceInput<T>[],
-  names: string[],
-): InstanceInput<T>[] {
-  return names.map(name => findRequiredInput(inputs, name))
+  const boundary = groupBoundary ?? input[boundaryInput]
+  return createInput(input, { boundary }) as SelectInputResult<TInput>
 }
 
 /**
@@ -265,8 +473,7 @@ export function findRequiredInputs<T extends EntityTypes>(
 export enum HighstateSignature {
   Artifact = "d55c63ac-3174-4756-808f-f778e99af0d1",
   Yaml = "c857cac5-caa6-4421-b82c-e561fbce6367",
-  Id = "348d020e-0d9e-4ae7-9415-b91af99f5339",
-  Ref = "6d7f9da0-9cb6-496d-b72e-cf85ee4d9cf8",
+  Secret = "240e5789-6ae4-4b22-b9d8-87169e8b4bab",
 }
 
 export const yamlValueSchema = z.object({
@@ -274,17 +481,6 @@ export const yamlValueSchema = z.object({
   value: z.string(),
 })
 
-export const objectWithIdSchema = z.object({
-  [HighstateSignature.Id]: z.literal(true),
-  id: z.number(),
-  value: z.unknown(),
-})
-
-export const objectRefSchema = z.object({
-  [HighstateSignature.Ref]: z.literal(true),
-  id: z.number(),
-})
-
 export type YamlValue = z.infer<typeof yamlValueSchema>
 
 export const fileMetaSchema = z.object({
@@ -351,3 +547,49 @@ export const instanceStatusFieldSchema = z.object({
 
 export type InstanceStatusFieldValue = z.infer<typeof instanceStatusFieldValueSchema>
 export type InstanceStatusField = z.infer<typeof instanceStatusFieldSchema>
+
+export function secretSchema<TSchema extends z.ZodType>(
+  schema: TSchema,
+): z.ZodCodec<
+  z.ZodUnion<
+    [
+      z.ZodObject<{
+        [HighstateSignature.Secret]: z.ZodLiteral<true>
+        value: TSchema
+      }>,
+      TSchema,
+    ]
+  >,
+  z.ZodObject<{
+    [HighstateSignature.Secret]: z.ZodLiteral<true>
+    value: TSchema
+  }>
+> {
+  const secretType = z.object({
+    [HighstateSignature.Secret]: z.literal(true),
+    value: schema,
+  })
+
+  return z.codec(z.union([secretType, schema]), secretType, {
+    decode: value =>
+      typeof value === "object" && value !== null && HighstateSignature.Secret in value
+        ? (value as any)
+        : { [HighstateSignature.Secret]: true, value },
+    encode: value => value as any,
+  })
+}
+
+export type Secret<T> = {
+  [HighstateSignature.Secret]: true
+  value: T
+}
+
+/**
+ * Checks if the given value is a Secret.
+ *
+ * @param value The value to check.
+ * @returns True if the value is a Secret, false otherwise.
+ */
+export function isSecret<T>(value: unknown): value is Secret<T> {
+  return typeof value === "object" && value !== null && HighstateSignature.Secret in value
+}

package/src/json-schema.ts

@@ -0,0 +1,115 @@
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Normalizes JSON schema produced by Zod exports.
+ *
+ * In particular, it merges intersections of object schemas represented as
+ * `allOf: [{ type: "object", ... }, { type: "object", ... }, ...]` into a single
+ * object schema so that validators treat `additionalProperties` consistently.
+ */
+export function fixJsonSchema(schema: unknown): unknown {
+  if (!isRecord(schema)) {
+    return schema
+  }
+
+  const allOf = schema.allOf
+  if (Array.isArray(allOf) && allOf.length > 0) {
+    const objectSchemas: Record<string, unknown>[] = []
+    const otherSchemas: unknown[] = []
+
+    for (const item of allOf) {
+      if (isRecord(item) && item.type === "object") {
+        objectSchemas.push(item)
+        continue
+      }
+
+      otherSchemas.push(item)
+    }
+
+    if (objectSchemas.length > 1) {
+      const required = new Set<string>()
+      const properties: Record<string, unknown> = {}
+      let additionalProperties: unknown
+
+      for (const objectSchema of objectSchemas) {
+        const objectRequired = objectSchema.required
+        if (Array.isArray(objectRequired)) {
+          for (const key of objectRequired) {
+            if (typeof key === "string") {
+              required.add(key)
+            }
+          }
+        }
+
+        const objectProperties = objectSchema.properties
+        if (isRecord(objectProperties)) {
+          for (const [key, value] of Object.entries(objectProperties)) {
+            const existing = properties[key]
+            if (existing === undefined) {
+              properties[key] = value
+              continue
+            }
+
+            properties[key] = { allOf: [existing, value] }
+          }
+        }
+
+        if ("additionalProperties" in objectSchema) {
+          if (additionalProperties === undefined) {
+            additionalProperties = objectSchema.additionalProperties
+          } else if (additionalProperties !== objectSchema.additionalProperties) {
+            additionalProperties = false
+          }
+        }
+      }
+
+      const mergedObjectSchema: Record<string, unknown> = {
+        type: "object",
+        properties,
+        ...(required.size > 0 ? { required: Array.from(required) } : {}),
+        ...(additionalProperties !== undefined
+          ? { additionalProperties }
+          : { additionalProperties: false }),
+      }
+
+      const merged =
+        otherSchemas.length === 0
+          ? mergedObjectSchema
+          : {
+              ...schema,
+              allOf: [mergedObjectSchema, ...otherSchemas],
+            }
+
+      return fixJsonSchema(merged)
+    }
+  }
+
+  const next: Record<string, unknown> = { ...schema }
+
+  if (Array.isArray(next.allOf)) {
+    next.allOf = next.allOf.map(fixJsonSchema)
+  }
+  if (Array.isArray(next.anyOf)) {
+    next.anyOf = next.anyOf.map(fixJsonSchema)
+  }
+  if (Array.isArray(next.oneOf)) {
+    next.oneOf = next.oneOf.map(fixJsonSchema)
+  }
+  if (isRecord(next.properties)) {
+    next.properties = Object.fromEntries(
+      Object.entries(next.properties).map(([key, value]) => [key, fixJsonSchema(value)]),
+    )
+  }
+  if (isRecord(next.items)) {
+    next.items = fixJsonSchema(next.items)
+  } else if (Array.isArray(next.items)) {
+    next.items = next.items.map(fixJsonSchema)
+  }
+  if (isRecord(next.additionalProperties)) {
+    next.additionalProperties = fixJsonSchema(next.additionalProperties)
+  }
+
+  return next
+}

package/src/pulumi.ts

@@ -1,33 +1,49 @@
 import { parse } from "yaml"
 import { z } from "zod"
-import { entityInclusionSchema } from "./entity"
 import {
   fileMetaSchema,
   HighstateSignature,
-  instanceIdSchema,
   instanceInputSchema,
+  secretSchema,
   yamlValueSchema,
 } from "./instance"
 import { commonObjectMetaSchema } from "./meta"
 import { triggerInvocationSchema } from "./trigger"
 
-export type UnitInputReference = z.infer<typeof unitInputReference>
-
-export const unitInputReference = z.object({
+export const unitInputSourceSchema = z.object({
   ...instanceInputSchema.shape,
+})
 
+export type UnitInputSource = z.infer<typeof unitInputSourceSchema>
+
+export const unitInputValueSchema = z.object({
   /**
-   * The resolved inclusion needed to extract the input value.
+   * Inline resolved value passed to the unit.
+   *
+   * The backend is responsible for resolving the correct entity snapshot value
+   * and applying any inclusion transformations.
    */
-  inclusion: entityInclusionSchema.optional(),
+  value: z.unknown(),
+
+  /**
+   * Optional provenance of the value.
+   */
+  source: unitInputSourceSchema.optional(),
 })
 
+export type UnitInputValue = z.infer<typeof unitInputValueSchema>
+
 export const unitConfigSchema = z.object({
   /**
    * The ID of the instance.
    */
   instanceId: z.string(),
 
+  /**
+   * The state ID of the instance.
+   */
+  stateId: z.string(),
+
   /**
    * The record of argument values for the unit.
    */
@@ -36,7 +52,7 @@ export const unitConfigSchema = z.object({
   /**
    * The record of input references for the unit.
    */
-  inputs: z.record(z.string(), unitInputReference.array()),
+  inputs: z.record(z.string(), unitInputValueSchema.array()),
 
   /**
    * The list of triggers that have been invoked for this unit.
@@ -44,14 +60,11 @@ export const unitConfigSchema = z.object({
   invokedTriggers: triggerInvocationSchema.array(),
 
   /**
-   * The list of secret names that exists and provided to the unit.
+   * The record of secret values provided to the unit.
+   *
+   * It is stored in Pulumi stack config as a secret.
    */
-  secretNames: z.string().array(),
-
-  /**
-   * The map of instance ID to state ID in order to resolve instance references.
-   */
-  stateIdMap: z.record(instanceIdSchema, z.string()),
+  secretValues: z.record(z.string(), z.unknown()),
 
   /**
    * The base path for imports.
@@ -87,7 +100,6 @@ export function parseArgumentValue(value: unknown): unknown {
 
 export enum HighstateConfigKey {
   Config = "highstate",
-  Secrets = "highstate.secrets",
 }
 
 export const unitArtifactId = Symbol("unitArtifactId")
@@ -118,6 +130,23 @@ export const fileContentSchema = z.union([
      */
     value: z.string(),
   }),
+  z.object({
+    type: z.literal("embedded-secret"),
+
+    /**
+     * Whether the content is binary or not.
+     *
+     * If true, the `value` will be a base64 encoded string.
+     */
+    isBinary: z.boolean().optional(),
+
+    /**
+     * The content of the file wrapped as a Highstate secret.
+     *
+     * If `isBinary` is true, this will be a base64 encoded string.
+     */
+    value: secretSchema(z.string()),
+  }),
   z.object({
     type: z.literal("artifact"),
     ...unitArtifactSchema.shape,