@fjall/util 0.96.0 → 0.99.3

package/dist/.minified

@@ -1 +1 @@
-21 files minified at 2026-04-27T00:08:06.074Z
+53 files minified at 2026-05-22T22:51:39.799Z

package/dist/Config.d.ts

@@ -43,7 +43,7 @@ export declare const RootConfigSchema: z.ZodObject<{
         account: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
-type RootConfig = z.infer<typeof RootConfigSchema>;
+export type RootConfig = z.infer<typeof RootConfigSchema>;
 /**
  * Config class for loading and saving the root fjall-config.json.
  * Single config file at fjall/fjall-config.json (or fjall-config.json at cwd).

package/dist/appPath.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Workspace-layout conventions shared by CLI, webapp, and worker code.
+ *
+ * The Fjall scaffolder writes application infrastructure under a `fjall/`
+ * boundary directory. The customer-chosen app name lives **inside** that
+ * boundary, not as a sibling of it. Two layouts are supported:
+ *
+ *   - Default (no container):   `fjall/<name>/infrastructure.ts`
+ *   - With container:           `<container>/fjall/<name>/infrastructure.ts`
+ *
+ * The `fjall/` segment is the codemod blast-radius boundary; the
+ * `--container` argument names the directory that sits between the repo
+ * root and the boundary. Two `fjall create app` calls with the same
+ * container value land as siblings inside one shared boundary (the T3
+ * multi-app shape), e.g.
+ *   `webapp/fjall/api/infrastructure.ts`
+ *   `webapp/fjall/worker/infrastructure.ts`
+ *
+ * Multiple producers (the register-application flow, the auto-link
+ * repository flow, the post-create linkage flow, the CLI `cd …` message
+ * strings) all derive this path from this helper — keeping it as inline
+ * template literals would invite silent CLI/webapp drift if the
+ * convention shifts.
+ *
+ * See `aiDocs/designs/2026-05-11-marker-as-boundary-not-identity.md` and
+ * `aiDocs/patterns/fjall-marker-convention-pattern.md` for the
+ * convention's full topology mapping.
+ */
+export declare function buildAppConfigPath(appName: string, container?: string): string;

package/dist/appPath.js

@@ -0,0 +1 @@
+function t(r,n){if(n!==void 0){if(n.trim()==="")throw new Error("buildAppConfigPath: container must be a non-empty string");return`${n}/fjall/${r}`}return`fjall/${r}`}export{t as buildAppConfigPath};

package/dist/constructMap.d.ts

@@ -8,20 +8,16 @@
  * When a new CDK construct is added, add one entry here.
  * When a new AWS resource type is added, nothing changes.
  */
-/** Manifest file name — single source of truth across CLI, deploy-core, and infrastructure. */
-export declare const FJALL_MANIFEST_FILENAME = "fjall-manifest.json";
-/** Current manifest schema version. Shared between CLI and infrastructure. */
-export declare const MANIFEST_SCHEMA_VERSION: 1;
+/**
+ * Manifest filename + schema version + ResourceMapEntry shape are re-exported
+ * from `./manifest/schemas` (the canonical home for manifest types — that
+ * module is pure and is safe to import from environments that must avoid `fs`,
+ * e.g. the generator).
+ */
+export { FJALL_MANIFEST_FILENAME, MANIFEST_SCHEMA_VERSION } from "./manifest/schemas.js";
+export type { ResourceMapEntry } from "./manifest/schemas.js";
+import type { ResourceMapEntry } from "./manifest/schemas.js";
 import type { ResourceCategory } from "./resourceCategorisation.js";
-/** Entry in the resource map — maps a logical ID to its construct context. */
-export interface ResourceMapEntry {
-    /** Full CDK construct path (e.g., "/Account/CloudTrail/managementEventsTrail/Resource") */
-    constructPath: string;
-    /** Topology group derived from the construct (e.g., "monitoring") */
-    group: string;
-    /** AWS resource type (e.g., "AWS::KMS::Key") */
-    resourceType: string;
-}
 /**
  * Account stack construct-to-group mapping.
  * Keys are CDK construct IDs (first segment after stack name in construct path).

package/dist/constructMap.js

@@ -1 +1 @@
-const R="fjall-manifest.json",S=1;import{readFileSync as p}from"fs";import{join as l}from"path";import{logger as g}from"./logger.js";import{categoriseResource as d,getFriendlyResourceType as y}from"./resourceCategorisation.js";const h=Object.freeze({CloudTrail:"monitoring",MonitoringRole:"monitoring",AuditRole:"security",OidcConnector:"security",EcrDefaultImage:"registry",EventBus:"events",DisasterRecovery:"backup"}),A=Object.freeze({Network:"network",Database:"database",Compute:"compute",Storage:"storage",Messaging:"events",Cdn:"dns"});function C(o,e){const t=o.split("/").filter(Boolean);if(t.length<2)return;const r=t[1];return e[r]}function T(o){const e=o.split("/").filter(Boolean);return e.length<2?o:(e.length>2&&e[e.length-1]==="Resource"?e[e.length-2]:e[e.length-1]).replace(/([a-z])([A-Z])/g,"$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g,"$1 $2")}function E(o,e){const t=new Map;let r;try{const n=p(l(o,"manifest.json"),"utf-8"),s=JSON.parse(n);if(typeof s!="object"||s===null)return t;r=s}catch(n){return g.debug("ConstructMap","Could not read CDK manifest",{error:n instanceof Error?n.message:String(n)}),t}if(!r.artifacts)return t;for(const n of Object.values(r.artifacts)){if(n.type!=="aws:cloudformation:stack"||!n.metadata)continue;const s=b(o,n.properties?.templateFile);for(const[a,c]of Object.entries(n.metadata))for(const i of c){if(i.type!=="aws:cdk:logicalId")continue;const u=i.data,f=s.get(u)??"",m=C(a,e)??d(f);t.set(u,{constructPath:a,group:m,resourceType:f})}}return t}function b(o,e){const t=new Map;if(!e)return t;try{const r=p(l(o,e),"utf-8"),n=JSON.parse(r);if(typeof n!="object"||n===null)return t;const s=n;if(s.Resources&&typeof s.Resources=="object")for(const[a,c]of Object.entries(s.Resources))typeof c=="object"&&c!==null&&c.Type&&t.set(a,c.Type)}catch(r){g.debug("ConstructMap","Could not read template file",{templateFile:e,error:r instanceof Error?r.message:String(r)})}return t}function v(o){const e={};for(const[t,r]of o)e[t]=r;return e}function x(o){const e=new Map;if(!o)return e;for(const[t,r]of Object.entries(o))e.set(t,r);return e}function I(o,e,t){const r=t?.get(o);return r?{group:r.group,constructPath:r.constructPath,displayName:T(r.constructPath)}:{displayName:y(e)}}export{h as ACCOUNT_CONSTRUCT_GROUPS,A as APP_CONSTRUCT_GROUPS,R as FJALL_MANIFEST_FILENAME,S as MANIFEST_SCHEMA_VERSION,E as buildConstructMap,v as constructMapToRecord,T as deriveDisplayName,C as deriveGroupFromPath,I as enrichFromConstructMap,x as recordToConstructMap};
+import{FJALL_MANIFEST_FILENAME as _,MANIFEST_SCHEMA_VERSION as w}from"./manifest/schemas.js";import{readFileSync as p}from"fs";import{join as l}from"path";import{logger as g}from"./logger.js";import{categoriseResource as d,getFriendlyResourceType as y}from"./resourceCategorisation.js";const N=Object.freeze({CloudTrail:"monitoring",MonitoringRole:"monitoring",AuditRole:"security",OidcConnector:"security",EcrDefaultImage:"registry",EventBus:"events",DisasterRecovery:"backup"}),h=Object.freeze({Network:"network",Database:"database",Compute:"compute",Storage:"storage",Messaging:"events",Cdn:"dns"});function C(o,e){const t=o.split("/").filter(Boolean);if(t.length<2)return;const r=t[1];return e[r]}function T(o){const e=o.split("/").filter(Boolean);return e.length<2?o:(e.length>2&&e[e.length-1]==="Resource"?e[e.length-2]:e[e.length-1]).replace(/([a-z])([A-Z])/g,"$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g,"$1 $2")}function j(o,e){const t=new Map;let r;try{const n=p(l(o,"manifest.json"),"utf-8"),s=JSON.parse(n);if(typeof s!="object"||s===null)return t;r=s}catch(n){return g.debug("ConstructMap","Could not read CDK manifest",{error:n instanceof Error?n.message:String(n)}),t}if(!r.artifacts)return t;for(const n of Object.values(r.artifacts)){if(n.type!=="aws:cloudformation:stack"||!n.metadata)continue;const s=b(o,n.properties?.templateFile);for(const[a,c]of Object.entries(n.metadata))for(const u of c){if(u.type!=="aws:cdk:logicalId")continue;const i=u.data,f=s.get(i)??"",m=C(a,e)??d(f);t.set(i,{constructPath:a,group:m,resourceType:f})}}return t}function b(o,e){const t=new Map;if(!e)return t;try{const r=p(l(o,e),"utf-8"),n=JSON.parse(r);if(typeof n!="object"||n===null)return t;const s=n;if(s.Resources&&typeof s.Resources=="object")for(const[a,c]of Object.entries(s.Resources))typeof c=="object"&&c!==null&&c.Type&&t.set(a,c.Type)}catch(r){g.debug("ConstructMap","Could not read template file",{templateFile:e,error:r instanceof Error?r.message:String(r)})}return t}function A(o){const e={};for(const[t,r]of o)e[t]=r;return e}function E(o){const e=new Map;if(!o)return e;for(const[t,r]of Object.entries(o))e.set(t,r);return e}function v(o,e,t){const r=t?.get(o);return r?{group:r.group,constructPath:r.constructPath,displayName:T(r.constructPath)}:{displayName:y(e)}}export{N as ACCOUNT_CONSTRUCT_GROUPS,h as APP_CONSTRUCT_GROUPS,_ as FJALL_MANIFEST_FILENAME,w as MANIFEST_SCHEMA_VERSION,j as buildConstructMap,A as constructMapToRecord,T as deriveDisplayName,C as deriveGroupFromPath,v as enrichFromConstructMap,E as recordToConstructMap};

package/dist/deriveContentHashTag.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Domain helper: derive a content-addressed image tag from a buildx digest.
+ *
+ * Returns a tag of the shape `<serviceName>(-<target>)?-sha-<prefix>` where
+ * `prefix` is the first 12 lowercase-hex characters of the digest's sha256
+ * payload. The helper is the SOLE source of truth for content-hash tag
+ * synthesis — every producer (`@fjall/cli` `EcrBuildOrchestrator`,
+ * `@fjall/deploy-core` `dockerBuildHelper`) routes through it so a change
+ * to the format propagates without per-call-site drift.
+ *
+ * Rejection cases:
+ *   - digest not prefixed with `sha256:` (we never call other algorithms)
+ *   - digest hex payload shorter than 12 chars
+ *   - serviceName empty or whitespace-only
+ *   - target supplied as whitespace-only (caller would typically omit it
+ *     entirely; `""` is treated as "no target", surfaced via a failure so
+ *     the caller cannot pass through an upstream-empty value silently)
+ *
+ * The Result type below is structurally identical to the canonical
+ * `Result<T, E>` in `@fjall/generator/src/types/Result.ts`. `@fjall/util` is
+ * the root of the workspace dep graph, so we cannot import the canonical
+ * shape without creating a circular dependency. Consumers in
+ * `@fjall/deploy-core` and `@fjall/cli` consume values produced here and
+ * pass them through to canonical-`Result` consumers — structural identity
+ * means TS catches drift if the canonical shape ever changes.
+ */
+export type Result<T, E = Error> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: E;
+};
+export declare function deriveContentHashTag(digest: string, serviceName: string, target?: string): Result<string, Error>;

