@platforma-sdk/package-builder-lib 1.1.0

package/src/core/schemas/entrypoints.test.ts

@@ -0,0 +1,171 @@
+import { test, expect } from "vitest";
+import type { z } from "zod/v4";
+import * as entrypoints from "./entrypoints";
+import * as testArtifacts from "./test-artifacts";
+
+const parseJSON = <T extends z.ZodTypeAny>(data: string, schema: T): z.infer<T> => {
+  const parsedData: unknown = JSON.parse(data);
+  return schema.parse(parsedData);
+};
+
+test.for([
+  {
+    epTypes: ["environment"],
+    artType: "environment",
+    variant: "minimal",
+    data: testArtifacts.JavaEnvironmentEntrypoint,
+  },
+  {
+    epTypes: ["environment"],
+    artType: "environment",
+    variant: "with reference",
+    data: testArtifacts.JavaEnvironmentEntrypointWithReference,
+  },
+  { epTypes: ["asset"], artType: "asset", variant: "minimal", data: testArtifacts.AssetEntrypoint },
+  {
+    epTypes: ["binary"],
+    artType: "binary",
+    variant: "minimal",
+    data: testArtifacts.BinaryEntrypoint,
+  },
+  {
+    epTypes: ["binary"],
+    artType: "binary",
+    variant: "with reference",
+    data: testArtifacts.BinaryEntrypointWithReference,
+  },
+  {
+    epTypes: ["binary"],
+    artType: "binary",
+    variant: "limited platforms",
+    data: testArtifacts.LimitedPlatformsBinaryEntrypoint,
+  },
+  {
+    epTypes: ["binary"],
+    artType: "binary",
+    variant: "version override",
+    data: testArtifacts.CustomBinaryEntrypoint,
+  },
+  {
+    epTypes: ["binary"],
+    artType: "binary",
+    variant: "version docker",
+    data: testArtifacts.BinaryEntrypointWithDocker,
+  },
+  { epTypes: ["binary"], artType: "java", variant: "minimal", data: testArtifacts.JavaEntrypoint },
+  {
+    epTypes: ["binary"],
+    artType: "java",
+    variant: "with reference",
+    data: testArtifacts.JavaEntrypointWithReference,
+  },
+  {
+    epTypes: ["binary", "docker"],
+    artType: "java",
+    variant: "with docker",
+    data: testArtifacts.JavaEntrypointWithDocker,
+  },
+  {
+    epTypes: ["binary"],
+    artType: "python",
+    variant: "minimal",
+    data: testArtifacts.PythonEntrypoint,
+  },
+  {
+    epTypes: ["binary"],
+    artType: "python",
+    variant: "with reference",
+    data: testArtifacts.PythonEntrypointWithReference,
+  },
+  {
+    epTypes: ["binary", "docker"],
+    artType: "python",
+    variant: "with docker",
+    data: testArtifacts.PythonEntrypointWithDocker,
+  },
+  {
+    epTypes: ["binary"],
+    artType: "R",
+    variant: "with reference",
+    data: testArtifacts.REntrypointWithReference,
+  },
+  { epTypes: ["binary"], artType: "R", variant: "minimal", data: testArtifacts.REntrypoint },
+  {
+    epTypes: ["binary"],
+    artType: "R",
+    variant: "with reference",
+    data: testArtifacts.REntrypointWithReference,
+  },
+  {
+    epTypes: ["binary", "docker"],
+    artType: "R",
+    variant: "with docker",
+    data: testArtifacts.REntrypointWithDocker,
+  },
+  { epTypes: ["conda"], artType: "conda", variant: "minimal", data: testArtifacts.CondaEntrypoint },
+  {
+    epTypes: ["conda"],
+    artType: "conda",
+    variant: "with reference",
+    data: testArtifacts.CondaEntrypointWithReference,
+  },
+  {
+    epTypes: ["conda", "docker"],
+    artType: "conda",
+    variant: "with docker",
+    data: testArtifacts.CondaEntrypointWithDocker,
+  },
+  {
+    epTypes: ["docker"],
+    artType: "docker",
+    variant: "minimal",
+    data: testArtifacts.DockerEntrypoint,
+  },
+  {
+    epTypes: ["docker"],
+    artType: "docker",
+    variant: "with reference",
+    data: testArtifacts.DockerEntrypointWithReference,
+  },
+])("parse $artType artifact ($variant)", ({ epTypes, artType, data }) => {
+  const ep = parseJSON(data, entrypoints.entrypointSchema);
+  for (const epType of epTypes) {
+    switch (epType) {
+      case "environment":
+        expect(ep.environment).toBeDefined();
+        break;
+      case "asset":
+        expect(ep.asset).toBeDefined();
+        break;
+      case "binary": {
+        expect(ep.binary).toBeDefined();
+        const art = ep.binary!.artifact;
+        if (typeof art !== "string") {
+          expect(art.type).toEqual(artType);
+        }
+        break;
+      }
+      case "conda": {
+        expect(ep.conda).toBeDefined();
+        const art = ep.conda!.artifact;
+        if (typeof art !== "string") {
+          expect(art.registry).toBeDefined();
+          expect(art.spec).toBeDefined();
+        }
+        break;
+      }
+      case "docker": {
+        expect(ep.docker).toBeDefined();
+        const dockerArt = ep.docker!.artifact;
+        if (typeof dockerArt !== "string") {
+          expect(dockerArt.dockerfile).toBeDefined();
+          expect(dockerArt.context).toBeDefined();
+          expect(dockerArt.registry).toBeDefined();
+        }
+        break;
+      }
+      default:
+        throw new Error("epType not covered by test logic");
+    }
+  }
+});

