@crewhaus/docker-images 0.1.8 → 0.2.0

package/dist/index.d.ts

@@ -15,6 +15,13 @@
  *     version` succeeding); injectable `runner` for tests.
  *   - `loadDigests()` / `recordDigest()` over a `docker/digests.json`
  *     lockfile so reproducible builds work offline.
+ *   - `resolveImageDigest()` + `buildImageAndRecord()` — item 47 closes the
+ *     digests.json loop: PUSHED builds record their registry manifest digest
+ *     (the only digest `docker pull repo@sha256:…` accepts), and the release
+ *     workflow records the pushed ghcr.io digests for each v* tag. A local
+ *     `--load` build records NOTHING — `docker image inspect`'s `.Id` is the
+ *     image CONFIG digest, which no registry can serve, so writing it into
+ *     the lockfile would hand users an unpullable pin.
  */
 import { CrewhausError } from "@crewhaus/errors";
 export declare class DockerImagesError extends CrewhausError {
@@ -70,6 +77,54 @@ export type DigestsFile = {
 };
 export declare function loadDigests(path?: string): DigestsFile;
 export declare function recordDigest(target: TargetShape, tag: string, sha256: string, path?: string): void;
+export type ResolveImageDigestOptions = {
+    readonly target: TargetShape;
+    readonly tag: string;
+    /** Test injection point — defaults to the same spawn runner as buildImage. */
+    readonly runner?: BuildRunner;
+};
+/**
+ * Resolve a PUSHED image's registry manifest digest via `docker buildx
+ * imagetools inspect`. Only the manifest digest is pullable
+ * (`docker pull repo@sha256:…`); the local image store's `.Id` is the image
+ * CONFIG digest, which registries do not serve — so there is deliberately no
+ * local-inspect fallback here (a `--load` build has no recordable digest).
+ */
+export declare function resolveImageDigest(opts: ResolveImageDigestOptions): Promise<string>;
+export type BuildImageAndRecordOptions = BuildImageOptions & {
+    /** Record the built image's digest into docker/digests.json. Default true. */
+    readonly record?: boolean;
+    /** Override the digests.json location (tests / CI checkouts). */
+    readonly digestsFile?: string;
+    /** Test injection point for the recording seam. Defaults to {@link recordDigest}. */
+    readonly recordDigestFn?: typeof recordDigest;
+};
+export type BuildImageAndRecordResult = BuildImageResult & {
+    /** Registry manifest digest of the pushed image; undefined when recording was skipped or failed. */
+    readonly digest?: string;
+    readonly recorded: boolean;
+    /** Why the digest was not recorded (set only when recording was requested but failed). */
+    readonly recordError?: string;
+    /**
+     * Set when recording was requested but is not applicable: a `--load` build
+     * only produces a local image whose ID is a CONFIG digest, not a pullable
+     * registry manifest digest, so nothing truthful can land in the lockfile.
+     */
+    readonly recordSkippedReason?: string;
+};
+/**
+ * `buildImage()` + close the digests.json loop: after a successful PUSHED
+ * build, resolve the image's registry manifest digest (`docker buildx
+ * imagetools inspect`) and record it in the lockfile — the maintenance the
+ * digests.json header always promised. `crewhaus build-image --push` calls
+ * this (recording is default-on there; `--no-record` opts out). A local
+ * `--load` build records NOTHING (see `recordSkippedReason`): its image ID is
+ * a config digest that `docker pull repo@sha256:…` cannot resolve, and the
+ * lockfile must only ever contain pullable pins. A digest-resolution/record
+ * failure does NOT fail the build — the image exists; the caller decides how
+ * loudly to surface the stale lockfile (the CLI prints a warning).
+ */
+export declare function buildImageAndRecord(opts: BuildImageAndRecordOptions): Promise<BuildImageAndRecordResult>;
 export type DockerfileFingerprint = {
     readonly stages: ReadonlyArray<{
         readonly image: string;

package/dist/index.js

@@ -18,6 +18,13 @@ import { fileURLToPath } from "node:url";
  *     version` succeeding); injectable `runner` for tests.
  *   - `loadDigests()` / `recordDigest()` over a `docker/digests.json`
  *     lockfile so reproducible builds work offline.