package/dist/deriveContentHashTag.js

@@ -0,0 +1 @@
+function d(e){return{success:!0,data:e}}function t(e){return{success:!1,error:e}}const a="sha256:",o=12;function f(e,u,i){if(!e.startsWith(a))return t(new Error(`expected sha256:... digest, got ${e.slice(0,32)}`));const r=e.slice(a.length);if(r.length<o)return t(new Error(`digest hex payload too short (need >=${o} chars, got ${r.length})`));const n=u.trim();if(n==="")return t(new Error("serviceName must be a non-empty string"));let s;if(i!==void 0){const c=i.trim();if(c==="")return t(new Error("target, when supplied, must be a non-empty string; omit the argument instead"));s=c.toLowerCase()}const h=r.slice(0,o).toLowerCase(),m=s!==void 0?`${n.toLowerCase()}-${s}`:n.toLowerCase();return d(`${m}-sha-${h}`)}export{f as deriveContentHashTag};

package/dist/docker/DockerCli.build.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Build-related implementations for `DockerCli`.
+ *
+ * `_buildxBuild` validates the args via `BuildxBuildArgsSchema.safeParse()`
+ * (Pitfall 4 — never `.parse()` inside a `Result`-returning function),
+ * spawns `docker buildx build` with the argv from the pure builder,
+ * line-buffers `--progress=rawjson` stdout into the rawjson parser, fires
+ * `onProgress` events through the masking boundary, then reads the
+ * `--metadata-file` for `containerimage.digest` to assemble the
+ * `BuildxBuildResult`.
+ *
+ * Resource discipline (per AC12 + robustness-standards § "Resource
+ * Acquisition Inside `try`"): the `--metadata-file` path is treated as a
+ * caller-owned-but-DockerCli-cleaned resource. `let
+ * tempMetadataPathForCleanup: string | undefined` outside the `try`,
+ * captured inside, removed via `rm(..., { force: true }).catch(...)` in
+ * `finally`. The `force: true` flag also short-circuits a missing-file
+ * cleanup which is the common case for failed-build paths where buildx
+ * never wrote the file.
+ */
+import { type BuildxBuildArgs, type BuildxBuildResult, type DockerCliError } from "./dockerCliSchemas.js";
+import { type BuildxProgressEvent, type DockerCliState, type ImagetoolsInspect, type Result } from "./DockerCli.js";
+export declare function _buildxBuild(state: DockerCliState, args: BuildxBuildArgs, onProgress: (event: BuildxProgressEvent) => void): Promise<Result<BuildxBuildResult, DockerCliError>>;
+/**
+ * Create one or more manifest-list tags pointing at an existing image
+ * digest without re-uploading layers.
+ *
+ * Implementation: `docker buildx imagetools create --tag <tag1> --tag
+ * <tag2> ... <sourceImage>@<digest>`. The source `image@digest` reference
+ * pins the immutable content; each `--tag` argument creates (or moves) a
+ * mutable name pointing at that digest. The registry stores no new blobs,
+ * only a new manifest reference per tag.
+ *
+ * Discipline:
+ *   - argv-only spawn (`shell: false` via `runDocker`)
+ *   - tag values are validated to be non-empty strings before they enter argv
+ *   - stderr is masked and bounded by `makeError(... stderrTail)`
+ *   - timeout: re-uses `DEFAULT_INSPECT_TIMEOUT_MS`; imagetools create is a
+ *     manifest-only operation comparable to inspect in latency
+ */
+export declare function _tagByDigest(state: DockerCliState, sourceImage: string, digest: string, tags: readonly string[]): Promise<Result<void, DockerCliError>>;
+export declare function _imagetoolsInspect(state: DockerCliState, image: string): Promise<Result<ImagetoolsInspect, DockerCliError>>;

package/dist/docker/DockerCli.build.js

@@ -0,0 +1 @@
+import{rm as C}from"node:fs/promises";import{buildxArgvBuilder as D}from"./buildxArgvBuilder.js";import{BuildxBuildArgsSchema as k}from"./dockerCliSchemas.js";import{DEFAULT_BUILD_TIMEOUT_MS as $,DEFAULT_INSPECT_TIMEOUT_MS as w,DOCKER_CLI_BUILDX_LOG_CATEGORY as T}from"./dockerCliConstants.js";import{parseMetadataFile as B}from"./metadataFileParser.js";import{parseRawjsonLine as M}from"./rawjsonParser.js";import{rawjsonToVertexEvent as S}from"./rawjsonToVertexEvent.js";import{maskSensitiveOutput as x}from"../securityHelpers.js";import{failure as i,makeError as s,maskOutput as b,runDocker as _,spawnFailureToError as F,streamDocker as I,success as v}from"./DockerCli.js";function h(o){return o instanceof Error?o.message:String(o)}async function H(o,u,t){const r=k.safeParse(u);if(!r.success){const a=x(r.error.message);return i(s("validation",`Invalid BuildxBuildArgs: ${a}`,{issues:r.error.issues}))}const l=D(r.data);let n=0,g=0;const d=new Set,f=a=>{const m=M(a);if(m===null){a.trim()!==""&&o.logger.debug(T,"Skipping malformed rawjson line",{line:x(a)});return}const c=S(m);if(c!==null){for(const e of c.vertexes)e.completed!==void 0&&!d.has(e.digest)&&(d.add(e.digest),e.cached===!0?n++:g++),t({type:"vertex",message:b(e.name),vertex:e.digest});for(const e of c.logs)t({type:"log",message:b(e.data),vertex:e.vertex});for(const e of c.statuses)t({type:"status",message:b(`${e.name} ${e.current}`),vertex:e.vertex});for(const e of c.warnings)t({type:"warning",message:b(e.short),vertex:e.vertex})}};let p;try{p=r.data.metadataFile;const a=await I(o,{args:l,timeoutMs:$},f);if(a.spawnError!==void 0)return i(s("daemon_unreachable",`Docker CLI is not available: ${a.spawnError}`,{stderrTail:a.stderrTail}));if(a.aborted||a.exitCode===null)return i(s("abort","docker buildx build was aborted",{stderrTail:a.stderrTail}));if(a.exitCode!==0)return i(s("build_failed",`docker buildx build failed (exit ${a.exitCode})`,{stderrTail:a.stderrTail}));const m=await B(r.data.metadataFile);if(!m.success)return m;const c=m.data,e=c["containerimage.digest"];if(typeof e!="string"||e==="")return i(s("metadata_missing_digest","Buildx metadata file does not contain containerimage.digest",{metadataFile:r.data.metadataFile}));const y={};for(const E of r.data.tags)y[E]=e;return v({imageDigests:y,metadata:c,platforms:r.data.platforms,cacheHits:n,cacheMisses:g})}finally{p!==void 0&&await C(p,{force:!0}).catch(a=>{o.logger.warn(T,"Failed to clean up buildx metadata file",{path:p,error:x(h(a))})})}}async function K(o,u,t,r){if(u.trim()==="")return i(s("validation","tagByDigest: sourceImage must be non-empty"));if(!t.startsWith("sha256:"))return i(s("validation",`tagByDigest: expected sha256:... digest, got ${t.slice(0,32)}`));if(r.length===0)return i(s("validation","tagByDigest: tags must be a non-empty list"));for(const f of r)if(typeof f!="string"||f.trim()==="")return i(s("validation","tagByDigest: every tag must be non-empty"));const l=`${u}@${t}`,n=[];for(const f of r)n.push("--tag",f);const g=["buildx","imagetools","create",...n,l],d=await _(o,{args:g,timeoutMs:w});return d.spawnError!==void 0?i(F(d)):d.exitCode===null?i(s("abort",`docker buildx imagetools create for ${l} was aborted`,{stderrTail:d.stderrTail})):d.exitCode!==0?i(s("tag_failed",`docker buildx imagetools create for ${l} failed (exit ${d.exitCode})`,{stderrTail:d.stderrTail})):v(void 0)}async function V(o,u){const t=await _(o,{args:["buildx","imagetools","inspect",u,"--raw"],timeoutMs:w});if(t.spawnError!==void 0)return i(s("daemon_unreachable",`Docker CLI is not available: ${t.spawnError}`,{stderrTail:t.stderrTail}));if(t.exitCode===null)return i(s("abort",`docker buildx imagetools inspect ${u} was aborted`,{stderrTail:t.stderrTail}));if(t.exitCode!==0)return i(s("inspect_failed",`docker buildx imagetools inspect ${u} failed (exit ${t.exitCode})`,{stderrTail:t.stderrTail}));let r,l;try{const n=JSON.parse(t.stdout);typeof n.mediaType=="string"&&(r=n.mediaType),typeof n.digest=="string"&&(l=n.digest)}catch(n){o.logger.debug(T,"imagetools inspect output is not JSON; preserving raw",{error:x(h(n))})}return v({raw:t.stdout,...r!==void 0&&{mediaType:r},...l!==void 0&&{digest:l}})}export{H as _buildxBuild,V as _imagetoolsInspect,K as _tagByDigest};

package/dist/docker/DockerCli.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Concrete `DockerCli` class — wraps `docker` and `docker buildx` subprocess
+ * calls behind a typed interface. The class itself is thin: it carries shared
+ * state (logger, env, dockerBin, abort signal) and delegates each method to a
+ * pure-ish free function in a sibling file (`DockerCli.build.ts`,
+ * `DockerCli.registry.ts`, `DockerCli.daemon.ts`).
+ *
+ * Splitting was mandated by the plan's AC12 (each file < ~300 lines, one
+ * cohesion zone per file: build, registry, daemon).
+ *
+ * Subprocess discipline (every spawn call):
+ *   - `shell: false`
+ *   - `env` is `filterDangerousEnvVars(process.env)` plus any caller overrides
+ *   - `onProgress` events are masked via `maskSensitiveOutput()` once at the
+ *     boundary BEFORE the consumer callback fires
+ *   - abort routed through `abortChildProcess()` from `./abortHelpers.js`
+ *   - cleanup-side awaits in `finally` are wrapped with `.catch(...)` so
+ *     cleanup failures cannot replace the operation result
+ */
+import { type ChildProcess } from "node:child_process";
+import type { BuildxBuildArgs, BuildxBuildResult, DockerCliError, DockerCliErrorKind } from "./dockerCliSchemas.js";
+import { failure, success, type Result } from "./result.js";
+export interface DockerCliLogger {
+    debug(category: string, message: string, data?: Record<string, unknown>): void;
+    info(category: string, message: string, data?: Record<string, unknown>): void;
+    warn(category: string, message: string, data?: Record<string, unknown>): void;
+    error(category: string, message: string, data?: Record<string, unknown>): void;
+}
+export interface DockerCliOptions {
+    readonly logger: DockerCliLogger;
+    readonly dockerBin?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly abortSignal?: AbortSignal;
+}
+export interface DockerCliState {
+    readonly logger: DockerCliLogger;
+    readonly dockerBin: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly abortSignal: AbortSignal | undefined;
+}
+export interface BuildxProgressEvent {
+    readonly type: "vertex" | "log" | "status" | "warning";
+    readonly message: string;
+    readonly vertex?: string;
+}
+export interface PushProgressEvent {
+    readonly id: string;
+    readonly status: string;
+    readonly current?: number;
+    readonly total?: number;
+}
+export interface PushResult {
+    readonly digest: string;
+}
+export interface PullProgressEvent {
+    readonly id: string;
+    readonly status: string;
+    readonly current?: number;
+    readonly total?: number;
+}
+export interface PullResult {
+    readonly imageId: string;
+}
+export interface ImagetoolsInspect {
+    readonly raw: string;
+    readonly mediaType?: string;
+    readonly digest?: string;
+}
+export interface EcrLoginArgs {
+    readonly registry: string;
+    readonly username: string;
+    readonly password: string;
+}
+export interface BuildxCapabilities {
+    readonly version: string;
+}
+export interface DaemonInfo {
+    readonly serverName: string;
+    readonly serverVersion: string;
+}
+export declare class DockerCli {
+    private readonly state;
+    constructor(opts: DockerCliOptions);
+    buildxBuild(args: BuildxBuildArgs, onProgress: (event: BuildxProgressEvent) => void): Promise<Result<BuildxBuildResult, DockerCliError>>;
+    tag(source: string, target: string): Promise<Result<void, DockerCliError>>;
+    /**
+     * Create one or more manifest-list tags pointing at a previously pushed
+     * digest without re-uploading layers. Uses `docker buildx imagetools
+     * create` against `<sourceImage>@<digest>`.
+     */
+    tagByDigest(sourceImage: string, digest: string, tags: readonly string[]): Promise<Result<void, DockerCliError>>;
+    push(image: string, onProgress?: (event: PushProgressEvent) => void): Promise<Result<PushResult, DockerCliError>>;
+    pull(image: string, platform?: string, onProgress?: (event: PullProgressEvent) => void): Promise<Result<PullResult, DockerCliError>>;
+    imageInspect(image: string): Promise<Result<{
+        exists: boolean;
+        digest?: string;
+    }, DockerCliError>>;
+    imagetoolsInspect(image: string): Promise<Result<ImagetoolsInspect, DockerCliError>>;
+    loginEcr(args: EcrLoginArgs): Promise<Result<void, DockerCliError>>;
+    ensureBuilder(name: string): Promise<Result<{
+        created: boolean;
+    }, DockerCliError>>;
+    assertBuildxAvailable(): Promise<Result<BuildxCapabilities, DockerCliError>>;
+    detectDaemon(): Promise<Result<DaemonInfo, DockerCliError>>;
+}
+export interface SpawnDockerOptions {
+    readonly args: readonly string[];
+    readonly stdin?: string;
+    readonly timeoutMs?: number;
+}
+export interface SpawnDockerResult {
+    readonly exitCode: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly stderrTail: readonly string[];
+    readonly aborted: boolean;
+    readonly spawnError?: string;
+}
+export declare function makeError(kind: DockerCliErrorKind, message: string, details?: Record<string, unknown>): DockerCliError;
+export declare function spawnFailureToError(result: {
+    spawnError?: string;
+    stderrTail: readonly string[];
+}): DockerCliError;
+export declare function tailLines(buffer: string, count: number): string[];
+export declare function maskOutput(value: string): string;
+export declare function runDocker(state: DockerCliState, opts: SpawnDockerOptions): Promise<SpawnDockerResult>;
+export declare function streamDocker(state: DockerCliState, opts: SpawnDockerOptions, onStdoutLine: (line: string) => void, onStderrLine?: (line: string) => void): Promise<{
+    exitCode: number | null;
+    stderrTail: readonly string[];
+    aborted: boolean;
+    spawnError?: string;
+    child: ChildProcess | null;
+}>;
+export { failure, success };
+export type { Result };

