@helmr/sdk 0.1.0

package/dist/compile.js

@@ -0,0 +1,503 @@
+// sdk/typescript/src/compile.ts
+import { create, toBinary } from "@bufbuild/protobuf";
+import { createHash } from "node:crypto";
+import {
+  BundleSchema,
+  CacheMountBindingSchema,
+  CopyFromImageSchema,
+  CopySourceDirSchema,
+  CopySourceFileSchema,
+  DirPlacementSchema,
+  EnvSchema,
+  EnvPlacementSchema,
+  FilePlacementSchema,
+  FromSchema,
+  ImageSpecSchema,
+  ImageStepSchema,
+  PlacementSchema as BundlePlacementSchema,
+  PlatformSchema,
+  ResourcesSchema,
+  RunSchema,
+  SandboxSpecSchema,
+  SecretPlacementSchema as BundleSecretPlacementSchema,
+  SecretMountBindingSchema,
+  SecretRefSchema,
+  SourceDirRefSchema,
+  SourceFileRefSchema,
+  TaskSpecSchema,
+  UserSchema,
+  WorkdirSchema,
+  WorkspaceRuntimeBindingSchema
+} from "@helmr/proto";
+
+// sdk/typescript/src/schema/task.ts
+var DEFAULT_MAX_DURATION_SECONDS = 900;
+var MIN_MAX_DURATION_SECONDS = 5;
+var MAX_DURATION_SECONDS = 86400;
+class TaskMaxDurationError extends Error {
+  name = "TaskMaxDurationError";
+  value;
+  label;
+  constructor(value, label = "task maxDuration") {
+    super(`${label} must be an integer number of seconds between ${MIN_MAX_DURATION_SECONDS} and ${MAX_DURATION_SECONDS}`);
+    this.value = value;
+    this.label = label;
+  }
+}
+function readOptionalMaxDurationSeconds(value, label = "task maxDuration") {
+  if (value === undefined) {
+    return DEFAULT_MAX_DURATION_SECONDS;
+  }
+  if (typeof value === "number" && Number.isInteger(value) && Number.isFinite(value) && value >= MIN_MAX_DURATION_SECONDS && value <= MAX_DURATION_SECONDS) {
+    return value;
+  }
+  throw new TaskMaxDurationError(value, label);
+}
+
+// sdk/typescript/src/internal.ts
+var approvalTimeoutErrorBrand = Symbol.for("helmr.sdk.ApprovalTimeoutError");
+var messageTimeoutErrorBrand = Symbol.for("helmr.sdk.MessageTimeoutError");
+var concurrentWaitErrorBrand = Symbol.for("helmr.sdk.ConcurrentWaitError");
+function validateSecretName(name, label = "secret name") {
+  if (name.length === 0) {
+    throw new Error(`${label} must not be empty`);
+  }
+  if (name.length > 128) {
+    throw new Error(`${label} must be at most 128 characters`);
+  }
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new Error(`${label} must match /^[A-Za-z_][A-Za-z0-9_]*$/`);
+  }
+  const upper = name.toUpperCase();
+  if (upper === "CON" || upper === "PRN" || upper === "AUX" || upper === "NUL" || /^COM[1-9]$/.test(upper) || /^LPT[1-9]$/.test(upper)) {
+    throw new Error(`${label} is reserved`);
+  }
+}
+var taskBrand = Symbol.for("helmr.sdk.Task");
+var taskOriginBrand = Symbol.for("helmr.sdk.TaskOrigin");
+var configBrand = Symbol.for("helmr.sdk.Config");
+var imageBuilderBrand = Symbol.for("helmr.sdk.ImageBuilder");
+var sandboxBuilderBrand = Symbol.for("helmr.sdk.SandboxBuilder");
+var sourceFileRefBrand = Symbol.for("helmr.sdk.SourceFileRef");
+var sourceDirRefBrand = Symbol.for("helmr.sdk.SourceDirRef");
+function isImageBuilder(value) {
+  return hasBrand(value, imageBuilderBrand);
+}
+function isSandboxBuilder(value) {
+  return hasBrand(value, sandboxBuilderBrand);
+}
+function isSourceFileRef(value) {
+  return hasBrand(value, sourceFileRefBrand);
+}
+function isSourceDirRef(value) {
+  return hasBrand(value, sourceDirRefBrand);
+}
+function hasBrand(value, brand) {
+  return value !== null && typeof value === "object" && value[brand] === true;
+}
+
+// sdk/typescript/src/compile.ts
+var IMAGE_FORMAT_VERSION = 1;
+var IMAGE_KEY_DOMAIN = `helmr.image.v1
+`;
+function compile(opts) {
+  const task = opts.task;
+  if (!isSandboxBuilder(task.sandbox)) {
+    throw new Error(`task "${task.id}" must declare sandbox: sandbox(...)`);
+  }
+  const compiler = new BundleCompiler;
+  const imageSpec = compiler.compileSandboxImage(task.sandbox);
+  const subImages = compiler.compileSubImages(imageSpec);
+  const workspace = compiler.compileWorkspace(task.sandbox);
+  const resources = task.sandbox.resourceSpec;
+  const maxDurationSeconds = readOptionalMaxDurationSeconds(task.maxDuration, `task "${task.id}" maxDuration`);
+  const sandboxSpec = create(SandboxSpecSchema, {
+    id: task.sandbox.id,
+    workspace,
+    ...resources ? {
+      resources: create(ResourcesSchema, {
+        ...resources.cpu === undefined ? {} : { cpu: resources.cpu },
+        ...resources.memory === undefined ? {} : { memory: resources.memory }
+      })
+    } : {}
+  });
+  return create(BundleSchema, {
+    image: imageSpec,
+    sandbox: sandboxSpec,
+    subImages,
+    task: create(TaskSpecSchema, {
+      id: task.id,
+      sandboxId: task.sandbox.id,
+      modulePath: opts.modulePath,
+      exportName: opts.exportName ?? "default",
+      maxDurationSeconds,
+      secrets: Object.entries(readSecretDecls(task.secrets)).map(([name, placement]) => create(BundleSecretPlacementSchema, {
+        name,
+        placement: compilePlacement(placement)
+      }))
+    })
+  });
+}
+function compilePlacement(placement) {
+  if ("env" in placement) {
+    return create(BundlePlacementSchema, {
+      kind: {
+        case: "env",
+        value: create(EnvPlacementSchema, {
+          name: placement.env
+        })
+      }
+    });
+  }
+  if ("file" in placement) {
+    return create(BundlePlacementSchema, {
+      kind: {
+        case: "file",
+        value: create(FilePlacementSchema, {
+          path: placement.file,
+          ...placement.mode === undefined ? {} : { mode: placement.mode },
+          ...placement.owner === undefined ? {} : { owner: placement.owner }
+        })
+      }
+    });
+  }
+  return create(BundlePlacementSchema, {
+    kind: {
+      case: "dir",
+      value: create(DirPlacementSchema, {
+        path: placement.dir,
+        ...placement.mode === undefined ? {} : { mode: placement.mode },
+        ...placement.owner === undefined ? {} : { owner: placement.owner }
+      })
+    }
+  });
+}
+
+class BundleCompiler {
+  imageSpecs = new Map;
+  compileSandboxImage(sandbox) {
+    const image = sandbox.imageBuilder;
+    if (!image) {
+      throw new Error(`sandbox "${sandbox.id}" must declare image(...)`);
+    }
+    return this.compileImage(image);
+  }
+  compileWorkspace(sandbox) {
+    const workspace = sandbox.workspaceBinding ?? {
+      mountPath: "/workspace"
+    };
+    return create(WorkspaceRuntimeBindingSchema, {
+      mountPath: workspace.mountPath
+    });
+  }
+  compileImage(image) {
+    const existing = this.imageSpecs.get(image);
+    if (existing) {
+      return existing;
+    }
+    if (image.steps.length === 0) {
+      throw new Error(`image "${image.id}" must contain at least one operation`);
+    }
+    const spec = create(ImageSpecSchema, {
+      formatVersion: IMAGE_FORMAT_VERSION,
+      platform: create(PlatformSchema, { os: "linux", architecture: currentArchitecture() }),
+      steps: image.steps.map((step) => this.compileBuildStep(step))
+    });
+    this.imageSpecs.set(image, spec);
+    return spec;
+  }
+  compileSubImages(root) {
+    const values = {};
+    for (const spec of this.imageSpecs.values()) {
+      if (spec === root) {
+        continue;
+      }
+      values[compileProvisionalImageKey(spec)] = spec;
+    }
+    return values;
+  }
+  compileBuildStep(step) {
+    switch (step.kind) {
+      case "from":
+        return create(ImageStepSchema, {
+          kind: { case: "from", value: create(FromSchema, { ref: step.ref }) }
+        });
+      case "run":
+        return create(ImageStepSchema, {
+          kind: {
+            case: "run",
+            value: create(RunSchema, {
+              argv: [...step.argv],
+              cacheMounts: step.cache.map((binding) => create(CacheMountBindingSchema, {
+                dst: binding.mountPath,
+                cacheId: binding.cache.id,
+                sharing: "locked"
+              })),
+              secretMounts: step.secrets.map((binding) => create(SecretMountBindingSchema, {
+                dst: binding.mountPath,
+                secretRef: create(SecretRefSchema, { name: binding.secret })
+              }))
+            })
+          }
+        });
+      case "copy":
+        return this.compileCopyStep(step.dest, step.source);
+      case "copyFrom":
+        return create(ImageStepSchema, {
+          kind: {
+            case: "copyFromImage",
+            value: create(CopyFromImageSchema, {
+              dst: step.dest,
+              srcImageKey: compileProvisionalImageKey(this.compileImage(step.source)),
+              srcPath: step.srcPath
+            })
+          }
+        });
+      case "workdir":
+        return create(ImageStepSchema, {
+          kind: { case: "workdir", value: create(WorkdirSchema, { path: step.path }) }
+        });
+      case "env":
+        return create(ImageStepSchema, {
+          kind: { case: "env", value: create(EnvSchema, { key: step.key, value: step.value }) }
+        });
+      case "user":
+        return create(ImageStepSchema, {
+          kind: { case: "user", value: create(UserSchema, { name: step.name }) }
+        });
+    }
+  }
+  compileCopyStep(dest, source) {
+    if (isSourceFileRef(source)) {
+      return create(ImageStepSchema, {
+        kind: {
+          case: "copySourceFile",
+          value: create(CopySourceFileSchema, {
+            dst: dest,
+            srcRef: create(SourceFileRefSchema, { path: source.path })
+          })
+        }
+      });
+    }
+    if (isSourceDirRef(source)) {
+      return create(ImageStepSchema, {
+        kind: {
+          case: "copySourceDir",
+          value: create(CopySourceDirSchema, {
+            dst: dest,
+            srcRef: this.compileSourceDirRef(source),
+            ignore: [...source.ignore]
+          })
+        }
+      });
+    }
+    if (isImageBuilder(source)) {
+      return create(ImageStepSchema, {
+        kind: {
+          case: "copyFromImage",
+          value: create(CopyFromImageSchema, {
+            dst: dest,
+            srcImageKey: compileProvisionalImageKey(this.compileImage(source)),
+            srcPath: "/"
+          })
+        }
+      });
+    }
+    throw new Error("image.copy() source must be source.file(), source.directory(), or image()");
+  }
+  compileSourceDirRef(ref) {
+    return create(SourceDirRefSchema, { path: ref.path, ignore: [...ref.ignore] });
+  }
+}
+function currentArchitecture() {
+  switch (process.arch) {
+    case "arm64":
+      return "arm64";
+    case "x64":
+      return "amd64";
+    default:
+      return process.arch;
+  }
+}
+function compileProvisionalImageKey(image) {
+  return canonicalImageKey(image);
+}
+function canonicalImageKey(image) {
+  const hash = createHash("sha256");
+  hash.update(IMAGE_KEY_DOMAIN);
+  hash.update(u32be(image.formatVersion));
+  hashLenPrefixedBytes(hash, image.platform ? toBinary(PlatformSchema, image.platform) : new Uint8Array);
+  hashLenPrefixedBytes(hash, encodeImageSteps(image.steps));
+  hashLenPrefixedBytes(hash, encodeDigestList(sourceInputDigests(image.steps)));
+  hashLenPrefixedBytes(hash, encodeDigestList(subImageKeys(image.steps)));
+  return `sha256:${hash.digest("hex")}`;
+}
+function encodeImageSteps(steps) {
+  const chunks = [u64be(steps.length)];
+  for (const step of steps) {
+    chunks.push(lenPrefixedBytes(toBinary(ImageStepSchema, step)));
+  }
+  return concatBytes(chunks);
+}
+function encodeDigestList(values) {
+  const chunks = [u64be(values.length)];
+  for (const value of values) {
+    chunks.push(lenPrefixedBytes(new TextEncoder().encode(value)));
+  }
+  return concatBytes(chunks);
+}
+function sourceInputDigests(steps) {
+  const values = [];
+  for (const step of steps) {
+    switch (step.kind.case) {
+      case "copySourceFile":
+        values.push(step.kind.value.digest);
+        break;
+      case "copySourceDir":
+        values.push(step.kind.value.treeDigest);
+        break;
+    }
+  }
+  return values;
+}
+function subImageKeys(steps) {
+  const values = [];
+  for (const step of steps) {
+    if (step.kind.case === "copyFromImage") {
+      values.push(step.kind.value.srcImageKey);
+    }
+  }
+  return values;
+}
+function hashLenPrefixedBytes(hash, bytes) {
+  hash.update(u64be(bytes.byteLength));
+  hash.update(bytes);
+}
+function lenPrefixedBytes(bytes) {
+  return concatBytes([u64be(bytes.byteLength), bytes]);
+}
+function u32be(value) {
+  const buffer = Buffer.alloc(4);
+  buffer.writeUInt32BE(value);
+  return buffer;
+}
+function u64be(value) {
+  const buffer = Buffer.alloc(8);
+  buffer.writeBigUInt64BE(BigInt(value));
+  return buffer;
+}
+function concatBytes(chunks) {
+  const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out;
+}
+function readSecretDecls(value) {
+  if (value === undefined) {
+    return {};
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("task secrets must be an object literal");
+  }
+  const record = value;
+  return Object.fromEntries(Object.entries(record).map(([name, placement]) => {
+    validateSecretName(name, `task secrets.${name}`);
+    return [name, readPlacement(placement, `task secrets.${name}`)];
+  }));
+}
+function readPlacement(value, label) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be a placement object`);
+  }
+  const record = value;
+  if ("env" in record) {
+    const env = record["env"];
+    if (Object.keys(record).length !== 1 || !isNonEmptyPlacementString(env)) {
+      throw new Error(`${label} must be { env: string }`);
+    }
+    return { env };
+  }
+  if ("file" in record) {
+    const file = record["file"];
+    const mode = readOptionalPlacementString(record, "mode");
+    const owner = readOptionalPlacementString(record, "owner");
+    if (!hasOnlyKeys(record, ["file", "mode", "owner"]) || !isNonEmptyPlacementString(file)) {
+      throw new Error(`${label} must be { file: string, mode?: string, owner?: string }`);
+    }
+    if (mode === INVALID_PLACEMENT_STRING || owner === INVALID_PLACEMENT_STRING) {
+      throw new Error(`${label} must be { file: string, mode?: string, owner?: string }`);
+    }
+    validatePlacementPath(file, `${label}.file`);
+    validatePlacementMode(mode, `${label}.mode`);
+    return {
+      file,
+      ...mode === undefined ? {} : { mode },
+      ...owner === undefined ? {} : { owner }
+    };
+  }
+  if ("dir" in record) {
+    const dir = record["dir"];
+    const mode = readOptionalPlacementString(record, "mode");
+    const owner = readOptionalPlacementString(record, "owner");
+    if (!hasOnlyKeys(record, ["dir", "mode", "owner"]) || !isNonEmptyPlacementString(dir)) {
+      throw new Error(`${label} must be { dir: string, mode?: string, owner?: string }`);
+    }
+    if (mode === INVALID_PLACEMENT_STRING || owner === INVALID_PLACEMENT_STRING) {
+      throw new Error(`${label} must be { dir: string, mode?: string, owner?: string }`);
+    }
+    validatePlacementPath(dir, `${label}.dir`);
+    validatePlacementMode(mode, `${label}.mode`);
+    return {
+      dir,
+      ...mode === undefined ? {} : { mode },
+      ...owner === undefined ? {} : { owner }
+    };
+  }
+  throw new Error(`${label} must be one of { env }, { file, mode?, owner? }, or { dir, mode?, owner? }`);
+}
+var INVALID_PLACEMENT_STRING = Symbol("invalid placement string");
+function isNonEmptyPlacementString(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function readOptionalPlacementString(record, key) {
+  const value = record[key];
+  if (value === undefined) {
+    return;
+  }
+  return typeof value === "string" ? value : INVALID_PLACEMENT_STRING;
+}
+function validatePlacementMode(mode, label) {
+  if (mode === undefined) {
+    return;
+  }
+  const normalized = mode.trim().replace(/^0[oO]/, "");
+  if (!/^[0-7]+$/.test(normalized)) {
+    throw new Error(`${label} must be an octal permission mode`);
+  }
+  if (Number.parseInt(normalized, 8) > 511) {
+    throw new Error(`${label} must only contain permission bits`);
+  }
+}
+function validatePlacementPath(path, label) {
+  const normalized = path.trim().replaceAll("\\", "/");
+  if (path !== path.trim()) {
+    throw new Error(`${label} must not contain leading or trailing whitespace`);
+  }
+  if (normalized === "." || normalized === "/") {
+    throw new Error(`${label} must target a file or directory`);
+  }
+  if (normalized.split("/").includes("..")) {
+    throw new Error(`${label} must not contain parent components`);
+  }
+}
+function hasOnlyKeys(record, allowed) {
+  return Object.keys(record).every((key) => allowed.includes(key));
+}
+export {
+  compile,
+  IMAGE_FORMAT_VERSION
+};

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+import { type HelmrConfig } from "./internal.js";
+export interface HelmrConfigInput {
+    readonly project?: string;
+    readonly dirs: readonly string[];
+    readonly ignorePatterns?: readonly string[];
+}
+export declare function defineConfig(config: HelmrConfigInput): HelmrConfig;
+export type { HelmrConfig };

package/dist/fuzzy.d.ts

@@ -0,0 +1 @@
+export declare function levenshteinDistance(left: string, right: string): number;

package/dist/fuzzy.js

@@ -0,0 +1,29 @@
+// sdk/typescript/src/fuzzy.ts
+function levenshteinDistance(left, right) {
+  if (left === right) {
+    return 0;
+  }
+  if (left.length === 0) {
+    return right.length;
+  }
+  if (right.length === 0) {
+    return left.length;
+  }
+  const previous = new Array(right.length + 1);
+  const current = new Array(right.length + 1);
+  for (let column = 0;column <= right.length; column += 1) {
+    previous[column] = column;
+  }
+  for (let row = 1;row <= left.length; row += 1) {
+    current[0] = row;
+    for (let column = 1;column <= right.length; column += 1) {
+      const cost = left[row - 1] === right[column - 1] ? 0 : 1;
+      current[column] = Math.min(current[column - 1] + 1, previous[column] + 1, previous[column - 1] + cost);
+    }
+    previous.splice(0, previous.length, ...current);
+  }
+  return previous[right.length] ?? right.length;
+}
+export {
+  levenshteinDistance
+};

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { ApprovalTimeoutError, ConcurrentWaitError, MessageTimeoutError, validateSecretName, type CacheBuilder, type CacheMount, type CacheMountBinding, type EmitContent, type EmitEvent, type ImageBuilder, type ImageRunOptions, type Placement, type SandboxBuilder, type SecretDecls, type SecretMountBinding, type SourceCapabilities, type SourceDirRef, type SourceDirectoryOptions, type SourceFileRef, type TaskContext, type TaskOutput, type TaskPayload, type WorkspaceCapabilities, type WorkspaceSpec } from "./internal.js";
+import { HelmrClient } from "./runtime/client.js";
+import { sandbox } from "./sandbox.js";
+import { defineConfig, type HelmrConfig, type HelmrConfigInput } from "./config.js";
+import { task, type Task, type TaskConfig } from "./task.js";
+import { tasks } from "./trigger.js";
+export { AuthError, RunNotFoundError, TimeoutError, UnsupportedTransportError } from "./runtime/errors.js";
+export { ApprovalTimeoutError, ConcurrentWaitError, MessageTimeoutError };
+export { type LogSnapshot, type ListRunEventsOptions, type ListRunsOptions, type PendingApprovalWaitpoint, type PendingMessageWaitpoint, type PendingWaitpoint, type RetrieveRunOptions, type RunEvent, type RunEventRecord, type RunEventRecordPage, type RunHandle, type RunSnapshot, type RunStatus, type RunSummary, type RunWaitOptions, type SubscribeRunEventsOptions, type WaitpointApprovalOptions, type WaitpointRef, type WaitpointReplyOptions, } from "./runtime/run.js";
+export { defineConfig, sandbox, task, tasks };
+export type { HelmrConfig, HelmrConfigInput, Placement, SecretDecls, Task, TaskConfig, TaskOutput, TaskPayload, };
+export declare const image: (id: string) => ImageBuilder;
+export declare const cache: (id: string) => CacheBuilder;
+export declare const source: SourceCapabilities;
+export declare const workspace: WorkspaceCapabilities;
+export { HelmrClient };
+export { validateSecretName };
+export declare const runs: {
+    retrieve: <TOutput = unknown>(idOrHandle: string | import("./index.js").RunHandle<TOutput>, opts?: import("./index.js").RetrieveRunOptions) => Promise<import("./index.js").RunSnapshot<TOutput>>;
+    wait: <TOutput = unknown>(idOrHandle: string | import("./index.js").RunHandle<TOutput>, opts?: import("./index.js").RunWaitOptions) => Promise<import("./index.js").RunSnapshot<TOutput>>;
+    list: (opts?: import("./index.js").ListRunsOptions) => Promise<import("./index.js").RunSummary[]>;
+    logs: {
+        retrieve: <TOutput = unknown>(idOrHandle: string | import("./index.js").RunHandle<TOutput>, opts?: {
+            readonly signal?: AbortSignal;
+        }) => Promise<import("./index.js").LogSnapshot>;
+    };
+    events: {
+        list: <TOutput = unknown>(idOrHandle: string | import("./index.js").RunHandle<TOutput>, opts?: import("./index.js").ListRunEventsOptions) => Promise<import("./index.js").RunEvent[]>;
+        subscribe: <TOutput = unknown>(idOrHandle: string | import("./index.js").RunHandle<TOutput>, opts?: import("./index.js").SubscribeRunEventsOptions) => Promise<AsyncIterable<import("./index.js").RunEvent>>;
+    };
+};
+export declare const waitpoints: import("./runtime/client.js").WaitpointsApi;
+export type { CacheBuilder, CacheMount, CacheMountBinding, EmitContent, EmitEvent, ImageBuilder, ImageRunOptions, SandboxBuilder, SecretMountBinding, SourceCapabilities, SourceDirRef, SourceDirectoryOptions, SourceFileRef, WorkspaceCapabilities, WorkspaceSpec, TaskContext, };