@highstate/library 0.9.15 → 0.9.16

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@highstate/library",
-  "version": "0.9.15",
+  "version": "0.9.16",
   "type": "module",
+  "highstate": {
+    "type": "library"
+  },
   "files": [
     "dist",
     "src"
@@ -16,15 +19,15 @@
     "access": "public"
   },
   "scripts": {
-    "build": "highstate build --library"
+    "build": "highstate build"
   },
   "dependencies": {
-    "@highstate/contract": "^0.9.15",
+    "@highstate/contract": "^0.9.16",
     "@sinclair/typebox": "^0.34.11",
     "remeda": "^2.21.0"
   },
   "devDependencies": {
-    "@highstate/cli": "^0.9.15"
+    "@highstate/cli": "^0.9.16"
   },
-  "gitHead": "f61b9905d4cd50511b03331411f42595403ebc06"
+  "gitHead": "458d6f1f9f6d4aec0ba75a2b2c4c01408cb9c8df"
 }

package/src/abbreviations.ts

@@ -0,0 +1,35 @@
+import { registerKnownAbbreviations } from "@highstate/contract"
+
+registerKnownAbbreviations([
+  "ID",
+  "URL",
+  "IP",
+  "IPs",
+  "IPv4",
+  "IPv6",
+  "DNS",
+  "FQDN",
+  "SSH",
+  "WireGuard",
+  "API",
+  "k8s",
+  "TLS",
+  "HTTP",
+  "HTTPS",
+  "TCP",
+  "UDP",
+  "CIDR",
+  "CPU",
+  "RAM",
+  "GPU",
+  "SSD",
+  "HDD",
+  "VM",
+  "CNI",
+  "CSI",
+  "MariaDB",
+  "PostgreSQL",
+  "MongoDB",
+])
+
+export const noop = () => {}

package/src/apps/dns.ts