package/dist/docker/DockerCli.daemon.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Daemon + builder bootstrap implementations for `DockerCli`.
+ *
+ * `assertBuildxAvailable` reads `docker buildx version` stdout and rejects
+ * any version below `BUILDX_VERSION_FLOOR`. The error path distinguishes
+ * "buildx plugin missing" (engine present, plugin exit 127) from
+ * "docker daemon unreachable" (engine command itself fails) so the
+ * surface error message can offer a targeted install hint.
+ *
+ * `detectDaemon` runs `docker version --format json` and surfaces the
+ * server name; Podman returns `Podman Engine` and is rejected fail-fast
+ * with `kind: "buildx_unavailable"`.
+ *
+ * `ensureBuilder` checks for the named buildx builder and creates it on
+ * absence. A wrong-driver builder (`docker` instead of `docker-container`)
+ * is removed and re-created; consumer is logged a warning.
+ */
+import type { DockerCliError } from "./dockerCliSchemas.js";
+import { type BuildxCapabilities, type DaemonInfo, type DockerCliState, type Result } from "./DockerCli.js";
+export declare function _assertBuildxAvailable(state: DockerCliState): Promise<Result<BuildxCapabilities, DockerCliError>>;
+export declare function _detectDaemon(state: DockerCliState): Promise<Result<DaemonInfo, DockerCliError>>;
+export declare function _ensureBuilder(state: DockerCliState, name: string): Promise<Result<{
+    created: boolean;
+}, DockerCliError>>;