package/src/core/schemas/entrypoints.ts

@@ -0,0 +1,150 @@
+import { z } from "zod/v4";
+import * as artifacts from "./artifacts";
+import * as util from "../util";
+
+const envVarsSchema = z.array(
+  z
+    .string()
+    .regex(
+      /=/,
+      "full environment variable specification is required: <var-name>=<var-value>, e.g.: IS_CI=yes",
+    ),
+);
+
+export const EnyrypointReferencePattern =
+  /^(?<fullName>(?:(?<scope>@[a-z0-9-.]+)\/)?(?<name>[a-z0-9-.]+))\/(?<path>.*)$/;
+
+export const referenceSchema = z
+  .string()
+  .regex(
+    EnyrypointReferencePattern,
+    "entrypoint reference must contain full package name and path to the file inside",
+  );
+
+const orRef = <T extends z.ZodTypeAny>(schema: T) =>
+  z.union([
+    z
+      .string("not a reference to artifact")
+      .describe('reference to artifact in "artifacts" section'),
+    schema,
+  ]);
+
+// Common options for all software packages: everything that can be run on backend side.
+export const softwareOptionsSchema = z.strictObject({
+  cmd: z
+    .array(z.string("command artument must be a string"))
+    .min(1, { error: "at least one argument is required" })
+    .refine((cmd) => cmd[0].trim() != "", { error: "first cmd argument must be non-empty string" })
+    .describe(
+      "command to run for this entrypoint. This command will be appended by <args> set inside workflow",
+    ),
+  envVars: envVarsSchema
+    .optional()
+    .describe("list of environment variables to be set for this entrypoint"),
+});
+export type softwareOptionsType = z.infer<typeof softwareOptionsSchema>;
+
+export const environmentOptionsSchema = z.strictObject({
+  artifact: orRef(artifacts.environmentSchema.omit({ type: true })),
+  envVars: envVarsSchema
+    .optional()
+    .describe(
+      "list of environment variables to be set for any command inside this run environment",
+    ),
+});
+
+// Full schema of single entrypoint in block-software.entrypoints
+export const entrypointSchema = z
+  .strictObject({
+    reference: referenceSchema.optional(),
+    asset: orRef(artifacts.assetSchema.omit({ type: true })).optional(),
+    environment: environmentOptionsSchema.optional(),
+
+    binary: z
+      .union([
+        softwareOptionsSchema.extend({ artifact: orRef(artifacts.binarySchema) }),
+        softwareOptionsSchema.extend({ artifact: orRef(artifacts.javaSchema) }),
+        softwareOptionsSchema.extend({ artifact: orRef(artifacts.pythonSchema) }),
+        softwareOptionsSchema.extend({ artifact: orRef(artifacts.rSchema) }),
+      ])
+      .optional(), // TODO: reduce nesting: put java, python and r to the level of binary, like conda.
+
+    conda: softwareOptionsSchema
+      .extend({ artifact: orRef(artifacts.condaSchema.omit({ type: true })) })
+      .optional(),
+    docker: softwareOptionsSchema
+      .extend({ artifact: orRef(artifacts.dockerSchema.omit({ type: true })) })
+      .optional(),
+  })
+  .refine(
+    (data) => {
+      const n =
+        util.toInt(data.reference) +
+        util.toInt(data.asset && !data.docker) + // no docker for assets
+        util.toInt(data.binary || (data.binary && data.docker)) + // allow both docker and binary to be set in single entrypoint
+        util.toInt(data.conda || (data.conda && data.docker)) + // allow both docker and conda to be set in single entrypoint
+        util.toInt(data.environment && !data.docker); // no docker for environments
+
+      if (n === 0) {
+        return Boolean(data.docker); // allow separate docker entrypoints (without binary/conda/...)
+      }
+
+      return n === 1;
+    },
+    {
+      message:
+        "entrypoint cannot point to several packages at once: choose 'reference', 'asset', 'binary', 'environment' or 'docker'",
+      path: ["reference | asset | binary | environment | docker"],
+    },
+  );
+export type entrypointType = z.infer<typeof entrypointSchema>;
+
+// Full block-software.entrypoints list schema
+export const entrypointListSchema = z.record(
+  z
+    .string()
+    .regex(/[-_a-z0-9.]/)
+    .describe(
+      "name of entrypoint descriptor, client should import to use this entrypoint (assets.importSoftware)",
+    ),
+  entrypointSchema,
+);
+export type entrypointListType = z.infer<typeof entrypointListSchema>;
+
+export interface ReferenceEntrypoint {
+  type: "reference";
+  name: string;
+  reference: string;
+}
+
+export interface AssetEntrypoint {
+  type: "asset";
+  name: string;
+  artifact: artifacts.withId<artifacts.assetType>;
+}
+
+export interface SoftwareEntrypoint {
+  type: "software";
+  name: string;
+  artifact: artifacts.withId<
+    | artifacts.binaryType
+    | artifacts.condaType
+    | artifacts.javaType
+    | artifacts.pythonType
+    | artifacts.rType
+    | artifacts.dockerType
+  >;
+  cmd: string[];
+  env: string[];
+}
+
+export interface EnvironmentEntrypoint {
+  type: "environment";
+  name: string;
+  artifact: artifacts.withId<artifacts.environmentType>;
+  env: string[];
+}
+
+export type PackageEntrypoint = AssetEntrypoint | SoftwareEntrypoint | EnvironmentEntrypoint;
+export type Entrypoint = ReferenceEntrypoint | PackageEntrypoint;
+export type EntrypointType = Extract<Entrypoint, { type: string }>["type"];

