@platforma-sdk/package-builder-lib 1.1.0

package/src/core/paths.ts

@@ -0,0 +1,16 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export function path(...p: string[]): string {
+  return resolve(__dirname, "..", "..", ...p);
+}
+
+export function assets(...p: string[]): string {
+  return path("assets", ...p);
+}
+
+export function dist(...p: string[]): string {
+  return path("dist", ...p);
+}

package/src/core/resolver.ts

@@ -0,0 +1,195 @@
+import path from "node:path";
+import fs from "node:fs";
+import type winston from "winston";
+
+import * as swJson from "./schemas/sw-json";
+import type * as artifacts from "./schemas/artifacts";
+import type * as entrypoint from "./schemas/entrypoints";
+import * as util from "./util";
+
+export const compiledSoftwareSuffix = ".sw.json";
+export const compiledAssetSuffix = ".as.json";
+
+export function descriptorFilePath(
+  packageRoot: string,
+  entrypointType: Extract<entrypoint.EntrypointType, "software" | "asset">,
+  entrypointName?: string,
+): string {
+  const typeSuffix = entrypointType === "software" ? compiledSoftwareSuffix : compiledAssetSuffix;
+
+  if (!entrypointName) {
+    return path.resolve(packageRoot, "dist", "tengo", entrypointType);
+  }
+
+  return path.resolve(
+    packageRoot,
+    "dist",
+    "tengo",
+    entrypointType,
+    `${entrypointName}${typeSuffix}`,
+  );
+}
+
+/**
+ * Read and parse 'sw.json' descriptor file from given path.
+ *
+ * @param packageRoot: string - root directory of the package that contains software descriptor
+ * @param packageName: string - name of the package from <packageRoot>/package.json
+ * @param entrypointName: string - name of entrypoint with software descriptor
+ *
+ * @returns swJson.entrypoint - parsed descriptor with meta information of where it came from
+ */
+export function readSwJsonFile(
+  packageRoot: string,
+  packageName: string,
+  entrypointName: string,
+): swJson.swJsonType {
+  const filePath = descriptorFilePath(packageRoot, "software", entrypointName);
+  return readDescriptorFile(packageName, entrypointName, filePath);
+}
+
+/**
+ * Read 'sw.json' or 'as.json' descriptor file from given path and provide it along with metadata of where it came from
+ *
+ * @param packageNameForDescriptor: string - name of the package that contains this descriptor
+ * @param entrypointForDescriptor: string - name of entrypoint that contains this descriptor inside given package
+ * @param descriptorFilePath: string - path to the descriptor file
+ * @returns swJson.entrypoint - parsed descriptor with meta information of where it came from
+ */
+export function readDescriptorFile(
+  packageNameForDescriptor: string,
+  entrypointForDescriptor: string,
+  descriptorFilePath: string,
+): swJson.swJsonType {
+  if (!fs.existsSync(descriptorFilePath)) {
+    throw util.CLIError(
+      `entrypoint '${entrypointForDescriptor}' not found in '${descriptorFilePath}'`,
+    );
+  }
+
+  const swJsonContent = fs.readFileSync(descriptorFilePath);
+  const result = swJson.swJsonSchema.safeParse(JSON.parse(swJsonContent.toString()));
+
+  if (!result.success) {
+    throw util.CLIError(util.formatZodIssues(result.error.issues));
+  }
+
+  return {
+    id: {
+      package: packageNameForDescriptor,
+      name: entrypointForDescriptor,
+    },
+    ...result.data,
+  };
+}
+
+/**
+ * Resolve package dependency and read software descriptor from it.
+ *
+ * @param logger: winston.Logger - logger instance
+ * @param currentPackageRoot: string - root directory of the current package
+ * @param dependencyPackageName: string - name of the dependency to search
+ * @param dependencyEntrypointName: string - name of the entrypooint inside dependency package
+ *
+ * @returns swJson.entrypoint - parsed descriptor with meta information of where it came from
+ */
+export function resolveDependency(
+  logger: winston.Logger,
+  currentPackageRoot: string,
+  dependencyPackageName: string,
+  dependencyEntrypointName: string,
+): swJson.swJsonType {
+  const dependencyPath = util.findInstalledModule(
+    logger,
+    dependencyPackageName,
+    currentPackageRoot,
+  );
+  return readSwJsonFile(dependencyPath, dependencyPackageName, dependencyEntrypointName);
+}
+
+export function resolveRunEnvironment(
+  logger: winston.Logger,
+  packageRoot: string,
+  packageName: string,
+  envName: string,
+  requireType: "java",
+): swJson.runEnvDependencyJava;
+export function resolveRunEnvironment(
+  logger: winston.Logger,
+  packageRoot: string,
+  packageName: string,
+  envName: string,
+  requireType: "python",
+): swJson.runEnvDependencyPython;
+export function resolveRunEnvironment(
+  logger: winston.Logger,
+  packageRoot: string,
+  packageName: string,
+  envName: string,
+  requireType: "R",
+): swJson.runEnvDependencyR;
+export function resolveRunEnvironment(
+  logger: winston.Logger,
+  packageRoot: string,
+  packageName: string,
+  envName: string,
+  requireType: artifacts.runEnvironmentType,
+): swJson.runEnvDependency {
+  const [pkgName, id] = util.rSplit(envName, ":", 2);
+  const swDescriptor =
+    pkgName === ""
+      ? readSwJsonFile(packageRoot, packageName, id)
+      : resolveDependency(logger, packageRoot, pkgName, id);
+
+  if (!swDescriptor.runEnv) {
+    throw util.CLIError(
+      `software '${envName}' cannot be used as run environment (no 'runEnv' section in entrypoint descriptor)`,
+    );
+  }
+
+  const runEnv = swDescriptor.runEnv;
+
+  if (runEnv.type !== requireType) {
+    logger.error(
+      `run environment '${envName}' type '${runEnv.type}' differs from declared package type '${requireType}'`,
+    );
+    throw util.CLIError(
+      `incompatible environment: env type '${runEnv.type}' != package type '${requireType}'`,
+    );
+  }
+
+  switch (runEnv.type) {
+    case "python": {
+      return {
+        name: envName,
+        ...runEnv,
+
+        type: "python",
+        ["python-version"]: runEnv["python-version"] ?? "",
+      };
+    }
+    case "R": {
+      return {
+        name: envName,
+        ...runEnv,
+
+        type: "R",
+        ["r-version"]: runEnv["r-version"] ?? "",
+      };
+    }
+    case "java": {
+      return {
+        name: envName,
+        ...runEnv,
+
+        type: "java",
+        ["java-version"]: runEnv["java-version"] ?? "",
+      };
+    }
+    default:
+      util.assertNever(runEnv.type);
+      throw new Error(
+        "renderer logic error: resolveRunEnvironment does not cover all run environment types",
+      ); // calm down the linter
+  }
+}

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