package/dist/docker/DockerCli.daemon.js

@@ -0,0 +1 @@
+import{maskSensitiveOutput as p}from"../securityHelpers.js";import{BUILDX_VERSION_FLOOR as l,DEFAULT_DAEMON_PROBE_TIMEOUT_MS as x,DEFAULT_INSPECT_TIMEOUT_MS as c,DOCKER_CLI_BUILDX_LOG_CATEGORY as _,DOCKER_CLI_LOG_CATEGORY as g}from"./dockerCliConstants.js";import{failure as t,makeError as u,runDocker as s,spawnFailureToError as d,success as b}from"./DockerCli.js";function v(n){const e=n.startsWith("v")?n.slice(1):n,r=/^(\d+)\.(\d+)\.(\d+)/.exec(e);return r===null?null:[parseInt(r[1]??"0",10),parseInt(r[2]??"0",10),parseInt(r[3]??"0",10)]}function T(n,e){for(let r=0;r<3;r++){const i=n[r]??0,o=e[r]??0;if(i!==o)return i-o}return 0}function E(n){const e=/github\.com\/docker\/buildx\s+(v?\d+\.\d+\.\d+)/.exec(n);return e!==null&&e[1]!==void 0?e[1]:/(\d+\.\d+\.\d+)/.exec(n)?.[1]??null}async function O(n){const e=await s(n,{args:["buildx","version"],timeoutMs:c});if(e.spawnError!==void 0)return t(d(e));if(e.exitCode===null)return t(u("abort","docker buildx version was aborted",{stderrTail:e.stderrTail}));if(e.exitCode!==0){const a=await s(n,{args:["version","--format","{{.Server.Version}}"],timeoutMs:x});return a.spawnError!==void 0?t(d(a)):a.exitCode!==0?t(u("daemon_unreachable","Docker daemon is not running or not installed",{stderrTail:a.stderrTail})):t(u("buildx_unavailable",`Docker Buildx plugin is not installed (need >= ${l})`,{stderrTail:e.stderrTail}))}const r=E(e.stdout);if(r===null)return t(u("buildx_unavailable","Could not parse docker buildx version output",{stdout:e.stdout}));const i=v(r),o=v(l);return i===null||o===null?t(u("buildx_unavailable",`Could not parse buildx version "${r}"`,{stdout:e.stdout})):T(i,o)<0?t(u("buildx_unavailable",`Docker Buildx ${r} is below the required ${l} floor`,{observed:r,floor:l})):(n.logger.debug(_,"buildx available",{version:r}),b({version:r}))}async function D(n){const e=await s(n,{args:["version","--format","json"],timeoutMs:x});if(e.spawnError!==void 0)return t(d(e));if(e.exitCode===null)return t(u("abort","docker version was aborted",{stderrTail:e.stderrTail}));if(e.exitCode!==0)return t(u("daemon_unreachable","Docker daemon is not running or not installed",{stderrTail:e.stderrTail}));let r;try{r=JSON.parse(e.stdout)}catch(f){const m=p(f instanceof Error?f.message:String(f));return t(u("daemon_unreachable",`docker version output is not valid JSON: ${m}`,{stdout:e.stdout}))}if(r===null||typeof r!="object")return t(u("daemon_unreachable","docker version did not return a JSON object"));const i=r,o=i.Server?.Name??"Docker",a=i.Server?.Version??"unknown";return o==="Podman Engine"?t(u("buildx_unavailable","Podman is not supported; install Docker Engine 23+ with the buildx plugin")):b({serverName:o,serverVersion:a})}async function S(n,e){const r=await s(n,{args:["buildx","inspect",e],timeoutMs:c});if(r.spawnError!==void 0)return t(d(r));if(r.exitCode===0){if(/Driver:\s*docker-container/.test(r.stdout))return b({created:!1});n.logger.warn(g,"Replacing buildx builder with wrong driver",{name:e});const o=await s(n,{args:["buildx","rm",e],timeoutMs:c});if(o.spawnError!==void 0)return t(d(o));if(o.exitCode!==0)return t(u("buildx_unavailable",`Failed to remove existing buildx builder ${e}`,{stderrTail:o.stderrTail}))}const i=await s(n,{args:["buildx","create","--name",e,"--driver","docker-container","--use"],timeoutMs:c});return i.spawnError!==void 0?t(d(i)):i.exitCode!==0?t(u("buildx_unavailable",`Failed to create buildx builder ${e}`,{stderrTail:i.stderrTail})):b({created:!0})}export{O as _assertBuildxAvailable,D as _detectDaemon,S as _ensureBuilder};