@@ -102,8 +102,6 @@ export const recordSet = defineUnit({
 export const sharedArgs = {
   /**
    * The FQDN to register the cluster nodes with.
-   *
-   * @schema
    */
   fqdn: Type.Optional(Type.String()),
 }

package/src/apps/shared.ts

@@ -9,7 +9,7 @@ import {
   persistentVolumeClaimEntity,
   serviceEntity,
 } from "../k8s"
-import { repoEntity } from "../restic"
+import { repositoryEntity } from "../restic"
 import { providerEntity } from "../dns"
 import { l4EndpointEntity } from "../network"
 
@@ -58,7 +58,7 @@ const eagerExtraInputDefinitions = {
     entity: accessPointEntity,
   },
   resticRepo: {
-    entity: repoEntity,
+    entity: repositoryEntity,
     required: false,
   },
   dnsProviders: {

package/src/common.ts

@@ -90,8 +90,6 @@ export const serverPatch = defineUnit({
      * The entry may represent real node endpoint or virtual endpoint (like a load balancer).
      *
      * The same server may also be represented by multiple entries (e.g. a node with private and public IP).
-     *
-     * @schema
      */
     endpoints: Type.Default(Type.Array(Type.String()), []),
 
@@ -197,57 +195,6 @@ export const script = defineUnit({
   },
 })
 
-export const fileMetaEntity = defineEntity({
-  type: "common.file-meta",
-
-  schema: Type.Object({
-    name: Type.String(),
-    size: Type.Number(),
-    mode: Type.Number(),
-    isBinary: Type.Optional(Type.Boolean()),
-  }),
-
-  meta: {
-    color: "#FF5722",
-    description: "Metadata for a file.",
-  },
-})
-
-export const fileContentEntity = defineEntity({
-  type: "common.file-content",
-
-  schema: Type.Union([
-    Type.Object({
-      type: Type.Literal("inline"),
-      content: Type.String(),
-    }),
-    Type.Object({
-      type: Type.Literal("remote"),
-      url: Type.String(),
-    }),
-  ]),
-
-  meta: {
-    color: "#FF5722",
-    description: "The content of a file.",
-  },
-})
-
-export const fileEntity = defineEntity({
-  type: "common.file",
-
-  schema: Type.Object({
-    meta: fileMetaEntity.schema,
-    content: fileContentEntity.schema,
-  }),
-
-  meta: {
-    color: "#FF5722",
-  },
-})
-
 export type Server = Static<typeof serverEntity.schema>
 
-export type File = Static<typeof fileEntity.schema>
-export type FileMeta = Static<typeof fileMetaEntity.schema>
-export type FileContent = Static<typeof fileContentEntity.schema>
+export * from "./files"

package/src/distributions/index.ts

@@ -0,0 +1 @@
+export * from "./ubuntu"

package/src/distributions/ubuntu.ts

@@ -0,0 +1,32 @@
+import { defineUnit, Type } from "@highstate/contract"
+import { fileEntity } from "../files"
+
+export const ubuntuVersionSchema = Type.StringEnum(["22.04", "24.04", "24.10", "25.04", "25.10"])
+export const ubuntuArchitectureSchema = Type.StringEnum(["amd64", "arm64"])
+
+export const ubuntu = defineUnit({
+  type: "distributions.ubuntu",
+
+  args: {
+    version: Type.Default(ubuntuVersionSchema, "24.04"),
+    architecture: Type.Default(ubuntuArchitectureSchema, "amd64"),
+  },
+
+  outputs: {
+    image: fileEntity,
+    cloudConfig: fileEntity,
+  },
+
+  meta: {
+    displayName: "Ubuntu",
+    description: "Ubuntu distribution with image and cloud-config.",
+    primaryIcon: "mdi:ubuntu",
+    primaryIconColor: "#E95420",
+    category: "Distributions",
+  },
+
+  source: {
+    package: "@highstate/distributions",
+    path: "ubuntu",
+  },
+})

package/src/dns.ts

@@ -25,8 +25,6 @@ export function createArgs<TPrefix extends string = "">(prefix?: TPrefix) {
      * Will be inserted at the beginning of the resulting endpoint list.
      *
      * Will throw an error if no matching provider is found.
-     *
-     * @schema
      */
     fqdn: Type.Optional(Type.String()),
 
@@ -46,8 +44,6 @@ export function createArgs<TPrefix extends string = "">(prefix?: TPrefix) {
      * - If any public endpoints exist, all public endpoints are selected;
      * - Otherwise, if any external endpoints exist, all external endpoints are selected;
      * - If neither exist, all internal endpoints are selected.
-     *
-     * @schema
      */
     endpointFilter: Type.Default(endpointFilterSchema, []),
 
@@ -58,8 +54,6 @@ export function createArgs<TPrefix extends string = "">(prefix?: TPrefix) {
      * - `replace`: Replace the existing endpoints with the FQDN. It will ensure that the only the FQDN is used.
      *
      * The default is `prepend`.
-     *
-     * @schema
      */
     patchMode: Type.Default(arrayPatchModeSchema, "prepend"),
   })
@@ -70,8 +64,6 @@ export const inputs = {
    * The DNS providers to use to create the DNS records.
    *
    * If multiple providers match the domain, all of them will be used and multiple DNS records will be created.
-   *
-   * @schema
    */
   dnsProviders: {
     entity: providerEntity,

package/src/files.ts

@@ -0,0 +1,146 @@
+import type { Static } from "@sinclair/typebox"
+import {
+  defineEntity,
+  defineUnit,
+  HighstateSignature,
+  Type,
+  fileContentSchema as baseFileContentSchema,
+  fileMetaSchema as baseFileMetaSchema,
+  unitArtifactSchema,
+} from "@highstate/contract"
+import { l7EndpointEntity } from "./network"
+
+export const checksumAlgorithmSchema = Type.StringEnum([
+  "md5",
+  "sha1",
+  "sha256",
+  "sha384",
+  "sha512",
+])
+
+export const checksumSchema = Type.Object({
+  algorithm: checksumAlgorithmSchema,
+  value: Type.String(),
+})
+
+export const fileContentSchema = Type.Union([
+  baseFileContentSchema,
+  Type.Object({
+    type: Type.Literal("local"),
+    path: Type.String(),
+  }),
+  Type.Object({
+    type: Type.Literal("remote"),
+    endpoint: l7EndpointEntity.schema,
+    checksum: Type.Optional(checksumSchema),
+  }),
+])
+
+export const fileEntity = defineEntity({
+  type: "common.file",
+
+  schema: Type.Object({
+    meta: baseFileMetaSchema,
+    content: fileContentSchema,
+  }),
+
+  meta: {
+    color: "#FF5722",
+  },
+})
+
+export const folderMetaSchema = Type.Object({
+  name: Type.String(),
+  mode: Type.Optional(Type.Number()),
+})
+
+export const folderContentSchema = Type.Recursive(
+  TSelf => {
+    return Type.Union([
+      Type.Object({
+        type: Type.Literal("embedded"),
+        files: Type.Array(fileEntity.schema),
+        folders: Type.Array(
+          Type.Object({
+            meta: folderMetaSchema,
+            content: TSelf,
+          }),
+        ),
+      }),
+      Type.Object({
+        type: Type.Literal("artifact"),
+        [HighstateSignature.Artifact]: unitArtifactSchema,
+      }),
+      Type.Object({
+        type: Type.Literal("local"),
+        path: Type.String(),
+      }),
+      Type.Object({
+        type: Type.Literal("remote"),
+        endpoint: l7EndpointEntity.schema,
+      }),
+    ])
+  },
+  { $id: "common.folder.content" },
+)
+
+export const folderEntity = defineEntity({
+  type: "common.folder",
+
+  schema: Type.Object({
+    meta: folderMetaSchema,
+    content: folderContentSchema,
+  }),
+
+  meta: {
+    color: "#FF9800",
+  },
+})
+
+export const remoteFile = defineUnit({
+  type: "common.remote-file",
+
+  args: {
+    /**
+     * The URL of the remote file.
+     */
+    url: Type.Optional(Type.String()),
+  },
+
+  inputs: {
+    /**
+     * The L7 endpoint of the remote file.
+     */
+    endpoint: {
+      entity: l7EndpointEntity,
+      required: false,
+    },
+  },
+
+  outputs: {
+    file: fileEntity,
+  },
+
+  meta: {
+    displayName: "Remote File",
+    description: "References a file from a remote URL.",
+    primaryIcon: "mdi:file-download",
+    category: "Files",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/remote-file",
+  },
+})
+
+export type File = Static<typeof fileEntity.schema>
+export type FileMeta = Static<typeof baseFileMetaSchema>
+export type FileContent = Static<typeof fileContentSchema>
+
+export type Folder = Static<typeof folderEntity.schema>
+export type FolderMeta = Static<typeof folderMetaSchema>
+export type FolderContent = Static<typeof folderContentSchema>
+
+export type Checksum = Static<typeof checksumSchema>
+export type ChecksumAlgorithm = Static<typeof checksumAlgorithmSchema>

package/src/git.ts

@@ -0,0 +1,58 @@
+import { defineUnit, Type } from "@highstate/contract"
+import { l7EndpointEntity } from "./network"
+import { folderEntity } from "./files"
+
+export const remoteRepository = defineUnit({
+  type: "git.remote-repository",
+
+  args: {
+    /**
+     * The URL of the remote repository.
+     */
+    url: Type.Optional(Type.String()),
+
+    /**
+     * The ref of the remote repository to checkout.
+     *
+     * If not specified, the default branch will be used.
+     */
+    ref: Type.Optional(Type.String()),
+
+    /**
+     * Whether to include the .git directory in the packed artifact.
+     *
+     * Do not enable this unless you need the full git history.
+     */
+    includeGit: Type.Default(Type.Boolean(), false),
+  },
+
+  inputs: {
+    /**
+     * The L7 endpoint of the remote repository.
+     */
+    endpoint: {
+      entity: l7EndpointEntity,
+      required: false,
+    },
+  },
+
+  outputs: {
+    /**
+     * The folder containing the repository content.
+     */
+    folder: folderEntity,
+  },
+
+  meta: {
+    displayName: "Git Remote Repository",
+    description: "References a remote Git repository.",
+    primaryIcon: "simple-icons:git",
+    primaryIconColor: "#f1502f",
+    category: "Git",
+  },
+
+  source: {
+    package: "@highstate/git",
+    path: "remote-repository",
+  },
+})

package/src/index.ts

@@ -1,3 +1,6 @@
+import { noop } from "./abbreviations"
+noop()
+
 export * as common from "./common"
 export * as proxmox from "./proxmox"
 export * as ssh from "./ssh"
@@ -14,5 +17,7 @@ export * as timeweb from "./timeweb"
 export * as nixos from "./nixos"
 export * as sops from "./sops"
 export * as obfuscators from "./obfuscators"
+export * as distributions from "./distributions"
 export * as network from "./network"
+export * as git from "./git"
 export * from "./utils"

package/src/k3s.ts

@@ -28,8 +28,6 @@ export const cluster = defineUnit({
   args: {
     /**
      * The components to disable in the K3S cluster.
-     *
-     * @schema
      */
     disabledComponents: Type.Default(Type.Array(componentSchema), []),
 
@@ -38,8 +36,6 @@ export const cluster = defineUnit({
      *
      * Setting this to "none" will disable default Flannel CNI, but will not disable network policy controller and kube-proxy.
      * If needed, you can disable them using `disabledComponents` argument.
-     *
-     * @schema
      */
     cni: Type.Default(cniSchema, "flannel"),
 
@@ -47,8 +43,6 @@ export const cluster = defineUnit({
      * The K3S configuration to pass to each server or agent in the cluster.
      *
      * See: https://docs.k3s.io/installation/configuration
-     *
-     * @schema
      */
     config: Type.Optional(Type.Record(Type.String(), Type.Any())),
 
@@ -56,8 +50,6 @@ export const cluster = defineUnit({
      * The configuration of the registries to use for the K3S cluster.
      *
      * See: https://docs.k3s.io/installation/private-registry
-     *
-     * @schema
      */
     registries: Type.Optional(Type.Record(Type.String(), Type.Any())),
   },

package/src/k8s.ts

@@ -30,8 +30,6 @@ export const clusterQuirksSchema = Type.Object({
    * The IP and port of the kube-apiserver available from the cluster.
    *
    * Will be used to create fallback network policy in CNIs which does not support allowing access to the kube-apiserver.
-   *
-   * @schema
    */
   fallbackKubeApiAccess: Type.Optional(fallbackKubeApiAccessSchema),
 
@@ -41,8 +39,6 @@ export const clusterQuirksSchema = Type.Object({
    * If not provided, the default policy is `host` which assumes just mounting /dev/net/tun from the host.
    *
    * For some runtimes, like Talos's one, the /dev/net/tun device is not available in the host, so the plugin policy should be used.
-   *
-   * @schema
    */
   tunDevicePolicy: Type.Optional(tunDevicePolicySchema),
 
@@ -50,8 +46,6 @@ export const clusterQuirksSchema = Type.Object({
    * The service type to use for external services.
    *
    * If not provided, the default service type is `NodePort` since `LoadBalancer` may not be available.
-   *
-   * @schema
    */
   externalServiceType: Type.Optional(externalServiceTypeSchema),
 })
@@ -61,15 +55,11 @@ export const clusterInfoProperties = {
    * The unique identifier of the cluster.
    *
    * Should be defined as a UUID of the `kube-system` namespace which is always present in the cluster.
-   *
-   * @schema
    */
   id: Type.String(),
 
   /**
    * The name of the cluster.
-   *
-   * @schema
    */
   name: Type.String(),
 
@@ -79,8 +69,6 @@ export const clusterInfoProperties = {
    * Supported values are:
    * - `cilium`
    * - `other`
-   *
-   * @schema
    */
   cni: cniSchema,
 
@@ -90,8 +78,6 @@ export const clusterInfoProperties = {
    * The entry may represent real node endpoint or virtual endpoint (like a load balancer).
    *
    * The same node may also be represented by multiple entries (e.g. a node with private and public IP).
-   *
-   * @schema
    */
   endpoints: Type.Array(l3EndpointEntity.schema),
 
@@ -106,22 +92,16 @@ export const clusterInfoProperties = {
 
   /**
    * The external IPs of the cluster nodes allowed to be used for external access.
-   *
-   * @schema
    */
   externalIps: Type.Array(Type.String()),
 
   /**
    * The extra quirks of the cluster to improve compatibility.
-   *
-   * @schema
    */
   quirks: Type.Optional(clusterQuirksSchema),
 
   /**
    * The extra metadata to attach to the cluster.
-   *
-   * @schema
    */
   metadata: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
 } as const
@@ -176,8 +156,6 @@ export const scheduleOnMastersPolicyArgs = {
    * - `always`: always schedule workloads on master nodes regardless of the number of workers;
    * - `when-no-workers`: schedule workloads on master nodes only if there are no workers (default);
    * - `never`: never schedule workloads on master nodes.
-   *
-   * @schema
    */
   scheduleOnMastersPolicy: Type.Default(scheduleOnMastersPolicySchema, "when-no-workers"),
 }
@@ -214,8 +192,6 @@ export const existingCluster = defineUnit({
      * The list of external IPs of the cluster nodes allowed to be used for external access.
      *
      * If not provided, will be automatically detected by querying the cluster nodes.
-     *
-     * @schema
      */
     externalIps: Type.Optional(Type.Array(Type.String())),
 
@@ -225,15 +201,11 @@ export const existingCluster = defineUnit({
      * - `always`: always use internal IPs as external IPs;
      * - `public`: use internal IPs as external IPs only if they are (theoretically) routable from the public internet **(default)**;
      * - `never`: never use internal IPs as external IPs.
-     *
-     * @schema
      */
     internalIpsPolicy: Type.Default(internalIpsPolicySchema, "public"),
 
     /**
      * The extra quirks of the cluster to improve compatibility.
-     *
-     * @schema
      */
     quirks: Type.Optional(clusterQuirksSchema),
   },
@@ -243,8 +215,6 @@ export const existingCluster = defineUnit({
      * The kubeconfig of the cluster to use for connecting to the cluster.
      *
      * Will be available for all components using `cluster` output of this unit.
-     *
-     * @schema
      */
     kubeconfig: Type.Record(Type.String(), Type.Any()),
   },
@@ -274,8 +244,6 @@ export const clusterPatch = defineUnit({
      * The entry may represent real node endpoint or virtual endpoint (like a load balancer).
      *
      * The same node may also be represented by multiple entries (e.g. a node with private and public IP).
-     *
-     * @schema
      */
     apiEndpoints: Type.Default(Type.Array(Type.String()), []),
 
@@ -293,8 +261,6 @@ export const clusterPatch = defineUnit({
      * The entry may represent real node endpoint or virtual endpoint (like a load balancer).
      *
      * The same node may also be represented by multiple entries (e.g. a node with private and public IP).
-     *
-     * @schema
      */
     endpoints: Type.Default(Type.Array(Type.String()), []),
 
@@ -471,8 +437,6 @@ export const dns01TlsIssuer = defineUnit({
      * The top-level domains to filter the DNS01 challenge for.
      *
      * If not provided, will use all domains passed to the DNS providers.
-     *
-     * @schema
      */
     domains: Type.Optional(Type.Array(Type.String())),
   },
@@ -630,6 +594,24 @@ export const cilium = defineUnit({
   },
 })
 
+export const monitorWorkerResourceGroupSchema = Type.Object({
+  type: Type.StringEnum(["deployment", "statefulset", "pod", "service"]),
+  namespace: Type.String(),
+  names: Type.Optional(Type.Array(Type.String())),
+})
+
+export const monitorWorkerParamsSchema = Type.Object({
+  /**
+   * The ID of the secret containing the kubeconfig of the cluster.
+   */
+  kubeconfigSecretId: Type.String(),
+
+  /**
+   * The resources to monitor in the cluster.
+   */
+  resourceGroups: Type.Array(monitorWorkerResourceGroupSchema),
+})
+
 export type CNI = Static<typeof cniSchema>
 export type Cluster = Static<typeof clusterEntity.schema>
 
@@ -651,3 +633,6 @@ export type StatefulSet = Static<typeof statefulSetEntity.schema>
 
 export type Interface = Static<typeof interfaceEntity.schema>
 export type InternalIpsPolicy = Static<typeof internalIpsPolicySchema>
+
+export type MonitorWorkerParams = Static<typeof monitorWorkerParamsSchema>
+export type MonitorWorkerResourceGroup = Static<typeof monitorWorkerResourceGroupSchema>

package/src/mullvad.ts

@@ -10,8 +10,6 @@ export const peer = defineUnit({
 
     /**
      * Whether to include Mullvad DNS servers in the peer configuration.
-     *
-     * @schema
      */
     includeDns: Type.Default(Type.Boolean(), true),
   },
@@ -21,8 +19,6 @@ export const peer = defineUnit({
      * The network to use for the WireGuard peer.
      *
      * If not provided, the peer will use default network configuration.
-     *
-     * @schema
      */
     network: {
       entity: networkEntity,