+ *   - `resolveImageDigest()` + `buildImageAndRecord()` — item 47 closes the
+ *     digests.json loop: PUSHED builds record their registry manifest digest
+ *     (the only digest `docker pull repo@sha256:…` accepts), and the release
+ *     workflow records the pushed ghcr.io digests for each v* tag. A local
+ *     `--load` build records NOTHING — `docker image inspect`'s `.Id` is the
+ *     image CONFIG digest, which no registry can serve, so writing it into
+ *     the lockfile would hand users an unpullable pin.
  */
 import { CrewhausError } from "@crewhaus/errors";
 export class DockerImagesError extends CrewhausError {
@@ -148,6 +155,66 @@ export function recordDigest(target, tag, sha256, path = DIGESTS_PATH) {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, `${JSON.stringify(current, null, 2)}\n`, { mode: 0o644 });
 }
+const SHA256_DIGEST_RE = /sha256:[0-9a-f]{64}/;
+/**
+ * Resolve a PUSHED image's registry manifest digest via `docker buildx
+ * imagetools inspect`. Only the manifest digest is pullable
+ * (`docker pull repo@sha256:…`); the local image store's `.Id` is the image
+ * CONFIG digest, which registries do not serve — so there is deliberately no
+ * local-inspect fallback here (a `--load` build has no recordable digest).
+ */
+export async function resolveImageDigest(opts) {
+    const ref = `crewhaus/${opts.target}:${opts.tag}`;
+    const argv = ["docker", "buildx", "imagetools", "inspect", ref];
+    const runner = opts.runner ?? defaultRunner;
+    const { exitCode, stdout, stderr } = await runner(argv, process.cwd());
+    if (exitCode !== 0) {
+        throw new DockerImagesError(`could not inspect ${ref} for its digest (exit ${exitCode}): ${stderr.slice(0, 512)}`);
+    }
+    const match = SHA256_DIGEST_RE.exec(stdout);
+    if (match === null) {
+        throw new DockerImagesError(`no sha256 digest in docker inspect output for ${ref}`);
+    }
+    return match[0];
+}
+/**
+ * `buildImage()` + close the digests.json loop: after a successful PUSHED
+ * build, resolve the image's registry manifest digest (`docker buildx
+ * imagetools inspect`) and record it in the lockfile — the maintenance the
+ * digests.json header always promised. `crewhaus build-image --push` calls
+ * this (recording is default-on there; `--no-record` opts out). A local
+ * `--load` build records NOTHING (see `recordSkippedReason`): its image ID is
+ * a config digest that `docker pull repo@sha256:…` cannot resolve, and the
+ * lockfile must only ever contain pullable pins. A digest-resolution/record
+ * failure does NOT fail the build — the image exists; the caller decides how
+ * loudly to surface the stale lockfile (the CLI prints a warning).
+ */
+export async function buildImageAndRecord(opts) {
+    const result = await buildImage(opts);
+    if (opts.record === false) {
+        return { ...result, recorded: false };
+    }
+    if (opts.push !== true) {
+        return {
+            ...result,
+            recorded: false,
+            recordSkippedReason: "local image ID is not a registry digest — use --push to record a pullable digest",
+        };
+    }
+    const record = opts.recordDigestFn ?? recordDigest;
+    try {
+        const digest = await resolveImageDigest({
+            target: opts.target,
+            tag: opts.tag,
+            runner: opts.runner,
+        });
+        record(opts.target, opts.tag, digest, opts.digestsFile);
+        return { ...result, digest, recorded: true };
+    }
+    catch (err) {
+        return { ...result, recorded: false, recordError: err.message };
+    }
+}
 export function fingerprintDockerfile(text) {
     const lines = text.split(/\r?\n/);
     const fromStages = lines

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/docker-images",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "type": "module",
   "description": "Per-target-shape Docker images (multi-stage, non-root, healthchecked) + crewhaus build-image CLI wrapper (Section 32)",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.8"
+    "@crewhaus/errors": "0.2.0"
   },
   "license": "Apache-2.0",
   "author": {