package/dist/docker/DockerCli.js

@@ -0,0 +1 @@
+import{spawn as b}from"node:child_process";import{filterDangerousEnvVars as B,maskSensitiveOutput as E}from"../securityHelpers.js";import{abortChildProcess as h}from"./abortHelpers.js";import{DEFAULT_DOCKER_BIN as k,DOCKER_CLI_LOG_CATEGORY as A,STDERR_TAIL_LINE_MAX_CHARS as y,STDERR_TAIL_LINES as _}from"./dockerCliConstants.js";import{_buildxBuild as x,_imagetoolsInspect as D,_tagByDigest as w}from"./DockerCli.build.js";import{_assertBuildxAvailable as C,_detectDaemon as I,_ensureBuilder as L}from"./DockerCli.daemon.js";import{_imageInspect as R,_loginEcr as O,_pull as P,_push as N,_tag as F}from"./DockerCli.registry.js";import{failure as G,success as K}from"./result.js";class M{state;constructor(e){const r=e.dockerBin!==void 0&&e.dockerBin!==""?e.dockerBin:k,n=B(e.env??process.env);this.state={logger:e.logger,dockerBin:r,env:n,abortSignal:e.abortSignal}}async buildxBuild(e,r){return x(this.state,e,r)}async tag(e,r){return F(this.state,e,r)}async tagByDigest(e,r,n){return w(this.state,e,r,n)}async push(e,r){return N(this.state,e,r)}async pull(e,r,n){return P(this.state,e,r,n)}async imageInspect(e){return R(this.state,e)}async imagetoolsInspect(e){return D(this.state,e)}async loginEcr(e){return O(this.state,e)}async ensureBuilder(e){return L(this.state,e)}async assertBuildxAvailable(){return C(this.state)}async detectDaemon(){return I(this.state)}}function j(t){const e=E(t);return e.length>y?e.slice(0,y)+"\u2026":e}function H(t,e,r){let n,l=r;if(r!==void 0&&Array.isArray(r.stderrTail)&&r.stderrTail.every(o=>typeof o=="string")){n=r.stderrTail.map(j);const{stderrTail:o,...s}=r;l=Object.keys(s).length>0?s:void 0}return{kind:t,message:e,...n!==void 0&&{stderrTail:n},...l!==void 0&&{details:l}}}function Q(t){return H("daemon_unreachable",`Docker CLI is not available: ${t.spawnError??"unknown spawn failure"}`,{stderrTail:t.stderrTail})}function v(t,e){if(t==="")return[];const r=t.split(/\r?\n/);for(;r.length>0&&r[r.length-1]==="";)r.pop();return r.slice(-e)}function W(t){return E(t)}function Z(t,e){return new Promise(r=>{let n=!1,l=!1;const o=T(t.abortSignal,e.timeoutMs);let s;try{s=b(t.dockerBin,e.args,{shell:!1,env:t.env})}catch(i){const a=i instanceof Error?i.message:String(i);r({exitCode:null,stdout:"",stderr:a,stderrTail:[a],aborted:!1,spawnError:a});return}let c="",u="";s.stdout?.on("data",i=>{c+=i.toString()}),s.stderr?.on("data",i=>{u+=i.toString()}),e.stdin!==void 0&&(s.stdin?.on("error",i=>{t.logger.debug(A,"stdin write error (typically EPIPE on early child exit)",{error:i.message})}),s.stdin?.write(e.stdin),s.stdin?.end());const g=()=>{n=!0,h(s)};o!==void 0&&(o.aborted?g():o.addEventListener("abort",g,{once:!0})),s.once("error",i=>{if(l)return;l=!0,o!==void 0&&o.removeEventListener("abort",g);const a=i instanceof Error?i.message:String(i);r({exitCode:null,stdout:c,stderr:a,stderrTail:[a],aborted:n,spawnError:a})}),s.once("close",i=>{l||(l=!0,o!==void 0&&o.removeEventListener("abort",g),r({exitCode:i,stdout:c,stderr:u,stderrTail:v(u,_),aborted:n}))})})}function ee(t,e,r,n){return new Promise(l=>{let o=!1,s=!1;const c=T(t.abortSignal,e.timeoutMs);let u;try{u=b(t.dockerBin,e.args,{shell:!1,env:t.env})}catch(d){const f=d instanceof Error?d.message:String(d);l({exitCode:null,stderrTail:[f],aborted:!1,spawnError:f,child:null});return}let g="",i="",a="";u.stdout?.on("data",d=>{g+=d.toString();const f=g.split(/\r?\n/);g=f.pop()??"";for(const p of f)r(p)}),u.stderr?.on("data",d=>{const f=d.toString();if(i+=f,n!==void 0){a+=f;const p=a.split(/\r?\n/);a=p.pop()??"";for(const S of p)n(S)}});const m=()=>{o=!0,h(u)};c!==void 0&&(c.aborted?m():c.addEventListener("abort",m,{once:!0})),u.once("error",d=>{if(s)return;s=!0,c!==void 0&&c.removeEventListener("abort",m);const f=d instanceof Error?d.message:String(d);l({exitCode:null,stderrTail:[f],aborted:o,spawnError:f,child:u})}),u.once("close",d=>{s||(s=!0,g!==""&&r(g),n!==void 0&&a!==""&&n(a),c!==void 0&&c.removeEventListener("abort",m),l({exitCode:d,stderrTail:v(i,_),aborted:o,child:u}))})})}function T(t,e){if(!(t===void 0&&e===void 0))return t===void 0?AbortSignal.timeout(e):e===void 0?t:AbortSignal.any([t,AbortSignal.timeout(e)])}export{M as DockerCli,G as failure,H as makeError,W as maskOutput,Z as runDocker,Q as spawnFailureToError,ee as streamDocker,K as success,v as tailLines};

package/dist/docker/DockerCli.registry.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Registry-related implementations for `DockerCli`.
+ *
+ * `loginEcr` shells `docker login --username <u> --password-stdin <registry>`
+ * with the password sent on stdin so it never appears in argv (visible via
+ * `ps`). `imageInspect` distinguishes "image not found" (kind:inspect_failed
+ * with `exists: false`) from other inspect failures by sniffing the
+ * stderr tail for the literal `No such image:` substring docker emits.
+ */
+import type { DockerCliError } from "./dockerCliSchemas.js";
+import { type DockerCliState, type EcrLoginArgs, type PullProgressEvent, type PullResult, type PushProgressEvent, type PushResult, type Result } from "./DockerCli.js";
+export declare function _tag(state: DockerCliState, source: string, target: string): Promise<Result<void, DockerCliError>>;
+export declare function _push(state: DockerCliState, image: string, onProgress?: (event: PushProgressEvent) => void): Promise<Result<PushResult, DockerCliError>>;
+export declare function _pull(state: DockerCliState, image: string, platform?: string, onProgress?: (event: PullProgressEvent) => void): Promise<Result<PullResult, DockerCliError>>;
+export declare function _imageInspect(state: DockerCliState, image: string): Promise<Result<{
+    exists: boolean;
+    digest?: string;
+}, DockerCliError>>;
+export declare function _loginEcr(state: DockerCliState, args: EcrLoginArgs): Promise<Result<void, DockerCliError>>;