@@ -0,0 +1,72 @@
+import { test, expect } from "vitest";
+import type { z } from "zod/v4";
+import * as artifacts from "./artifacts";
+import * as testArtifacts from "./test-artifacts";
+
+const parseArtifact = <T extends z.ZodTypeAny>(data: string, schema: T): z.infer<T> => {
+  const parsedData: unknown = JSON.parse(data);
+  return schema.parse(parsedData);
+};
+
+// ['conda', artifacts.condaPackageSchema, testArtifacts.CondaArtifact],
+
+test.for([
+  {
+    type: "environment",
+    variant: "minimal",
+    schema: artifacts.environmentSchema,
+    data: testArtifacts.JavaEnvironmentArtifactWithType,
+  },
+  {
+    type: "binary",
+    variant: "minimal",
+    schema: artifacts.binarySchema,
+    data: testArtifacts.BinaryArtifact,
+  },
+  {
+    type: "binary",
+    variant: "version override",
+    schema: artifacts.binarySchema,
+    data: testArtifacts.CustomVersionArtifact,
+  },
+  {
+    type: "java",
+    variant: "minimal",
+    schema: artifacts.javaSchema,
+    data: testArtifacts.JavaArtifact,
+  },
+  {
+    type: "python",
+    variant: "minimal",
+    schema: artifacts.pythonSchema,
+    data: testArtifacts.PythonArtifact,
+  },
+  { type: "R", variant: "minimal", schema: artifacts.rSchema, data: testArtifacts.RArtifact },
+  {
+    type: "docker",
+    variant: "minimal",
+    schema: artifacts.dockerSchema,
+    data: testArtifacts.DockerArtifactWithType,
+  },
+  {
+    type: "docker",
+    variant: "with pkg",
+    schema: artifacts.dockerSchema,
+    data: testArtifacts.DockerArtifactWithPkg,
+  },
+  {
+    type: "docker",
+    variant: "with dockerfile",
+    schema: artifacts.dockerSchema,
+    data: testArtifacts.DockerArtifactWithDockerfile,
+  },
+  {
+    type: "conda",
+    variant: "minimal",
+    schema: artifacts.condaSchema,
+    data: testArtifacts.CondaArtifactWithType,
+  },
+])("parse $type artifact ($variant)", ({ type, schema, data }) => {
+  const binary = parseArtifact(data, schema);
+  expect(binary.type).toEqual(type);
+});

