@platforma-sdk/package-builder-lib 1.1.0 → 1.2.0

package/src/core/package-info.test.ts

@@ -1,13 +1,18 @@
 import { PackageInfo } from "./package-info";
 import * as testArtifacts from "./schemas/test-artifacts";
-import { createLogger } from "./util";
-import { test, expect } from "vitest";
+import { createLogger, isDevMode, producesRegistryDescriptor } from "./util";
+import * as envs from "./envs";
+import * as defaults from "../defaults";
+import { test, expect, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 
 test("PackageInfo loads correctly for single binary package", () => {
   const l = createLogger("error");
 
   const i = new PackageInfo(l, {
-    pkgJsonData: testArtifacts.SingleBinaryackageJson,
+    pkgJsonData: testArtifacts.SingleBinaryPackageJson,
   });
 
   const binary = i.getArtifact(testArtifacts.EPNameBinary, "binary");
@@ -80,3 +85,157 @@ test("PackageInfo considers version override", () => {
   const java = i.getArtifact(testArtifacts.EPNameJava, "java");
   expect(i.artifactVersion(java)).toEqual(customVersion);
 });
+
+test("content-addressable dev naming appends a content hash", () => {
+  const l = createLogger("error");
+
+  // Real package roots so the asset's "./src" content root resolves and can be hashed.
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "pkg-info-dev-"));
+  const root2 = fs.mkdtempSync(path.join(os.tmpdir(), "pkg-info-dev-"));
+  const devAsset = (packageRoot: string): string => {
+    const pi = new PackageInfo(l, { packageRoot, pkgJsonData: testArtifacts.PackageJson });
+    pi.buildMode = "dev-local";
+    return pi.artifactVersion(pi.getArtifact(testArtifacts.EPNameAsset, "asset"));
+  };
+
+  try {
+    fs.mkdirSync(path.join(root, "src"));
+    fs.writeFileSync(path.join(root, "src", "a.txt"), "hello");
+
+    const i = new PackageInfo(l, { packageRoot: root, pkgJsonData: testArtifacts.PackageJson });
+    const asset = i.getArtifact(testArtifacts.EPNameAsset, "asset");
+    const docker = i.getArtifact(testArtifacts.EPNameDocker, "docker");
+
+    // Release (default): version-derived, no suffix.
+    expect(i.artifactVersion(asset)).toEqual(testArtifacts.PackageVersion);
+
+    // Dev: a `-<12 hex>` content suffix, deterministic for unchanged content.
+    i.buildMode = "dev-local";
+    const dev1 = i.artifactVersion(asset);
+    expect(dev1).toMatch(new RegExp(`^${testArtifacts.PackageVersion}-[0-9a-f]{12}$`));
+    expect(i.artifactVersion(asset)).toEqual(dev1);
+
+    // Docker stays version-derived (already content-addressed via its image-ID tag).
+    expect(i.artifactVersion(docker)).toEqual(testArtifacts.PackageVersion);
+
+    // Reproducible: identical content at a different absolute location yields the same suffix
+    // (hash is over relative paths + file contents, sorted — not the build directory).
+    fs.mkdirSync(path.join(root2, "src"));
+    fs.writeFileSync(path.join(root2, "src", "a.txt"), "hello");
+    expect(devAsset(root2)).toEqual(dev1);
+
+    // Changed content ⟹ a different name (a fresh build over the changed tree).
+    fs.writeFileSync(path.join(root, "src", "b.txt"), "world");
+    expect(devAsset(root)).not.toEqual(dev1);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+    fs.rmSync(root2, { recursive: true, force: true });
+  }
+});
+
+test("dev content hash: absent root yields no suffix; a pinned version still gets one", () => {
+  const l = createLogger("error");
+  const empty = fs.mkdtempSync(path.join(os.tmpdir(), "pkg-info-noroot-"));
+  const withSrc = fs.mkdtempSync(path.join(os.tmpdir(), "pkg-info-src-"));
+  try {
+    // No ./src on disk → the asset's content root is absent → no hash suffix, even in dev.
+    const noRoot = new PackageInfo(l, {
+      packageRoot: empty,
+      pkgJsonData: testArtifacts.PackageJson,
+    });
+    noRoot.buildMode = "dev-local";
+    expect(noRoot.artifactVersion(noRoot.getArtifact(testArtifacts.EPNameAsset, "asset"))).toEqual(
+      testArtifacts.PackageVersion,
+    );
+
+    // Present root + explicit --version override: dev naming stays content-addressable, so the
+    // pinned version still gets the -<hash> suffix (a same-name re-push would be silently stale).
+    fs.mkdirSync(path.join(withSrc, "src"));
+    fs.writeFileSync(path.join(withSrc, "src", "a.txt"), "hello");
+    const pinned = new PackageInfo(l, {
+      packageRoot: withSrc,
+      pkgJsonData: testArtifacts.PackageJson,
+    });
+    pinned.buildMode = "dev-local";
+    pinned.version = "9.9.9";
+    expect(pinned.artifactVersion(pinned.getArtifact(testArtifacts.EPNameAsset, "asset"))).toMatch(
+      /^9\.9\.9-[0-9a-f]{12}$/,
+    );
+  } finally {
+    fs.rmSync(empty, { recursive: true, force: true });
+    fs.rmSync(withSrc, { recursive: true, force: true });
+  }
+});
+
+test("dev content hash is memoized for the builder's lifetime", () => {
+  const l = createLogger("error");
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "pkg-info-memo-"));
+  try {
+    fs.mkdirSync(path.join(root, "src"));
+    fs.writeFileSync(path.join(root, "src", "a.txt"), "hello");
+    const i = new PackageInfo(l, { packageRoot: root, pkgJsonData: testArtifacts.PackageJson });
+    i.buildMode = "dev-local";
+    const asset = i.getArtifact(testArtifacts.EPNameAsset, "asset");
+    const first = i.artifactVersion(asset);
+    // Mutate the tree; content roots are read once per builder, so the cached hash must not change.
+    fs.writeFileSync(path.join(root, "src", "b.txt"), "world");
+    expect(i.artifactVersion(asset)).toEqual(first);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("build-mode predicates split channel from descriptor shape", () => {
+  expect(isDevMode("dev-local")).toBe(true);
+  expect(isDevMode("dev-remote")).toBe(true);
+  expect(isDevMode("release")).toBe(false);
+
+  // dev-local is the only same-host mode: it does NOT build an archive / registry descriptor.
+  expect(producesRegistryDescriptor("dev-local")).toBe(false);
+  expect(producesRegistryDescriptor("dev-remote")).toBe(true);
+  expect(producesRegistryDescriptor("release")).toBe(true);
+});
+
+const devUploadEnv = envs.PL_DEV_BINARY_UPLOAD_URL;
+const releaseUploadEnv = envs.PL_RELEASE_BINARY_UPLOAD_URL;
+afterEach(() => {
+  delete process.env[devUploadEnv];
+  delete process.env[releaseUploadEnv];
+});
+
+test("dev channel flips the embedded binary registry name to midev/dev", () => {
+  const l = createLogger("error");
+  const i = new PackageInfo(l, { pkgJsonData: testArtifacts.SingleBinaryPackageJson });
+  const binary = i.getArtifact(testArtifacts.EPNameBinary, "binary");
+
+  // Release: keeps the artifact's resolved registry name (default platforma-open here).
+  const releaseName = i.artifactRegistrySettings(binary).name;
+  expect(releaseName).toEqual("platforma-open");
+
+  // Dev, built-in default: name is midev, upload routes to the built-in midev endpoint.
+  i.buildMode = "dev-remote";
+  const devDefault = i.artifactRegistrySettings(binary);
+  expect(devDefault.name).toEqual("midev");
+  expect(devDefault.storageURL).toEqual(defaults.DEV_BINARY_UPLOAD_TARGET);
+
+  // Dev with an explicit endpoint: name flips to dev and the upload URL routes there.
+  process.env[devUploadEnv] = "s3://my-bucket/dev?region=eu-central-1";
+  const dev = i.artifactRegistrySettings(binary);
+  expect(dev.name).toEqual("dev");
+  expect(dev.storageURL).toEqual("s3://my-bucket/dev?region=eu-central-1");
+
+  // dev-local channel behaves the same for naming.
+  i.buildMode = "dev-local";
+  expect(i.artifactRegistrySettings(binary).name).toEqual("dev");
+});
+
+test("release honors PL_RELEASE_BINARY_UPLOAD_URL without renaming", () => {
+  const l = createLogger("error");
+  const i = new PackageInfo(l, { pkgJsonData: testArtifacts.SingleBinaryPackageJson });
+  const binary = i.getArtifact(testArtifacts.EPNameBinary, "binary");
+
+  process.env[releaseUploadEnv] = "s3://release-bucket/pub?region=eu-central-1";
+  const rel = i.artifactRegistrySettings(binary);
+  expect(rel.name).toEqual("platforma-open");
+  expect(rel.storageURL).toEqual("s3://release-bucket/pub?region=eu-central-1");
+});

package/src/core/package-info.ts

@@ -1,5 +1,6 @@
 import * as path from "node:path";
 import * as fs from "node:fs";
+import { createHash } from "node:crypto";
 import type winston from "winston";
 import { z } from "zod/v4";
 
@@ -85,6 +86,9 @@ export class PackageInfo {
   private readonly pkgJson: packageJson;
   private _versionOverride: string | undefined;
 
+  /** Backing store for `Core.buildMode` (Core delegates its accessor here); gates content-addressable dev naming. */
+  public buildMode: util.BuildMode = "release";
+
   constructor(
     private logger: winston.Logger,
     options?: {
@@ -499,7 +503,20 @@ export class PackageInfo {
     return util.trimPrefix(this.pkgJson.name, "@") + "/" + artifact.id;
   }
 
-  public artifactVersion(artifact: artifacts.anyArtifactType): string {
+  public artifactVersion(artifact: artifacts.withId<artifacts.anyArtifactType>): string {
+    const base = this.baseArtifactVersion(artifact);
+
+    if (util.isDevMode(this.buildMode) && artifact.type !== "docker") {
+      const hash = this.devContentHash(artifact);
+      if (hash) {
+        return `${base}-${hash}`;
+      }
+    }
+
+    return base;
+  }
+
+  private baseArtifactVersion(artifact: artifacts.withId<artifacts.anyArtifactType>): string {
     if (this._versionOverride) {
       return this._versionOverride;
     }
@@ -515,6 +532,58 @@ export class PackageInfo {
     return this.pkgJson.version;
   }
 
+  /**
+   * Short content hash of the artifact's content root(s), used as the dev version suffix.
+   */
+  private readonly devContentHashCache = new Map<string, string | undefined>();
+
+  private devContentHash(
+    artifact: artifacts.withId<artifacts.anyArtifactType>,
+  ): string | undefined {
+    // Content roots are stable for the lifetime of this builder, so hash each artifact once.
+    if (this.devContentHashCache.has(artifact.id)) {
+      return this.devContentHashCache.get(artifact.id);
+    }
+
+    const hash = this.computeDevContentHash(artifact);
+    this.devContentHashCache.set(artifact.id, hash);
+    return hash;
+  }
+
+  private computeDevContentHash(
+    artifact: artifacts.withId<artifacts.anyArtifactType>,
+  ): string | undefined {
+    const hasher = createHash("sha256");
+    let hashedAny = false;
+
+    let platforms: util.PlatformType[];
+    try {
+      // Sorted so the hash is independent of package.json root-key order.
+      platforms = this.artifactPlatforms(artifact).toSorted();
+    } catch {
+      return undefined; // no content roots at all — leave the version without a suffix
+    }
+
+    for (const platform of platforms) {
+      let root: string;
+      try {
+        root = this.artifactContentRoot(artifact, platform);
+      } catch {
+        continue; // platform without a defined/present root — skip
+      }
+      if (!fs.existsSync(root)) {
+        continue;
+      }
+      // Hash the platform name too, so the same files under a different platform yield a different
+      // hash.
+      hasher.update(platform);
+      util.hashDirSync(root, hasher);
+      hashedAny = true;
+    }
+
+    return hashedAny ? hasher.digest("hex").slice(0, 12) : undefined;
+  }
+
   public artifactRegistrySettings(artifact: artifacts.anyArtifactType): artifacts.registry {
     if (artifact.type === "docker") {
       return {
@@ -559,6 +628,21 @@ export class PackageInfo {
       result.downloadURL = downloadFrom;
     }
 
+    // Dev channel: the embedded binary registry is the built-in `midev` uploading to its built-in
+    // endpoint, flipping to `dev` and `PL_DEV_BINARY_UPLOAD_URL` when that is set.
+    if (util.isDevMode(this.buildMode)) {
+      const devUpload = process.env[envs.PL_DEV_BINARY_UPLOAD_URL];
+      result.name = devUpload
+        ? defaults.DEV_BIN_REGISTRY_NAME_OVERRIDDEN
+        : defaults.DEV_BIN_REGISTRY_NAME;
+      result.storageURL = devUpload ?? defaults.DEV_BINARY_UPLOAD_TARGET;
+    } else {
+      const releaseUpload = process.env[envs.PL_RELEASE_BINARY_UPLOAD_URL];
+      if (releaseUpload) {
+        result.storageURL = releaseUpload;
+      }
+    }
+
     if (result.downloadURL) {
       const u = new URL(result.downloadURL, "file:/nonexistent"); // check download URL is valid URL
       if (!["https:", "http:"].includes(u.protocol)) {
@@ -718,8 +802,9 @@ export class PackageInfo {
         hasErrors = true;
       }
 
-      const name = this.artifactName({ id: artifactID, ...artifact });
-      const version = this.artifactVersion(artifact);
+      const withId = { id: artifactID, ...artifact };
+      const name = this.artifactName(withId);
+      const version = this.artifactVersion(withId);
       const uniqueName = `${name}-${version}`;
       if (uniquePackageNames.has(uniqueName)) {
         this.logger.error(

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

@@ -346,7 +346,7 @@ export const PackageJson = `{
     }
 }`;
 
-export const SingleBinaryackageJson = `{
+export const SingleBinaryPackageJson = `{
   "name": "${PackageName}",
   "version": "${PackageVersion}",
   "block-software": {

package/src/core/sw-json-render.test.ts

@@ -156,6 +156,29 @@ describe("Renderer tests", () => {
     expect(javaDescriptor.docker!.cmd).toEqual(["java", "-jar", "hello.jar"]);
   });
 
+  test("render no-software placeholder", () => {
+    const sw = new SwJsonRenderer(l, i);
+
+    // No artifact info written — placeholders need nothing built. A docker+binary pair collapses
+    // to a single placeholder for their shared origin entrypoint.
+    const epName = test_assets.EPNameJava;
+    const eps = new Map([
+      [docker.entrypointName(epName), i.getMainEntrypoint(docker.entrypointName(epName))],
+      [epName, i.getMainEntrypoint(epName)],
+    ]);
+    const result = sw.renderPlaceholderEntrypoints(eps);
+
+    expect(result.size).toBe(1);
+    const descriptor = result.get(epName)!;
+    expect(descriptor.isDev).toBe(true);
+    expect(descriptor.binary).toEqual({
+      type: "binary",
+      registry: defaults.NO_SOFTWARE_PLACEHOLDER,
+      package: defaults.NO_SOFTWARE_PLACEHOLDER,
+      cmd: ["true"],
+    });
+  });
+
   test("render docker indinvidual entrypoint", () => {
     const dockerEpName = test_assets.EPNameDocker;
     const dockerPkg = i.getArtifact(dockerEpName, "docker");

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

@@ -58,12 +58,12 @@ export class SwJsonRenderer {
         throw util.CLIError(`Entrypoint ${epName} not found in result`);
       }
 
-      if (mode !== "release") {
+      if (util.isDevMode(mode)) {
         info.isDev = true;
       }
 
       const pkg = ep.artifact;
-      if (util.isDevLocalMode(mode)) {
+      if (!util.producesRegistryDescriptor(mode)) {
         switch (pkg.type) {
           case "docker": {
             info.docker = this.renderDockerInfo(epName, ep, options?.requireAllArtifacts);
@@ -122,6 +122,31 @@ export class SwJsonRenderer {
     return result;
   }
 
+  // One minimal `binary` placeholder per entrypoint, so a block builds, loads, and renders without
+  // any software; only executing it fails, against the sentinel registry. References are copied
+  // through by the caller, so they are skipped here.
+  public renderPlaceholderEntrypoints(
+    entrypoints: Map<string, entrypoint.Entrypoint>,
+  ): Map<string, swJson.swJsonType> {
+    const result = new Map<string, swJson.swJsonType>();
+    for (const [epName, ep] of entrypoints.entries()) {
+      if (ep.type === "reference") continue;
+      const originEpName = docker.entrypointNameToOrigin(epName);
+      if (result.has(originEpName)) continue;
+      result.set(originEpName, {
+        id: { package: this.pkgInfo.packageName, name: originEpName },
+        isDev: true,
+        binary: {
+          type: "binary",
+          registry: defaults.NO_SOFTWARE_PLACEHOLDER,
+          package: defaults.NO_SOFTWARE_PLACEHOLDER,
+          cmd: ["true"],
+        },
+      });
+    }
+    return result;
+  }
+
   public writeSwJson(info: swJson.swJsonType, dstFile?: string) {
     const epType = info.asset ? "asset" : "software";
     const dstSwInfoPath =
@@ -297,6 +322,7 @@ export class SwJsonRenderer {
   ): swJson.remoteSoftwareType | undefined {
     switch (mode) {
       case "release":
+      case "dev-remote":
         break;
 
       case "dev-local":
@@ -433,6 +459,7 @@ export class SwJsonRenderer {
   ): swJson.runEnvInfo | undefined {
     switch (mode) {
       case "release":
+      case "dev-remote":
         break;
 
       case "dev-local":
@@ -482,6 +509,7 @@ export class SwJsonRenderer {
   ): swJson.assetInfo | undefined {
     switch (mode) {
       case "release":
+      case "dev-remote":
         break;
 
       case "dev-local":

package/src/core/util.test.ts

@@ -0,0 +1,52 @@
+import { hashDirSync, shouldDoAction } from "./util";
+import { test, expect } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const digest = (root: string): string => hashDirSync(root).digest("hex");
+
+// Nested entries must hash under their full path from the root, otherwise distinct trees collide
+// and content-addressable dev naming would serve a stale artifact.
+test("hashDirSync distinguishes a nested file from a same-named root file", () => {
+  const a = fs.mkdtempSync(path.join(os.tmpdir(), "hash-a-"));
+  const b = fs.mkdtempSync(path.join(os.tmpdir(), "hash-b-"));
+  try {
+    // Tree A: an empty `dir/` plus a root `file`.
+    fs.mkdirSync(path.join(a, "dir"));
+    fs.writeFileSync(path.join(a, "file"), "x");
+
+    // Tree B: the same `file` (same contents) but nested inside `dir/`.
+    fs.mkdirSync(path.join(b, "dir"));
+    fs.writeFileSync(path.join(b, "dir", "file"), "x");
+
+    expect(digest(a)).not.toEqual(digest(b));
+  } finally {
+    fs.rmSync(a, { recursive: true, force: true });
+    fs.rmSync(b, { recursive: true, force: true });
+  }
+});
+
+test("hashDirSync is identical for identical trees at different locations", () => {
+  const a = fs.mkdtempSync(path.join(os.tmpdir(), "hash-a-"));
+  const b = fs.mkdtempSync(path.join(os.tmpdir(), "hash-b-"));
+  try {
+    for (const root of [a, b]) {
+      fs.mkdirSync(path.join(root, "dir"));
+      fs.writeFileSync(path.join(root, "dir", "nested"), "hello");
+      fs.writeFileSync(path.join(root, "top"), "world");
+    }
+    expect(digest(a)).toEqual(digest(b));
+  } finally {
+    fs.rmSync(a, { recursive: true, force: true });
+    fs.rmSync(b, { recursive: true, force: true });
+  }
+});
+
+test("shouldDoAction: disable wins over enable wins over the default", () => {
+  expect(shouldDoAction({ default: true })).toBe(true);
+  expect(shouldDoAction({ default: false })).toBe(false);
+  expect(shouldDoAction({ default: false, enable: true })).toBe(true);
+  expect(shouldDoAction({ default: true, disable: true })).toBe(false);
+  expect(shouldDoAction({ default: false, enable: true, disable: true })).toBe(false);
+});

package/src/core/util.ts

@@ -10,7 +10,7 @@ import * as envs from "./envs";
 export const packageJsonName = "package.json";
 export const softwareConfigName = "package.json";
 
-export function assertNever(_a: never) {
+export function assertNever(_a: never): never {
   throw new Error(`code logic error: assertNever() call for ${JSON.stringify(_a)}`);
 }
 
@@ -51,7 +51,10 @@ export function hashDirSync(rootDir: string, hasher?: Hash, subdir?: string): Ha
   const hash = hasher ? hasher : createHash("sha256");
   const folder = path.join(rootDir, subdir ?? ".");
 
-  const info = fs.readdirSync(folder, { withFileTypes: true });
+  // Sort for a host-independent hash: readdir enumeration order is not guaranteed.
+  const info = fs
+    .readdirSync(folder, { withFileTypes: true })
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 
   for (const item of info) {
     const relPath = path.join(subdir ?? ".", item.name);
@@ -70,7 +73,9 @@ export function hashDirSync(rootDir: string, hasher?: Hash, subdir?: string): Ha
 
       fs.closeSync(fileDescriptor);
     } else if (item.isDirectory()) {
-      hashDirSync(fullPath, hash);
+      // Keep rootDir fixed and pass the accumulated relPath so nested entries hash under their
+      // full path from the root — otherwise `dirA/` + `file` collides with `dirA/file`.
+      hashDirSync(rootDir, hash, relPath);
     }
   }
 
@@ -295,11 +300,26 @@ export function currentPlatform(): PlatformType {
 export const AllSoftwareSources = ["archive", "docker"] as const; // add 'image', '<whatever>' here when supported
 export type SoftwareSource = (typeof AllSoftwareSources)[number];
 
-export type BuildMode = "dev-local" | "release";
+export type BuildMode = "dev-local" | "dev-remote" | "release";
+
+export function isDevMode(mode: BuildMode): mode is "dev-local" | "dev-remote" {
+  return mode === "dev-local" || mode === "dev-remote";
+}
+
+export function producesRegistryDescriptor(mode: BuildMode): mode is "dev-remote" | "release" {
+  return mode === "dev-remote" || mode === "release";
+}
 
-/** True for dev-local build mode. */
-export function isDevLocalMode(mode: BuildMode): mode is "dev-local" {
-  return mode === "dev-local";
+// Resolve a `--do`/`--no-do` (or PL_*_/PL_*_NO_ env) tri-state: explicit disable wins, then enable,
+// else the default.
+export function shouldDoAction(opts: {
+  default: boolean;
+  enable?: boolean;
+  disable?: boolean;
+}): boolean {
+  if (opts.disable) return false;
+  if (opts.enable) return true;
+  return opts.default;
 }
 
 export type artifactID = {

package/src/defaults.ts

@@ -8,6 +8,14 @@
 export const BIN_REGISTRY_NAME = "platforma-open";
 export const BIN_REGISTRY_DOWNLOAD_URL = "https://bin.pl-open.science/";
 
+// Built-in dev binary registry name; flips to DEV_BIN_REGISTRY_NAME_OVERRIDDEN under PL_DEV_BINARY_UPLOAD_URL.
+export const DEV_BIN_REGISTRY_NAME = "midev";
+export const DEV_BIN_REGISTRY_NAME_OVERRIDDEN = "dev";
+
+// Built-in midev dev binary upload endpoint (zero-config dev push), the binary counterpart of
+// DEV_DOCKER_PUSH_TARGET. Override with PL_DEV_BINARY_UPLOAD_URL.
+export const DEV_BINARY_UPLOAD_TARGET = "s3://milab-midev-registry?region=eu-central-1";
+
 // Python
 export const PYTHON_TOOLSET = "pip";
 export const PYTHON_REQUIREMENTS_FILE = "requirements.txt";
@@ -27,9 +35,19 @@ export const DOCKER_REGISTRY = "containers.pl-open.science/milaboratories/pl-con
 export const DOCKER_DOCKERFILE = "Dockerfile"; // inside git repo: path to Dockerfile to build by default
 export const DOCKER_PLACEHOLDER_PKG = "/app"; // {pkg} placeholder value to by used in 'cmd' (for autogenerated docker images)
 
+// Sentinel registry/package name for placeholder descriptors, so an accidental execution fails
+// with a recognizable error instead of an opaque registry 404.
+export const NO_SOFTWARE_PLACEHOLDER = "no-software-placeholder";
+
 // Block-software dev pushes (pl-pkg build --dev=local) target this ECR by default.
 // Override per-run with --docker-registry / PL_DOCKER_REGISTRY.
-export const DEV_DOCKER_REGISTRY = "public.ecr.aws/u5p1x5q2/pl-containers";
+export const DEV_DOCKER_REGISTRY = "public.ecr.aws/miresearch/pl-containers";
+
+// ecr:// scheme requests automatic docker login; the pull address stays the bare registry.
+export const DEV_DOCKER_PUSH_TARGET = `ecr://${DEV_DOCKER_REGISTRY}`;
+
+// Fallback AWS SSO profile for dev push; override with PL_AWS_PROFILE or AWS_PROFILE.
+export const AWS_DEV_PROFILE = "research-poweruser";
 
 // All docker images are built for and pushed as linux/amd64, regardless of host arch.
 // Platforma's K8s nodes are linux/amd64; building for any other platform produces

package/src/index.ts

@@ -5,6 +5,9 @@ export * as util from "./core/util";
 export * as envs from "./core/envs";
 export * as defaults from "./defaults";
 
+/** The logger the engine and its callers pass around. */
+export type Logger = winston.Logger;
+
 /**
  * Public surface of the build engine. Derived from `Core` so signatures never
  * drift, while the `Core` class itself stays internal (per A-0023: the engine is
@@ -22,6 +25,7 @@ export type Builder = Pick<
   | "buildDockerImages"
   | "buildSoftwareArchives"
   | "buildSwJsonFiles"
+  | "writePublishedArtifactInfo"
   | "publishPackages"
   | "publishDockerImages"
 >;