package/dist/docker/DockerCli.registry.js

@@ -0,0 +1,3 @@
+import{maskSensitiveOutput as h}from"../securityHelpers.js";import{DEFAULT_DAEMON_PROBE_TIMEOUT_MS as E,DEFAULT_INSPECT_TIMEOUT_MS as x,DEFAULT_PULL_TIMEOUT_MS as w,DEFAULT_PUSH_TIMEOUT_MS as C,DOCKER_CLI_LOG_CATEGORY as $}from"./dockerCliConstants.js";import{failure as i,makeError as a,maskOutput as _,runDocker as T,spawnFailureToError as c,streamDocker as g,success as u}from"./DockerCli.js";async function M(o,r,e){const t=await T(o,{args:["tag",r,e],timeoutMs:x});return t.spawnError!==void 0?i(c(t)):t.exitCode===null?i(a("abort",`docker tag ${r} ${e} was aborted`,{stderrTail:t.stderrTail})):t.exitCode!==0?i(a("tag_failed",`docker tag ${r} ${e} failed (exit ${t.exitCode})`,{stderrTail:t.stderrTail})):u(void 0)}async function D(o,r,e){let t;const d=await g(o,{args:["push",r],timeoutMs:C},f=>{if(f==="")return;let s;try{s=JSON.parse(f)}catch{o.logger.debug($,"Skipping malformed push progress line",{line:h(f)});return}if(s===null||typeof s!="object")return;const n=s;n.aux?.digest!==void 0&&(t=n.aux.digest),e!==void 0&&n.id!==void 0&&n.status!==void 0&&e({id:n.id,status:_(n.status),...n.progressDetail?.current!==void 0&&{current:n.progressDetail.current},...n.progressDetail?.total!==void 0&&{total:n.progressDetail.total}})});return d.spawnError!==void 0?i(c(d)):d.aborted||d.exitCode===null?i(a("abort",`docker push ${r} was aborted`,{stderrTail:d.stderrTail})):d.exitCode!==0?d.stderrTail.join(`
+`).toLowerCase().includes("unauthorized")?i(a("auth_failed",`docker push ${r} unauthorized`,{stderrTail:d.stderrTail})):i(a("push_failed",`docker push ${r} failed (exit ${d.exitCode})`,{stderrTail:d.stderrTail})):t===void 0?i(a("push_failed",`docker push ${r} succeeded but no digest was reported`,{stderrTail:d.stderrTail})):u({digest:t})}async function L(o,r,e,t){const l=["pull"];e!==void 0&&e!==""&&l.push("--platform",e),l.push(r);let d="";const s=await g(o,{args:l,timeoutMs:w},p=>{d+=`${p}
+`,!(t===void 0||p==="")&&t({id:r,status:_(p)})});if(s.spawnError!==void 0)return i(c(s));if(s.aborted||s.exitCode===null)return i(a("abort",`docker pull ${r} was aborted`,{stderrTail:s.stderrTail}));if(s.exitCode!==0)return i(a("pull_failed",`docker pull ${r} failed (exit ${s.exitCode})`,{stderrTail:s.stderrTail}));const n=/sha256:[0-9a-f]{64}/.exec(d);return u({imageId:n?.[0]??r})}async function O(o,r){const e=await T(o,{args:["image","inspect","--format","{{json .}}",r],timeoutMs:x});if(e.spawnError!==void 0)return i(c(e));if(e.exitCode===null)return i(a("abort",`docker image inspect ${r} was aborted`,{stderrTail:e.stderrTail}));if(e.exitCode!==0)return e.stderr.includes("No such image:")?u({exists:!1}):i(a("inspect_failed",`docker image inspect ${r} failed (exit ${e.exitCode})`,{stderrTail:e.stderrTail}));const t=/"Id":"(sha256:[0-9a-f]{64})"/.exec(e.stdout);return u({exists:!0,...t?.[1]!==void 0&&{digest:t[1]}})}async function y(o,r){const e=await T(o,{args:["login","--username",r.username,"--password-stdin",r.registry],stdin:r.password,timeoutMs:E});return e.spawnError!==void 0?i(c(e)):e.exitCode===null?i(a("abort",`docker login ${r.registry} was aborted`)):e.exitCode!==0?i(a("auth_failed",`docker login ${r.registry} failed (exit ${e.exitCode})`,{stderrTail:e.stderrTail})):u(void 0)}export{O as _imageInspect,y as _loginEcr,L as _pull,D as _push,M as _tag};

package/dist/docker/abortHelpers.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Cross-platform abort for spawned `docker` / `docker buildx` processes.
+ *
+ * `child_process.spawn(...).kill('SIGTERM')` on Windows translates to
+ * `TerminateProcess` — equivalent to SIGKILL, with no grace window. We
+ * use `taskkill /T /F /PID` instead so child trees (`docker` → buildkitd)
+ * are torn down explicitly. POSIX gets the standard SIGTERM-then-SIGKILL
+ * grace pattern.
+ *
+ * `platform` is injected so tests pass `"win32"` directly without
+ * `vi.stubGlobal('process', ...)`, which is fragile and leaks across
+ * tests.
+ *
+ * Stream cleanup before signalling per robustness-standards § "Process
+ * Timeout with Stream Cleanup".
+ */
+import { type ChildProcess } from "node:child_process";
+export declare function abortChildProcess(child: ChildProcess, platform?: NodeJS.Platform): void;

package/dist/docker/abortHelpers.js

@@ -0,0 +1 @@
+import{spawnSync as o}from"node:child_process";import{SIGTERM_GRACE_MS as s}from"./dockerCliConstants.js";function f(t,r=process.platform){if(t.pid===void 0)return;if(t.stdout&&t.stdout.destroy(),t.stderr&&t.stderr.destroy(),r==="win32"){o("taskkill",["/T","/F","/PID",String(t.pid)],{shell:!1});return}t.kill("SIGTERM");const e=setTimeout(()=>{t.killed||t.kill("SIGKILL")},s);t.once("exit",()=>clearTimeout(e))}export{f as abortChildProcess};

package/dist/docker/buildxArgvBuilder.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Pure function: `BuildxBuildArgs` → `string[]`.
+ *
+ * No closure state, no env reads, no subprocess calls, no I/O. The input
+ * is validated upstream by `BuildxBuildArgsSchema.safeParse()`; this
+ * function trusts its parameter shape and only emits argv tokens.
+ *
+ * Argv ordering matches the design §4.1 spec verbatim. Builder, progress,
+ * metadata-file, platform, tags, dockerfile, build-args, target, cache,
+ * provenance, sbom, push|load, then context path. Pure-function discipline
+ * is enforced by `buildxArgvBuilder.test.ts` (byte-identical output for
+ * the same input on repeat calls).
+ */
+import type { BuildxBuildArgs } from "./dockerCliSchemas.js";
+export declare function buildxArgvBuilder(args: BuildxBuildArgs): string[];

package/dist/docker/buildxArgvBuilder.js

@@ -0,0 +1 @@
+import{DEFAULT_BUILDER_NAME as f}from"./dockerCliConstants.js";function i(e){const o=["buildx","build"];o.push("--builder",e.builder??f),o.push("--progress=rawjson"),o.push("--metadata-file",e.metadataFile),o.push("--platform",e.platforms.join(","));for(const t of e.tags)o.push("-t",t);o.push("-f",e.dockerfilePath);for(const[t,u]of Object.entries(e.buildArgs))o.push("--build-arg",`${t}=${u}`);if(e.target!==void 0&&o.push("--target",e.target),e.cacheFrom!==void 0)for(const t of e.cacheFrom)o.push("--cache-from",t);if(e.cacheTo!==void 0)for(const t of e.cacheTo)o.push("--cache-to",t);if(e.secrets!==void 0)for(const t of e.secrets)o.push("--secret",`id=${t.id},src=${t.source}`);return o.push(`--provenance=${e.provenance?"true":"false"}`),o.push(`--sbom=${e.sbom?"true":"false"}`),e.push&&o.push("--push"),e.load&&o.push("--load"),o.push(e.contextPath),o}export{i as buildxArgvBuilder};