package/src/core/schemas/artifacts.ts

@@ -0,0 +1,279 @@
+import { z } from "zod/v4";
+import * as defaults from "../../defaults";
+import * as util from "../util";
+
+// All known artifact types
+export const artifactTypes = [
+  "asset",
+  "environment",
+  "binary",
+  "java",
+  "python",
+  "R",
+  "docker",
+  "conda",
+] as const;
+export type artifactType = (typeof artifactTypes)[number];
+
+// TODO: change these to type definitions, not arrays. This will simplify type narrowing logic throughout the code.
+export const archiveArtifactTypes: artifactType[] = [
+  "asset",
+  "environment",
+  "binary",
+  "java",
+  "python",
+  "R",
+  "conda",
+] as const;
+export const crossplatformTypes: artifactType[] = ["asset", "java", "python", "R"] as const;
+export const dockerAutogenTypes: artifactType[] = ["python", "conda"] as const;
+export const dockerArchitectures: util.ArchType[] = ["x64"] as const;
+
+export function isBuildable(aType: artifactType): boolean {
+  // All known artifact types are buildable. No exceptions so far.
+  return artifactTypes.includes(aType);
+}
+
+export function isCrossPlatform(aType: artifactType): boolean {
+  return crossplatformTypes.includes(aType);
+}
+
+export const runEnvironmentTypes = ["java", "python", "R"] as const;
+export type runEnvironmentType = (typeof runEnvironmentTypes)[number];
+
+export const pythonToolsets = ["pip"] as const;
+export type pythonToolsetName = (typeof pythonToolsets)[number];
+
+export const registrySchema = z.strictObject({
+  name: z.string(),
+  downloadURL: z.string().optional(),
+  storageURL: z.string().optional(),
+});
+export type registry = z.infer<typeof registrySchema>;
+
+export const registryOrRef = z.union([z.string(), registrySchema]);
+
+// common fields for all buildable artifacts
+// TODO: create new type for binary packages
+const archiveRulesSchema = z.object({
+  registry: registryOrRef.default({
+    name: defaults.BIN_REGISTRY_NAME,
+    downloadURL: defaults.BIN_REGISTRY_DOWNLOAD_URL,
+  }),
+
+  name: z.string().optional(),
+  version: z.string().optional(),
+
+  root: z.string("package archive content directory is required"),
+  roots: z
+    .partialRecord(
+      z.enum(
+        util.AllPlatforms as [
+          (typeof util.AllPlatforms)[number],
+          ...(typeof util.AllPlatforms)[number][],
+        ],
+      ),
+      z.string("path to package archive content directory cannot be empty").min(1),
+      {
+        error: (iss) => {
+          if (iss.input === undefined) {
+            return (
+              "list of supported platforms is required: { <platform>: <dir> }\n" +
+              "supported platforms:\n  " +
+              util.AllPlatforms.join("\n  ")
+            );
+          }
+          return null;
+        },
+      },
+    )
+    .refine((val) => Object.keys(val).length > 0, {
+      message:
+        "specify at least one platform supported by this software in format: { <platform>: <dir> }\n" +
+        "supported platforms:\n  " +
+        util.AllPlatforms.join("\n  "),
+    })
+    .describe(
+      "please, provide settings only for supported platforms: " + util.AllPlatforms.join(", "),
+    ),
+});
+export type archiveRules = z.infer<typeof archiveRulesSchema>;
+
+const dockerRulesSchema = z.object({
+  ["docker-registry"]: z
+    .string(
+      "python software is also automatically shipped as docker image. Docker registry cannot be empty",
+    )
+    .min(1)
+    .default(defaults.DOCKER_REGISTRY)
+    .describe("registry to use for pushing autogenerated docker image"),
+
+  pkg: z
+    .string()
+    .default(defaults.DOCKER_PLACEHOLDER_PKG)
+    .describe(
+      '{pkg} placeholder value to be used in "cmd" and arguments (for docker autogeneration)',
+    ),
+});
+
+export const artifactIDSchema = z
+  .string()
+  .regex(/:/, {
+    message:
+      "tengo artifact ID must have <npmPackage>:<artifactName> format, e.g @milaboratory/runenv-java-corretto:21.2.0.4.1",
+  })
+  .describe("ID of tengo build artifact");
+
+export type artifactIDString = z.infer<typeof artifactIDSchema>;
+
+export const assetSchema = archiveRulesSchema
+  .omit({ roots: true })
+  .extend({ type: z.literal("asset") })
+  .strict();
+export type assetType = z.infer<typeof assetSchema>;
+
+export const environmentSchema = archiveRulesSchema.omit({ root: true }).extend({
+  type: z.literal("environment"),
+
+  runtime: z
+    .enum(runEnvironmentTypes)
+    .describe("type of runtime this run environment provides: 'java', 'python' and so on"),
+
+  ["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()
+    .describe(
+      "path to 'bin' directory to be added to PATH when software uses this run environment",
+    ),
+});
+
+export type environmentType = z.infer<typeof environmentSchema>;
+
+export const binarySchema = archiveRulesSchema.omit({ root: true }).extend({
+  type: z.literal("binary"),
+});
+export type binaryType = z.infer<typeof binarySchema>;
+
+export const javaSchema = archiveRulesSchema.omit({ roots: true }).extend({
+  type: z.literal("java"),
+  environment: artifactIDSchema,
+});
+export type javaType = z.infer<typeof javaSchema>;
+
+const pipToolsetSchema = z.strictObject({
+  toolset: z.literal("pip"),
+  requirements: z.string().describe("path to requrements.txt inside package archive"),
+});
+
+export const pythonToolsetSchema = z.discriminatedUnion("toolset", [pipToolsetSchema]);
+
+export const pythonSchema = archiveRulesSchema
+  .omit({ roots: true })
+  .extend(dockerRulesSchema.shape)
+  .extend({
+    type: z.literal("python"),
+
+    environment: artifactIDSchema,
+    dependencies: pythonToolsetSchema.optional(),
+  });
+export type pythonType = z.infer<typeof pythonSchema>;
+
+export const rSchema = archiveRulesSchema.omit({ roots: true }).extend({
+  type: z.literal("R"),
+  environment: artifactIDSchema,
+});
+export type rType = z.infer<typeof rSchema>;
+
+export const condaSchema = archiveRulesSchema
+  .omit({ root: true })
+  .extend(dockerRulesSchema.shape)
+  .extend({
+    type: z.literal("conda"),
+
+    ["micromamba-version"]: z
+      .string()
+      .default(defaults.CONDA_MICROMAMBA_VERSION)
+      .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()
+      .default(defaults.CONDA_SOURCE_ENV_SPEC_FILE)
+      .describe(`path to conda environment yaml specification relative to package.json`),
+  });
+export type condaType = z.infer<typeof condaSchema>;
+
+export const dockerSchema = z.object({
+  type: z.literal("docker"),
+
+  registry: z
+    .string()
+    .default(defaults.DOCKER_REGISTRY)
+    .describe("registry+repository URL to use for pulling this image"),
+
+  // build from custom Dockerfile
+  context: z
+    .string()
+    .refine((val) => val !== "./" && val !== ".", {
+      message:
+        'Context cannot be "./" or "." - use absolute path or relative path without "./" prefix',
+    })
+    .describe(
+      'relative path to context directory from folder where command is executed or absolute path to context folder (cannot be "./" or ".")',
+    ),
+
+  dockerfile: z
+    .string()
+    .default(defaults.DOCKER_DOCKERFILE)
+    .describe(
+      "relative path to 'Dockerfile' file from folder where command is executed or absolute path to the file",
+    ),
+
+  pkg: z
+    .string()
+    .default(defaults.DOCKER_PLACEHOLDER_PKG)
+    .describe('{pkg} placeholder value to be used in "cmd" and arguments'),
+
+  // import existing image
+  // entrypoint: z
+  //   .array(z.string())
+  //   .optional()
+  //   .describe('replace image\'s ENTRYPOINT with this value when running container'),
+});
+export type dockerType = z.infer<typeof dockerSchema>;
+
+export const anyArtifactSchema = z.discriminatedUnion("type", [
+  assetSchema,
+  environmentSchema,
+  binarySchema,
+  javaSchema,
+  pythonSchema,
+  rSchema,
+  condaSchema,
+  dockerSchema,
+]);
+
+export type anyArtifactType = z.infer<typeof anyArtifactSchema>;
+
+export const artifactIndexSchema = z.record(z.string(), anyArtifactSchema);
+export type artifactIndexType = z.infer<typeof artifactIndexSchema>;
+
+export type withType<Typ, Orig> = Orig & { type: Typ };
+export type withId<T> = T & { id: string };