package/src/core/schemas/sw-json.ts

@@ -0,0 +1,216 @@
+import { z } from "zod/v4";
+import * as defaults from "../../defaults";
+import * as artifacts from "./artifacts";
+import * as util from "../util";
+
+export const remoteLocationSchema = z.object({
+  registry: z.string().describe("name of the registry to use for package download"),
+  package: z
+    .string()
+    .describe("full package path in registry, e.g. 'common/jdk/21.0.2.13.1-{os}-{arch}.tgz"),
+});
+
+export const assetSchema = z.object({
+  ...remoteLocationSchema.shape,
+  url: z.string().describe("asset download URL"),
+});
+export type assetInfo = z.infer<typeof assetSchema>;
+
+export const dockerSchema = z.object({
+  tag: z.string().describe("full image tag to pull on backend side to execute this software"),
+  entrypoint: z.array(z.string()).describe("override image's entrypoint"),
+  cmd: z.array(z.string()).describe("command to be run in the container"),
+
+  pkg: z
+    .string()
+    .default(defaults.DOCKER_PLACEHOLDER_PKG)
+    .describe(
+      'what to substitute in place of "{pkg}" variable in "cmd" (for artifacts with docker autogeneration)',
+    ),
+});
+export type dockerInfo = z.infer<typeof dockerSchema>;
+
+export const runEnvironmentSchema = z.object({
+  type: z.enum(artifacts.runEnvironmentTypes),
+  ...remoteLocationSchema.shape,
+
+  ["r-version"]: z.string().optional(),
+  ["python-version"]: z.string().optional(),
+  ["java-version"]: z.string().optional(),
+
+  envVars: z
+    .array(
+      z
+        .string()
+        .regex(
+          /=/,
+          "environment variable should be specified in format: <var-name>=<var-value>, i.e.: MY_ENV=value",
+        ),
+    )
+    .optional(),
+
+  binDir: z.string(),
+});
+export type runEnvInfo = z.infer<typeof runEnvironmentSchema>;
+
+export const runDependencyJavaSchema = runEnvironmentSchema.extend({
+  type: z.literal("java"),
+  name: z
+    .string()
+    .describe("name used to import this package as software dependency of tengo script"),
+});
+export type runEnvDependencyJava = z.infer<typeof runDependencyJavaSchema>;
+
+export const runDependencyPythonSchema = runEnvironmentSchema.extend({
+  type: z.literal("python"),
+  ["python-version"]: z.string(),
+  name: z
+    .string()
+    .describe("name used to import this package as software dependency of tengo script"),
+});
+export type runEnvDependencyPython = z.infer<typeof runDependencyPythonSchema>;
+
+export const runDependencyRSchema = runEnvironmentSchema.extend({
+  type: z.literal("R"),
+  ["r-version"]: z.string(),
+  name: z
+    .string()
+    .describe("name used to import this package as software dependency of tengo script"),
+});
+export type runEnvDependencyR = z.infer<typeof runDependencyRSchema>;
+
+export type runEnvDependency = runEnvDependencyJava | runEnvDependencyPython | runEnvDependencyR;
+
+export const commonPackageSettingsSchema = z.object({
+  cmd: z.array(z.string()).min(1).describe("run given command, appended by args from workflow"),
+
+  envVars: z
+    .array(
+      z
+        .string()
+        .regex(
+          /=/,
+          "full environment variable specification is required: <var-name>=<var-value>, e.g.: IS_CI=yes",
+        ),
+    )
+    .optional(),
+});
+
+export const binaryPackageSchema = z.object({
+  type: z.literal("binary"),
+  ...commonPackageSettingsSchema.shape,
+
+  pkg: z
+    .string()
+    .optional()
+    .describe("location of all package contents in Docker container (default: /app)"),
+});
+
+export const javaPackageSettingsSchema = z.object({
+  type: z.literal("java"),
+
+  ...commonPackageSettingsSchema.shape,
+  runEnv: runDependencyJavaSchema,
+});
+
+export const pythonPackageSettingsSchema = z.object({
+  type: z.literal("python"),
+
+  ...commonPackageSettingsSchema.shape,
+  runEnv: runDependencyPythonSchema,
+
+  toolset: z.string(),
+  dependencies: z
+    .record(z.string(), z.string())
+    .describe(
+      "paths of files that describe dependencies for given toolset: say, requirements.txt for 'pip'",
+    ),
+});
+
+export const rPackageSettingsSchema = z.object({
+  type: z.literal("R"),
+
+  ...commonPackageSettingsSchema.shape,
+  runEnv: runDependencyRSchema,
+
+  toolset: z.string(),
+  dependencies: z
+    .record(z.string(), z.string())
+    .describe(
+      "paths of files that describe dependencies for given toolset: say, requirements.txt for 'pip'",
+    ),
+});
+
+export const condaPackageSchema = z.object({
+  type: z.literal("conda"),
+  ...commonPackageSettingsSchema.shape,
+
+  ["micromamba-version"]: z
+    .string()
+    .describe("version of micromamba to be used to operate with conda environments"),
+  ["conda-root-dir"]: z
+    .string()
+    .default(defaults.CONDA_DATA_LOCATION)
+    .describe("root directory of conda environment inside package root"),
+
+  spec: z
+    .string()
+    .describe("location of spec.yaml describing conda environment, relative to package root."),
+});
+
+export const remoteSoftwareSchema = z.union([
+  remoteLocationSchema.extend(binaryPackageSchema.shape),
+  remoteLocationSchema.extend(javaPackageSettingsSchema.shape),
+  remoteLocationSchema.extend(pythonPackageSettingsSchema.shape),
+  remoteLocationSchema.extend(rPackageSettingsSchema.shape),
+  remoteLocationSchema.extend(condaPackageSchema.shape),
+]);
+export type remoteSoftwareType = z.infer<typeof remoteSoftwareSchema>;
+
+export const localLocationSchema = z.object({
+  hash: z
+    .string()
+    .describe(
+      "hash of software directory. Makes deduplication to work properly when you actively develop software",
+    ),
+  path: z.string().describe("absolute path to root directory of software on local host"),
+});
+
+export const localSoftwareSchema = z.discriminatedUnion("type", [
+  localLocationSchema.extend(binaryPackageSchema.shape),
+  localLocationSchema.extend(javaPackageSettingsSchema.shape),
+  localLocationSchema.extend(pythonPackageSettingsSchema.shape),
+  localLocationSchema.extend(rPackageSettingsSchema.shape),
+  localLocationSchema.extend(condaPackageSchema.shape),
+  // Docker can be used 'as usual' without any special 'local' section magic
+]);
+export type localSoftwareType = z.infer<typeof localSoftwareSchema>;
+
+// Full .sw.json file schema
+export const swJsonSchema = z
+  .object({
+    isDev: z.boolean().optional(),
+
+    asset: assetSchema.optional(),
+    binary: remoteSoftwareSchema.optional(),
+    docker: dockerSchema.optional(),
+    runEnv: runEnvironmentSchema.optional(),
+    local: localSoftwareSchema.optional(),
+  })
+  .refine(
+    (data) =>
+      util.toInt(data.runEnv) +
+        util.toInt(data.binary || data.docker) + // allow both docker and binary to be set in single entrypoint
+        util.toInt(data.asset) +
+        util.toInt(data.local) ==
+      1,
+    {
+      message:
+        "entrypoint cannot point to several packages at once: choose 'environment', 'binary', 'asset', 'conda' or 'local'",
+      path: ["environment | binary | asset | conda | local"],
+    },
+  );
+
+export type swJsonType = z.infer<typeof swJsonSchema> & {
+  id: util.artifactID;
+};