package/dist/docker/dockerCliConstants.d.ts

@@ -0,0 +1,15 @@
+export declare const DOCKER_CLI_LOG_CATEGORY = "DockerCli";
+export declare const DOCKER_CLI_BUILDX_LOG_CATEGORY = "DockerCli.buildx";
+export declare const BUILDX_VERSION_FLOOR = "0.13.0";
+export declare const ENGINE_VERSION_FLOOR = "23.0.0";
+export declare const PrerequisiteMissingExitCode = 64;
+export declare const DEFAULT_BUILDER_NAME = "fjall";
+export declare const DEFAULT_DOCKER_BIN = "docker";
+export declare const SIGTERM_GRACE_MS = 5000;
+export declare const STDERR_TAIL_LINES = 50;
+export declare const STDERR_TAIL_LINE_MAX_CHARS = 2000;
+export declare const DEFAULT_BUILD_TIMEOUT_MS = 600000;
+export declare const DEFAULT_PUSH_TIMEOUT_MS = 300000;
+export declare const DEFAULT_PULL_TIMEOUT_MS = 300000;
+export declare const DEFAULT_INSPECT_TIMEOUT_MS = 30000;
+export declare const DEFAULT_DAEMON_PROBE_TIMEOUT_MS = 10000;

package/dist/docker/dockerCliConstants.js

@@ -0,0 +1 @@
+const _="DockerCli",o="DockerCli.buildx",E="0.13.0",t="23.0.0",T=64,L="fjall",e="docker",I=5e3,r=50,O=2e3,D=6e5,c=3e5,s=3e5,R=3e4,U=1e4;export{E as BUILDX_VERSION_FLOOR,L as DEFAULT_BUILDER_NAME,D as DEFAULT_BUILD_TIMEOUT_MS,U as DEFAULT_DAEMON_PROBE_TIMEOUT_MS,e as DEFAULT_DOCKER_BIN,R as DEFAULT_INSPECT_TIMEOUT_MS,s as DEFAULT_PULL_TIMEOUT_MS,c as DEFAULT_PUSH_TIMEOUT_MS,o as DOCKER_CLI_BUILDX_LOG_CATEGORY,_ as DOCKER_CLI_LOG_CATEGORY,t as ENGINE_VERSION_FLOOR,T as PrerequisiteMissingExitCode,I as SIGTERM_GRACE_MS,r as STDERR_TAIL_LINES,O as STDERR_TAIL_LINE_MAX_CHARS};

package/dist/docker/dockerCliSchemas.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Zod schemas + companion types for the DockerCli boundary contract.
+ *
+ * Every cross-process boundary (CLI ↔ webapp worker, subprocess ↔ adapter)
+ * round-trips through these schemas. Pitfall guards encoded:
+ *   - Pitfall 1 (schema-interface drift): every TS type is `z.infer<typeof Schema>`
+ *   - Pitfall 3 (.strict() on every z.object()): all object schemas use .strict() before refinements
+ *   - Pitfall 4 (.parse() inside Result): callers use safeParse() and map to failure({...})
+ *   - Pitfall 6 (companion type pairing): every export pairs schema + type in the same statement
+ *   - Pitfall 7 (mutable .default()): no schema uses .default({}) or .default([])
+ *   - Pitfall 9 (.optional() string + empty-string trap): `target` uses .min(1).optional()
+ *
+ * `BuildxBuildArgs` is the argv-builder contract — flat fields that map 1:1
+ * to `docker buildx build` flags. The role-aware manifest contract
+ * (`DockerBuild { path, context?, target? }`) lives in `@fjall/util/manifest`
+ * and is projected into this shape by a thin caller-side adapter
+ * (`dockerBuildToBuildxArgs`) in PR 2's CLI orchestrator.
+ */
+import { z } from "zod";
+export declare const DockerCliErrorKindSchema: z.ZodEnum<{
+    abort: "abort";
+    validation: "validation";
+    buildx_unavailable: "buildx_unavailable";
+    daemon_unreachable: "daemon_unreachable";
+    build_failed: "build_failed";
+    push_failed: "push_failed";
+    pull_failed: "pull_failed";
+    tag_failed: "tag_failed";
+    inspect_failed: "inspect_failed";
+    auth_failed: "auth_failed";
+    timeout: "timeout";
+    metadata_missing: "metadata_missing";
+    metadata_malformed: "metadata_malformed";
+    metadata_missing_digest: "metadata_missing_digest";
+}>;
+export type DockerCliErrorKind = z.infer<typeof DockerCliErrorKindSchema>;
+export declare function isDockerCliErrorKind(value: string): value is DockerCliErrorKind;
+export declare const BuildxBuildArgsSchema: z.ZodObject<{
+    contextPath: z.ZodString;
+    dockerfilePath: z.ZodString;
+    target: z.ZodOptional<z.ZodString>;
+    platforms: z.ZodArray<z.ZodString>;
+    tags: z.ZodArray<z.ZodString>;
+    buildArgs: z.ZodRecord<z.ZodString, z.ZodString>;
+    cacheFrom: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    cacheTo: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    secrets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        source: z.ZodString;
+    }, z.core.$strict>>>;
+    provenance: z.ZodBoolean;
+    sbom: z.ZodBoolean;
+    push: z.ZodBoolean;
+    load: z.ZodBoolean;
+    builder: z.ZodOptional<z.ZodString>;
+    metadataFile: z.ZodString;
+}, z.core.$strict>;
+export type BuildxBuildArgs = z.infer<typeof BuildxBuildArgsSchema>;
+export declare const BuildxBuildResultSchema: z.ZodObject<{
+    imageDigests: z.ZodRecord<z.ZodString, z.ZodString>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    platforms: z.ZodArray<z.ZodString>;
+    cacheHits: z.ZodNumber;
+    cacheMisses: z.ZodNumber;
+}, z.core.$strict>;
+export type BuildxBuildResult = z.infer<typeof BuildxBuildResultSchema>;
+export declare const DockerCliErrorSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        abort: "abort";
+        validation: "validation";
+        buildx_unavailable: "buildx_unavailable";
+        daemon_unreachable: "daemon_unreachable";
+        build_failed: "build_failed";
+        push_failed: "push_failed";
+        pull_failed: "pull_failed";
+        tag_failed: "tag_failed";
+        inspect_failed: "inspect_failed";
+        auth_failed: "auth_failed";
+        timeout: "timeout";
+        metadata_missing: "metadata_missing";
+        metadata_malformed: "metadata_malformed";
+        metadata_missing_digest: "metadata_missing_digest";
+    }>;
+    message: z.ZodString;
+    stderrTail: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    details: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>;
+export type DockerCliError = z.infer<typeof DockerCliErrorSchema>;

package/dist/docker/dockerCliSchemas.js

@@ -0,0 +1 @@
+import{z as t}from"zod";const a=t.enum(["buildx_unavailable","daemon_unreachable","build_failed","push_failed","pull_failed","tag_failed","inspect_failed","auth_failed","abort","timeout","validation","metadata_missing","metadata_malformed","metadata_missing_digest"]),e=new Set(a.options);function r(i){return e.has(i)}const o=t.object({contextPath:t.string().min(1),dockerfilePath:t.string().min(1),target:t.string().min(1).optional(),platforms:t.array(t.string().min(1)).min(1),tags:t.array(t.string().min(1)).min(1),buildArgs:t.record(t.string(),t.string()),cacheFrom:t.array(t.string().min(1)).optional(),cacheTo:t.array(t.string().min(1)).optional(),secrets:t.array(t.object({id:t.string().min(1),source:t.string().min(1)}).strict()).optional(),provenance:t.boolean(),sbom:t.boolean(),push:t.boolean(),load:t.boolean(),builder:t.string().min(1,"Builder name cannot be empty").optional(),metadataFile:t.string().min(1)}).strict().refine(i=>!(i.platforms.length>1&&i.load),{message:"Multi-arch builds cannot use load:true (Docker limitation); use push:true or omit both for cache-only"}).refine(i=>!(i.push&&i.load),{message:"push and load are mutually exclusive"}),s=t.object({imageDigests:t.record(t.string(),t.string()),metadata:t.record(t.string(),t.unknown()),platforms:t.array(t.string()),cacheHits:t.number().int().nonnegative(),cacheMisses:t.number().int().nonnegative()}).strict(),l=t.object({kind:a,message:t.string(),stderrTail:t.array(t.string()).optional(),details:t.unknown().optional()}).strict();export{o as BuildxBuildArgsSchema,s as BuildxBuildResultSchema,a as DockerCliErrorKindSchema,l as DockerCliErrorSchema,r as isDockerCliErrorKind};

package/dist/docker/index.d.ts

@@ -0,0 +1,10 @@
+export { type Result, isSuccess, isFailure, success, failure } from "./result.js";
+export { DOCKER_CLI_LOG_CATEGORY, DOCKER_CLI_BUILDX_LOG_CATEGORY, BUILDX_VERSION_FLOOR, ENGINE_VERSION_FLOOR, PrerequisiteMissingExitCode, DEFAULT_BUILDER_NAME, DEFAULT_DOCKER_BIN, SIGTERM_GRACE_MS, STDERR_TAIL_LINES, DEFAULT_BUILD_TIMEOUT_MS, DEFAULT_PUSH_TIMEOUT_MS, DEFAULT_PULL_TIMEOUT_MS, DEFAULT_INSPECT_TIMEOUT_MS, DEFAULT_DAEMON_PROBE_TIMEOUT_MS } from "./dockerCliConstants.js";
+export { BuildxBuildArgsSchema, BuildxBuildResultSchema, DockerCliErrorKindSchema, DockerCliErrorSchema, isDockerCliErrorKind, type BuildxBuildArgs, type BuildxBuildResult, type DockerCliError, type DockerCliErrorKind } from "./dockerCliSchemas.js";
+export { buildxArgvBuilder } from "./buildxArgvBuilder.js";
+export { parseRawjsonLine, type RawjsonEnvelope, type RawjsonVertex, type RawjsonStatus, type RawjsonLog, type RawjsonWarning } from "./rawjsonParser.js";
+export { rawjsonToVertexEvent, type RawjsonVertexEvent, type NormalisedVertex, type NormalisedStatus, type NormalisedLog, type NormalisedWarning } from "./rawjsonToVertexEvent.js";
+export { parseMetadataFile } from "./metadataFileParser.js";
+export { projectBuildxResult, type DockerBuildResultLike, type ProjectBuildxResultArgs } from "./projectBuildxResult.js";
+export { abortChildProcess } from "./abortHelpers.js";
+export { DockerCli, type DockerCliLogger, type DockerCliOptions, type BuildxProgressEvent, type PushProgressEvent, type PushResult, type PullProgressEvent, type PullResult, type ImagetoolsInspect, type EcrLoginArgs, type BuildxCapabilities, type DaemonInfo } from "./DockerCli.js";

package/dist/docker/index.js

@@ -0,0 +1 @@
+import{isSuccess as E,isFailure as _,success as o,failure as i}from"./result.js";import{DOCKER_CLI_LOG_CATEGORY as L,DOCKER_CLI_BUILDX_LOG_CATEGORY as s,BUILDX_VERSION_FLOOR as t,ENGINE_VERSION_FLOOR as D,PrerequisiteMissingExitCode as O,DEFAULT_BUILDER_NAME as I,DEFAULT_DOCKER_BIN as R,SIGTERM_GRACE_MS as S,STDERR_TAIL_LINES as U,DEFAULT_BUILD_TIMEOUT_MS as l,DEFAULT_PUSH_TIMEOUT_MS as x,DEFAULT_PULL_TIMEOUT_MS as M,DEFAULT_INSPECT_TIMEOUT_MS as A,DEFAULT_DAEMON_PROBE_TIMEOUT_MS as C}from"./dockerCliConstants.js";import{BuildxBuildArgsSchema as c,BuildxBuildResultSchema as m,DockerCliErrorKindSchema as u,DockerCliErrorSchema as p,isDockerCliErrorKind as d}from"./dockerCliSchemas.js";import{buildxArgvBuilder as f}from"./buildxArgvBuilder.js";import{parseRawjsonLine as N}from"./rawjsonParser.js";import{rawjsonToVertexEvent as G}from"./rawjsonToVertexEvent.js";import{parseMetadataFile as h}from"./metadataFileParser.js";import{projectBuildxResult as k}from"./projectBuildxResult.js";import{abortChildProcess as j}from"./abortHelpers.js";import{DockerCli as b}from"./DockerCli.js";export{t as BUILDX_VERSION_FLOOR,c as BuildxBuildArgsSchema,m as BuildxBuildResultSchema,I as DEFAULT_BUILDER_NAME,l as DEFAULT_BUILD_TIMEOUT_MS,C as DEFAULT_DAEMON_PROBE_TIMEOUT_MS,R as DEFAULT_DOCKER_BIN,A as DEFAULT_INSPECT_TIMEOUT_MS,M as DEFAULT_PULL_TIMEOUT_MS,x as DEFAULT_PUSH_TIMEOUT_MS,s as DOCKER_CLI_BUILDX_LOG_CATEGORY,L as DOCKER_CLI_LOG_CATEGORY,b as DockerCli,u as DockerCliErrorKindSchema,p as DockerCliErrorSchema,D as ENGINE_VERSION_FLOOR,O as PrerequisiteMissingExitCode,S as SIGTERM_GRACE_MS,U as STDERR_TAIL_LINES,j as abortChildProcess,f as buildxArgvBuilder,i as failure,d as isDockerCliErrorKind,_ as isFailure,E as isSuccess,h as parseMetadataFile,N as parseRawjsonLine,k as projectBuildxResult,G as rawjsonToVertexEvent,o as success};

package/dist/docker/metadataFileParser.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Reads + parses the JSON file `docker buildx build` writes via
+ * `--metadata-file`. Returns the raw metadata blob; consumer code (e.g.
+ * `projectBuildxResult.ts`) is responsible for extracting specific keys
+ * such as `containerimage.digest`.
+ *
+ * Three failure shapes mapped to distinct DockerCliError kinds:
+ *   - `metadata_missing`   — file does not exist (ENOENT)
+ *   - `metadata_malformed` — file exists but contents are not valid JSON
+ *   - `inspect_failed`     — any other read I/O error
+ *
+ * Out of scope: writing the metadata file (buildx does that), choosing the
+ * tmp path (the DockerCli caller does that), digest extraction (projection).
+ */
+import { type DockerCliError } from "./dockerCliSchemas.js";
+import { type Result } from "./result.js";
+export declare function parseMetadataFile(path: string): Promise<Result<Record<string, unknown>, DockerCliError>>;

package/dist/docker/metadataFileParser.js

@@ -0,0 +1 @@
+import{readFile as n}from"node:fs/promises";import{maskSensitiveOutput as m}from"../securityHelpers.js";import{makeError as a}from"./DockerCli.js";import{failure as i,success as f}from"./result.js";async function S(e){let o;try{o=await n(e,"utf8")}catch(r){if(r?.code==="ENOENT")return i(a("metadata_missing",`Buildx metadata file not found at ${e}`,{path:e}));const s=m(r instanceof Error?r.message:String(r));return i(a("inspect_failed",`Failed to read buildx metadata file at ${e}: ${s}`,{path:e}))}let t;try{t=JSON.parse(o)}catch(r){const d=m(r instanceof Error?r.message:String(r));return i(a("metadata_malformed",`Buildx metadata file at ${e} is not valid JSON: ${d}`,{path:e}))}return t===null||typeof t!="object"||Array.isArray(t)?i(a("metadata_malformed",`Buildx metadata file at ${e} is not a JSON object`,{path:e})):f(t)}export{S as parseMetadataFile};