@mysten-incubation/devstack 0.0.0

package/dist/runtime/docker/image.mjs

@@ -0,0 +1,278 @@
+import { decodeJsonTextSync } from "../../substrate/runtime/runtime-decode.mjs";
+import { CacheService } from "../../substrate/runtime/cache/service.mjs";
+import { DockerHost, DockerSpawner, dockerCommand, dockerRun, dockerRunOk } from "./client.mjs";
+import { ImageLoadFailed, ImageNotFound, ImageRemoveFailed, ImageSaveFailed, ImageTagFailed } from "./errors.mjs";
+import { isImageNotFoundStderr, wrapBuildError, wrapGeneric, wrapPullError } from "./wrap.mjs";
+import { Effect, Fiber, Schema, Stream } from "effect";
+//#region src/runtime/docker/image.ts
+const SNAPSHOT_TEMP_TAG_PREFIX = "devstack-snapshot:";
+const isSnapshotTempTag = (ref) => ref.startsWith(SNAPSHOT_TEMP_TAG_PREFIX);
+const cleanupSnapshotTempTag = (ref) => {
+	if (!isSnapshotTempTag(ref)) return Effect.void;
+	return dockerRunOk("image", ["rm", ref]).pipe(Effect.catch(() => Effect.void), Effect.asVoid);
+};
+/** Encode/decode the cache entry — we store the resolved image digest
+*  as plain UTF-8 bytes so the cache primitive's byte shape works. */
+const encodeDigest = (digest) => new TextEncoder().encode(JSON.stringify({ digest }));
+const DigestDoc = Schema.Struct({ digest: Schema.String });
+const decodeDigest = (bytes) => {
+	try {
+		return decodeJsonTextSync(DigestDoc, new TextDecoder().decode(bytes), {
+			source: "docker image digest cache",
+			mkError: (issue) => issue
+		}).digest;
+	} catch {
+		return null;
+	}
+};
+/** `docker image inspect <ref>` — returns the digest, or null on miss. */
+const imageExists = (ref) => Effect.gen(function* () {
+	const res = yield* dockerRunOk("image", [
+		"inspect",
+		"--format",
+		"{{.Id}}",
+		ref
+	]).pipe(Effect.mapError(wrapGeneric("docker.image.inspect")));
+	if (res.exitCode !== 0) return null;
+	const id = res.stdout.trim();
+	return id.length > 0 ? id : null;
+}).pipe(Effect.withSpan("runtime.docker.image.exists"));
+/** Strict variant — surfaces `ImageNotFound` if the inspect misses. */
+const inspectDigest = (ref) => Effect.gen(function* () {
+	const id = yield* imageExists(ref);
+	if (id === null) return yield* Effect.fail(new ImageNotFound({
+		ref,
+		detail: "docker image inspect returned empty"
+	}));
+	return id;
+}).pipe(Effect.withSpan("runtime.docker.image.inspectDigest"));
+/** `docker pull <ref>` — surfaces ImageNotFound / ImagePullFailed.
+*  Per-line progress emission opt-in via `onLine`. */
+const pull = (ref, onLine) => Effect.gen(function* () {
+	yield* dockerRun("pull", [ref], { onStdoutLine: onLine }).pipe(Effect.mapError(wrapPullError(ref)));
+	return yield* inspectDigest(ref);
+}).pipe(Effect.withSpan("runtime.docker.image.pull"));
+/** `docker build -t <tag> [-f Dockerfile] <ctx>`. On exit-0 the
+*  resulting tag is on-host; we read its digest and return.
+*
+*  NOTE: the content-addressed cache integration is in `ensureImageCached`
+*  below — this verb is the unconditional build, used when the cache
+*  has missed AND the on-host tag-exists probe also missed. */
+const build = (opts) => Effect.gen(function* () {
+	const args = ["-t", opts.tag];
+	if (opts.platform !== void 0) args.push("--platform", opts.platform);
+	if (opts.dockerfile && opts.dockerfile !== "Dockerfile") {
+		const resolved = opts.dockerfile.startsWith("/") || /^[A-Za-z]:/.test(opts.dockerfile) ? opts.dockerfile : `${opts.contextPath.replace(/\/$/, "")}/${opts.dockerfile}`;
+		args.push("-f", resolved);
+	}
+	if (opts.buildArgs) for (const [k, v] of Object.entries(opts.buildArgs)) args.push("--build-arg", `${k}=${v}`);
+	args.push(opts.contextPath);
+	yield* dockerRun("build", args, {
+		onStdoutLine: opts.onLine,
+		onStderrLine: opts.onLine
+	}).pipe(Effect.mapError(wrapBuildError(opts.contextPath, opts.dockerfile)));
+	return yield* inspectDigest(opts.tag);
+}).pipe(Effect.withSpan("runtime.docker.image.build"));
+/** `docker tag <src> <dst>` — used by snapshot restore to alias a
+*  loaded image back to its original tag. */
+const tagImage = (src, dst, opts = {}) => Effect.gen(function* () {
+	const res = yield* dockerRunOk("tag", [src, dst]).pipe(Effect.mapError(wrapGeneric("docker.tag")));
+	if (res.exitCode !== 0) {
+		if (isImageNotFoundStderr(res.stderr)) return yield* Effect.fail(new ImageNotFound({
+			ref: src,
+			detail: `tag source missing: ${res.stderr}`
+		}));
+		return yield* Effect.fail(new ImageTagFailed({
+			src,
+			dst,
+			stderr: res.stderr
+		}));
+	}
+	if (opts.removeSourceAfterTag === true && src !== dst) yield* cleanupSnapshotTempTag(src);
+}).pipe(Effect.withSpan("runtime.docker.image.tag"));
+const isMissingImageStderr = (stderr) => /no such image|not found|reference does not exist/i.test(stderr);
+const removeImage = (ref) => Effect.gen(function* () {
+	const res = yield* dockerRunOk("image", [
+		"rm",
+		"-f",
+		ref
+	]).pipe(Effect.mapError(wrapGeneric("docker.image.rm")));
+	if (res.exitCode === 0 || isMissingImageStderr(res.stderr)) return;
+	return yield* Effect.fail(new ImageRemoveFailed({
+		ref,
+		stderr: res.stderr,
+		exitCode: res.exitCode
+	}));
+}).pipe(Effect.withSpan("runtime.docker.image.remove"));
+/** Stream the bytes of `docker save <ref>` to the consumer. Stdout
+*  stays streaming so large images never materialise in memory; stderr
+*  and exit are drained concurrently so a missing image cannot look
+*  like a successful empty tar. */
+const saveImages = (refs, opts = {}) => {
+	const mapSpawnError = (cause) => new ImageSaveFailed({
+		ref: refs.join(" "),
+		detail: refs.length === 0 ? "docker save called with no image refs" : "docker save spawn failed",
+		cause
+	});
+	if (refs.length === 0) return Stream.fail(mapSpawnError(/* @__PURE__ */ new Error("empty docker save ref list")));
+	return Stream.unwrap(Effect.gen(function* () {
+		const host = yield* DockerHost;
+		const spawner = yield* DockerSpawner;
+		const cmd = dockerCommand(host, "save", refs);
+		const handle = yield* spawner.spawn(cmd).pipe(Effect.mapError(mapSpawnError));
+		const stderrFiber = yield* Effect.forkChild(Stream.mkString(Stream.decodeText(handle.stderr)).pipe(Effect.mapError((cause) => new ImageSaveFailed({
+			ref: refs.join(" "),
+			detail: "docker save stderr drain failed",
+			cause
+		}))));
+		const exitFiber = yield* Effect.forkChild(handle.exitCode.pipe(Effect.mapError((cause) => new ImageSaveFailed({
+			ref: refs.join(" "),
+			detail: "docker save exit failed",
+			cause
+		}))));
+		const checkExit = Effect.gen(function* () {
+			const [stderrText, exitCode] = yield* Effect.all([Fiber.join(stderrFiber), Fiber.join(exitFiber)], { concurrency: "unbounded" });
+			if (exitCode !== 0) return yield* Effect.fail(new ImageSaveFailed({
+				ref: refs.join(" "),
+				detail: `docker save exited ${exitCode}${stderrText.length > 0 ? `: ${stderrText}` : ""}`
+			}));
+		});
+		const cleanupTag = opts.removeAfterSave === true ? Effect.forEach(refs, cleanupSnapshotTempTag, { concurrency: "unbounded" }).pipe(Effect.asVoid) : Effect.void;
+		const cleanup = Effect.all([
+			cleanupTag,
+			Fiber.interrupt(stderrFiber),
+			Fiber.interrupt(exitFiber)
+		], { concurrency: "unbounded" }).pipe(Effect.asVoid);
+		return handle.stdout.pipe(Stream.mapError((cause) => new ImageSaveFailed({
+			ref: refs.join(" "),
+			detail: "docker save stdout pipe failed",
+			cause
+		})), Stream.onEnd(checkExit), Stream.ensuring(cleanup));
+	}));
+};
+const saveImage = (ref, opts = {}) => saveImages([ref], opts);
+/** Parse `docker load` stdout lines to extract the loaded image refs.
+*  Docker's output is one of:
+*   - `Loaded image: <tag>`
+*   - `Loaded image ID: sha256:<digest>`
+*  Exported for direct testing without a docker dependency. */
+const parseLoadedRefs = (stdout) => {
+	const refs = [];
+	for (const rawLine of stdout.split(/\r?\n/)) {
+		const line = rawLine.trim();
+		const taggedMatch = /^Loaded image: (\S+)$/.exec(line);
+		if (taggedMatch?.[1]) {
+			refs.push({ tag: taggedMatch[1] });
+			continue;
+		}
+		const digestMatch = /^Loaded image ID: (sha256:\S+)$/.exec(line);
+		if (digestMatch?.[1]) refs.push({ digest: digestMatch[1] });
+	}
+	return refs;
+};
+/** `docker load < <tar-stream>`. Returns every freshly-loaded ref
+*  Docker reported on stdout. Symmetric with `saveImage`/`saveImages`.
+*  Upstream stream errors (e.g. file-read failures from a snapshot
+*  tar) are projected to `ImageLoadFailed` so callers see one shape.
+*
+*  Stdin lifetime: the supplied stream is fed in via the spawner's
+*  `stdin` sink under the same scope as the spawn itself; both close
+*  when the child exits. */
+const loadImage = (tar) => Effect.gen(function* () {
+	const host = yield* DockerHost;
+	const spawner = yield* DockerSpawner;
+	const cmd = dockerCommand(host, "load", []);
+	const mapSpawnError = (cause) => new ImageLoadFailed({
+		detail: "docker load spawn failed",
+		cause
+	});
+	return yield* Effect.scoped(Effect.gen(function* () {
+		const handle = yield* spawner.spawn(cmd).pipe(Effect.mapError(mapSpawnError));
+		const writeStdin = Stream.run(tar, handle.stdin).pipe(Effect.mapError((cause) => new ImageLoadFailed({
+			detail: "docker load stdin pipe failed",
+			cause
+		})));
+		const stdoutDrain = Stream.mkString(Stream.decodeText(handle.stdout)).pipe(Effect.mapError((cause) => new ImageLoadFailed({
+			detail: "docker load stdout drain failed",
+			cause
+		})));
+		const stderrDrain = Stream.mkString(Stream.decodeText(handle.stderr)).pipe(Effect.mapError((cause) => new ImageLoadFailed({
+			detail: "docker load stderr drain failed",
+			cause
+		})));
+		const exit = handle.exitCode.pipe(Effect.mapError((cause) => new ImageLoadFailed({
+			detail: "docker load exit failed",
+			cause
+		})));
+		const [, stdoutText, stderrText, exitCode] = yield* Effect.all([
+			writeStdin,
+			stdoutDrain,
+			stderrDrain,
+			exit
+		], { concurrency: "unbounded" });
+		if (exitCode !== 0) return yield* Effect.fail(new ImageLoadFailed({
+			detail: `docker load exited ${exitCode}`,
+			stderr: stderrText
+		}));
+		const parsed = parseLoadedRefs(stdoutText);
+		if (parsed.length === 0) return yield* Effect.fail(new ImageLoadFailed({
+			detail: "docker load succeeded but no Loaded image lines found",
+			stderr: stdoutText
+		}));
+		return { refs: yield* Effect.forEach(parsed, (ref) => Effect.gen(function* () {
+			if (ref.digest !== void 0) return refOf(ref.digest, ref.tag);
+			const digest = yield* imageExists(ref.tag);
+			if (digest === null) return yield* Effect.fail(new ImageLoadFailed({ detail: `loaded image '${ref.tag}' not visible to inspect` }));
+			return refOf(digest, ref.tag);
+		}), { concurrency: "unbounded" }) };
+	}));
+}).pipe(Effect.withSpan("runtime.docker.image.load"));
+/** Content-addressed image build:
+*
+*    1. cache lookup keyed by (namespace, chainId, contentHash)
+*    2. on hit, verify the on-host tag still resolves; if so return
+*    3. on miss, run `docker build`, then write the resolved digest
+*       to the cache (best-effort — write failure does not roll back
+*       the on-host build).
+*
+*  Caller-supplied tag is the content-addressed name; the cache key
+*  is independent so an unrelated invalidation (e.g. base-image
+*  bump) can drop the cache without disturbing the tag scheme. */
+const ensureImageCached = (opts, key) => Effect.gen(function* () {
+	const cache = yield* CacheService;
+	const hit = yield* cache.lookup({
+		namespace: key.namespace,
+		chain: key.chain,
+		contentHash: key.contentHash
+	}).pipe(Effect.catch(() => Effect.succeed(null)));
+	if (hit !== null) {
+		if (decodeDigest(hit.bytes) !== null) {
+			const existing = yield* imageExists(opts.tag);
+			if (existing !== null) return existing;
+		}
+	}
+	const onHost = yield* imageExists(opts.tag);
+	if (onHost !== null) {
+		yield* cache.write({
+			namespace: key.namespace,
+			chain: key.chain,
+			contentHash: key.contentHash
+		}, encodeDigest(onHost)).pipe(Effect.catch(() => Effect.void));
+		return onHost;
+	}
+	const digest = yield* build(opts);
+	yield* cache.write({
+		namespace: key.namespace,
+		chain: key.chain,
+		contentHash: key.contentHash
+	}, encodeDigest(digest)).pipe(Effect.catch(() => Effect.void));
+	return digest;
+}).pipe(Effect.withSpan("runtime.docker.image.ensureCached"));
+const refOf = (digest, tag) => tag !== void 0 ? {
+	digest,
+	tag
+} : { digest };
+//#endregion
+export { ensureImageCached, loadImage, pull, refOf, removeImage, saveImage, saveImages, tagImage };
+
+//# sourceMappingURL=image.mjs.map

package/dist/runtime/docker/image.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.mjs","names":[],"sources":["../../../src/runtime/docker/image.ts"],"sourcesContent":["// Docker image lifecycle.\n//\n// Architecture § Docker backend § Images:\n//   - Bring-your-own-image vs build is a CLOSED SUM (architecture §8):\n//     either the caller supplies an image ref (`docker pull`) or a\n//     `ContainerBuildContext` (`docker build`); no third option.\n//   - Content-addressed build cache: the substrate's L0 cache holds\n//     the `(namespace, chainId, contentHash) → imageDigest` mapping.\n//     When the cache hits we short-circuit the build. The `docker\n//     build` itself is then a no-op when the resulting tag already\n//     exists on the host (defense-in-depth — cache miss but on-host\n//     tag-exists still skips the build).\n//   - Pull progress narration is wired through `onStdoutLine` /\n//     `onStderrLine` per-line callbacks on the L0 capture; the L1\n//     observability sink promotes WARN/ERROR markers.\n//\n// Surface:\n//   - `imageExists(ref)` — `docker inspect` short-circuit\n//   - `pull(ref)`        — `docker pull`; surfaces ImageNotFound /\n//                          ImagePullFailed via wrap.ts\n//   - `build(ctx, tag)`  — `docker build -t <tag> <ctx>`; surfaces\n//                          BuildFailed via wrap.ts; integrates with\n//                          the L0 cache\n//   - `tag(src, dst)`    — `docker tag`\n//   - `inspectDigest`    — read the on-host digest of a tag\n\nimport { Effect, Fiber, Schema, Stream } from 'effect';\n\nimport type { ChainId, ContentHash } from '../../substrate/brand.ts';\nimport { CacheService } from '../../substrate/runtime/cache/index.ts';\nimport { decodeJsonTextSync } from '../../substrate/runtime/runtime-decode.ts';\nimport type { ImageRef, LoadedImageBundle } from '../../contracts/container-runtime.ts';\nimport { DockerHost, DockerSpawner, dockerCommand, dockerRun, dockerRunOk } from './client.ts';\nimport type { DockerRuntimeError } from './errors.ts';\nimport {\n\tImageLoadFailed,\n\tImageNotFound,\n\tImageRemoveFailed,\n\tImageSaveFailed,\n\tImageTagFailed,\n} from './errors.ts';\nimport { isImageNotFoundStderr, wrapBuildError, wrapGeneric, wrapPullError } from './wrap.ts';\n\n// -----------------------------------------------------------------------------\n// Helpers\n// -----------------------------------------------------------------------------\n\nconst SNAPSHOT_TEMP_TAG_PREFIX = 'devstack-snapshot:';\n\nconst isSnapshotTempTag = (ref: string): boolean => ref.startsWith(SNAPSHOT_TEMP_TAG_PREFIX);\n\nconst cleanupSnapshotTempTag = (\n\tref: string,\n): Effect.Effect<void, never, DockerHost | DockerSpawner> => {\n\tif (!isSnapshotTempTag(ref)) return Effect.void;\n\treturn dockerRunOk('image', ['rm', ref]).pipe(\n\t\tEffect.catch(() => Effect.void),\n\t\tEffect.asVoid,\n\t);\n};\n\nexport interface SaveImageOptions {\n\treadonly removeAfterSave?: boolean;\n}\n\nexport interface TagImageOptions {\n\treadonly removeSourceAfterTag?: boolean;\n}\n\n/** Encode/decode the cache entry — we store the resolved image digest\n *  as plain UTF-8 bytes so the cache primitive's byte shape works. */\nconst encodeDigest = (digest: string): Uint8Array =>\n\tnew TextEncoder().encode(JSON.stringify({ digest } satisfies { digest: string }));\n\nconst DigestDoc = Schema.Struct({ digest: Schema.String });\n\nconst decodeDigest = (bytes: Uint8Array): string | null => {\n\ttry {\n\t\treturn decodeJsonTextSync(DigestDoc, new TextDecoder().decode(bytes), {\n\t\t\tsource: 'docker image digest cache',\n\t\t\tmkError: (issue) => issue,\n\t\t}).digest;\n\t} catch {\n\t\treturn null;\n\t}\n};\n\n// -----------------------------------------------------------------------------\n// Exists / inspect\n// -----------------------------------------------------------------------------\n\n/** `docker image inspect <ref>` — returns the digest, or null on miss. */\nexport const imageExists = (\n\tref: string,\n): Effect.Effect<string | null, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst res = yield* dockerRunOk('image', ['inspect', '--format', '{{.Id}}', ref]).pipe(\n\t\t\tEffect.mapError(wrapGeneric('docker.image.inspect')),\n\t\t);\n\t\tif (res.exitCode !== 0) return null;\n\t\tconst id = res.stdout.trim();\n\t\treturn id.length > 0 ? id : null;\n\t}).pipe(Effect.withSpan('runtime.docker.image.exists'));\n\n/** Strict variant — surfaces `ImageNotFound` if the inspect misses. */\nexport const inspectDigest = (\n\tref: string,\n): Effect.Effect<string, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst id = yield* imageExists(ref);\n\t\tif (id === null) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew ImageNotFound({ ref, detail: 'docker image inspect returned empty' }),\n\t\t\t);\n\t\t}\n\t\treturn id;\n\t}).pipe(Effect.withSpan('runtime.docker.image.inspectDigest'));\n\n// -----------------------------------------------------------------------------\n// Pull\n// -----------------------------------------------------------------------------\n\n/** `docker pull <ref>` — surfaces ImageNotFound / ImagePullFailed.\n *  Per-line progress emission opt-in via `onLine`. */\nexport const pull = (\n\tref: string,\n\tonLine?: (line: string) => Effect.Effect<void>,\n): Effect.Effect<string, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tyield* dockerRun('pull', [ref], { onStdoutLine: onLine }).pipe(\n\t\t\tEffect.mapError(wrapPullError(ref)),\n\t\t);\n\t\treturn yield* inspectDigest(ref);\n\t}).pipe(Effect.withSpan('runtime.docker.image.pull'));\n\n// -----------------------------------------------------------------------------\n// Build (content-addressed)\n// -----------------------------------------------------------------------------\n\nexport interface BuildOptions {\n\treadonly contextPath: string;\n\treadonly dockerfile?: string;\n\treadonly platform?: string;\n\treadonly buildArgs?: Readonly<Record<string, string>>;\n\treadonly tag: string;\n\treadonly onLine?: (line: string) => Effect.Effect<void>;\n}\n\n/** `docker build -t <tag> [-f Dockerfile] <ctx>`. On exit-0 the\n *  resulting tag is on-host; we read its digest and return.\n *\n *  NOTE: the content-addressed cache integration is in `ensureImageCached`\n *  below — this verb is the unconditional build, used when the cache\n *  has missed AND the on-host tag-exists probe also missed. */\nexport const build = (\n\topts: BuildOptions,\n): Effect.Effect<string, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst args: Array<string> = ['-t', opts.tag];\n\t\tif (opts.platform !== undefined) {\n\t\t\targs.push('--platform', opts.platform);\n\t\t}\n\t\t// `-f` is resolved relative to the docker CLI's CWD, NOT the\n\t\t// context directory. Skip `-f` entirely when the dockerfile is\n\t\t// the canonical default name (`Dockerfile`) and the context is a\n\t\t// directory — docker buildx then auto-discovers `<ctx>/Dockerfile`.\n\t\t// When the user names a non-default dockerfile, resolve it against\n\t\t// the context so `docker build -f a/b/Dockerfile.x .` works\n\t\t// regardless of CWD.\n\t\tif (opts.dockerfile && opts.dockerfile !== 'Dockerfile') {\n\t\t\tconst isAbs = opts.dockerfile.startsWith('/') || /^[A-Za-z]:/.test(opts.dockerfile);\n\t\t\tconst resolved = isAbs\n\t\t\t\t? opts.dockerfile\n\t\t\t\t: `${opts.contextPath.replace(/\\/$/, '')}/${opts.dockerfile}`;\n\t\t\targs.push('-f', resolved);\n\t\t}\n\t\tif (opts.buildArgs) {\n\t\t\tfor (const [k, v] of Object.entries(opts.buildArgs)) {\n\t\t\t\targs.push('--build-arg', `${k}=${v}`);\n\t\t\t}\n\t\t}\n\t\targs.push(opts.contextPath);\n\t\tyield* dockerRun('build', args, {\n\t\t\tonStdoutLine: opts.onLine,\n\t\t\tonStderrLine: opts.onLine,\n\t\t}).pipe(Effect.mapError(wrapBuildError(opts.contextPath, opts.dockerfile)));\n\t\treturn yield* inspectDigest(opts.tag);\n\t}).pipe(Effect.withSpan('runtime.docker.image.build'));\n\n// -----------------------------------------------------------------------------\n// Tag\n// -----------------------------------------------------------------------------\n\n/** `docker tag <src> <dst>` — used by snapshot restore to alias a\n *  loaded image back to its original tag. */\nexport const tagImage = (\n\tsrc: string,\n\tdst: string,\n\topts: TagImageOptions = {},\n): Effect.Effect<void, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst res = yield* dockerRunOk('tag', [src, dst]).pipe(\n\t\t\tEffect.mapError(wrapGeneric('docker.tag')),\n\t\t);\n\t\tif (res.exitCode !== 0) {\n\t\t\tif (isImageNotFoundStderr(res.stderr)) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tnew ImageNotFound({ ref: src, detail: `tag source missing: ${res.stderr}` }),\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn yield* Effect.fail(new ImageTagFailed({ src, dst, stderr: res.stderr }));\n\t\t}\n\t\tif (opts.removeSourceAfterTag === true && src !== dst) {\n\t\t\tyield* cleanupSnapshotTempTag(src);\n\t\t}\n\t}).pipe(Effect.withSpan('runtime.docker.image.tag'));\n\nconst isMissingImageStderr = (stderr: string): boolean =>\n\t/no such image|not found|reference does not exist/i.test(stderr);\n\nexport const removeImage = (\n\tref: string,\n): Effect.Effect<void, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst res = yield* dockerRunOk('image', ['rm', '-f', ref]).pipe(\n\t\t\tEffect.mapError(wrapGeneric('docker.image.rm')),\n\t\t);\n\t\tif (res.exitCode === 0 || isMissingImageStderr(res.stderr)) return;\n\t\treturn yield* Effect.fail(\n\t\t\tnew ImageRemoveFailed({\n\t\t\t\tref,\n\t\t\t\tstderr: res.stderr,\n\t\t\t\texitCode: res.exitCode,\n\t\t\t}),\n\t\t);\n\t}).pipe(Effect.withSpan('runtime.docker.image.remove'));\n\n// -----------------------------------------------------------------------------\n// Save (image → tar stream)\n// -----------------------------------------------------------------------------\n\n/** Stream the bytes of `docker save <ref>` to the consumer. Stdout\n *  stays streaming so large images never materialise in memory; stderr\n *  and exit are drained concurrently so a missing image cannot look\n *  like a successful empty tar. */\nexport const saveImages = (\n\trefs: ReadonlyArray<string>,\n\topts: SaveImageOptions = {},\n): Stream.Stream<Uint8Array, DockerRuntimeError, DockerHost | DockerSpawner> => {\n\tconst mapSpawnError = (cause: unknown): DockerRuntimeError =>\n\t\tnew ImageSaveFailed({\n\t\t\tref: refs.join(' '),\n\t\t\tdetail:\n\t\t\t\trefs.length === 0 ? 'docker save called with no image refs' : 'docker save spawn failed',\n\t\t\tcause,\n\t\t});\n\tif (refs.length === 0) {\n\t\treturn Stream.fail(mapSpawnError(new Error('empty docker save ref list')));\n\t}\n\treturn Stream.unwrap(\n\t\tEffect.gen(function* () {\n\t\t\tconst host = yield* DockerHost;\n\t\t\tconst spawner = yield* DockerSpawner;\n\t\t\tconst cmd = dockerCommand(host, 'save', refs);\n\t\t\tconst handle = yield* spawner.spawn(cmd).pipe(Effect.mapError(mapSpawnError));\n\t\t\tconst stderrFiber = yield* Effect.forkChild(\n\t\t\t\tStream.mkString(Stream.decodeText(handle.stderr)).pipe(\n\t\t\t\t\tEffect.mapError(\n\t\t\t\t\t\t(cause): DockerRuntimeError =>\n\t\t\t\t\t\t\tnew ImageSaveFailed({\n\t\t\t\t\t\t\t\tref: refs.join(' '),\n\t\t\t\t\t\t\t\tdetail: 'docker save stderr drain failed',\n\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\t\t\tconst exitFiber = yield* Effect.forkChild(\n\t\t\t\thandle.exitCode.pipe(\n\t\t\t\t\tEffect.mapError(\n\t\t\t\t\t\t(cause): DockerRuntimeError =>\n\t\t\t\t\t\t\tnew ImageSaveFailed({\n\t\t\t\t\t\t\t\tref: refs.join(' '),\n\t\t\t\t\t\t\t\tdetail: 'docker save exit failed',\n\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\t\t\tconst checkExit = Effect.gen(function* () {\n\t\t\t\tconst [stderrText, exitCode] = yield* Effect.all(\n\t\t\t\t\t[Fiber.join(stderrFiber), Fiber.join(exitFiber)] as const,\n\t\t\t\t\t{ concurrency: 'unbounded' },\n\t\t\t\t);\n\t\t\t\tif (exitCode !== 0) {\n\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\tnew ImageSaveFailed({\n\t\t\t\t\t\t\tref: refs.join(' '),\n\t\t\t\t\t\t\tdetail: `docker save exited ${exitCode}${\n\t\t\t\t\t\t\t\tstderrText.length > 0 ? `: ${stderrText}` : ''\n\t\t\t\t\t\t\t}`,\n\t\t\t\t\t\t}),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t});\n\t\t\tconst cleanupTag =\n\t\t\t\topts.removeAfterSave === true\n\t\t\t\t\t? Effect.forEach(refs, cleanupSnapshotTempTag, { concurrency: 'unbounded' }).pipe(\n\t\t\t\t\t\t\tEffect.asVoid,\n\t\t\t\t\t\t)\n\t\t\t\t\t: Effect.void;\n\t\t\tconst cleanup = Effect.all(\n\t\t\t\t[cleanupTag, Fiber.interrupt(stderrFiber), Fiber.interrupt(exitFiber)],\n\t\t\t\t{ concurrency: 'unbounded' },\n\t\t\t).pipe(Effect.asVoid);\n\t\t\treturn handle.stdout.pipe(\n\t\t\t\tStream.mapError(\n\t\t\t\t\t(cause): DockerRuntimeError =>\n\t\t\t\t\t\tnew ImageSaveFailed({\n\t\t\t\t\t\t\tref: refs.join(' '),\n\t\t\t\t\t\t\tdetail: 'docker save stdout pipe failed',\n\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t}),\n\t\t\t\t),\n\t\t\t\tStream.onEnd(checkExit),\n\t\t\t\tStream.ensuring(cleanup),\n\t\t\t);\n\t\t}),\n\t);\n};\n\nexport const saveImage = (\n\tref: string,\n\topts: SaveImageOptions = {},\n): Stream.Stream<Uint8Array, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tsaveImages([ref], opts);\n\n// -----------------------------------------------------------------------------\n// Load (tar stream → image)\n// -----------------------------------------------------------------------------\n\n/** Parse `docker load` stdout lines to extract the loaded image refs.\n *  Docker's output is one of:\n *   - `Loaded image: <tag>`\n *   - `Loaded image ID: sha256:<digest>`\n *  Exported for direct testing without a docker dependency. */\nexport const parseLoadedRefs = (\n\tstdout: string,\n): ReadonlyArray<{ readonly tag?: string; readonly digest?: string }> => {\n\tconst refs: Array<{ tag?: string; digest?: string }> = [];\n\tfor (const rawLine of stdout.split(/\\r?\\n/)) {\n\t\tconst line = rawLine.trim();\n\t\tconst taggedMatch = /^Loaded image: (\\S+)$/.exec(line);\n\t\tif (taggedMatch?.[1]) {\n\t\t\trefs.push({ tag: taggedMatch[1] });\n\t\t\tcontinue;\n\t\t}\n\t\tconst digestMatch = /^Loaded image ID: (sha256:\\S+)$/.exec(line);\n\t\tif (digestMatch?.[1]) {\n\t\t\trefs.push({ digest: digestMatch[1] });\n\t\t}\n\t}\n\treturn refs;\n};\n\n/** `docker load < <tar-stream>`. Returns every freshly-loaded ref\n *  Docker reported on stdout. Symmetric with `saveImage`/`saveImages`.\n *  Upstream stream errors (e.g. file-read failures from a snapshot\n *  tar) are projected to `ImageLoadFailed` so callers see one shape.\n *\n *  Stdin lifetime: the supplied stream is fed in via the spawner's\n *  `stdin` sink under the same scope as the spawn itself; both close\n *  when the child exits. */\nexport const loadImage = (\n\ttar: Stream.Stream<Uint8Array, unknown>,\n): Effect.Effect<LoadedImageBundle, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst host = yield* DockerHost;\n\t\tconst spawner = yield* DockerSpawner;\n\t\tconst cmd = dockerCommand(host, 'load', []);\n\t\tconst mapSpawnError = (cause: unknown): DockerRuntimeError =>\n\t\t\tnew ImageLoadFailed({ detail: 'docker load spawn failed', cause });\n\t\treturn yield* Effect.scoped(\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst handle = yield* spawner.spawn(cmd).pipe(Effect.mapError(mapSpawnError));\n\t\t\t\t// Concurrently:\n\t\t\t\t//  - pump the supplied tar into stdin\n\t\t\t\t//  - drain stdout (the \"Loaded image: …\" lines)\n\t\t\t\t//  - drain stderr\n\t\t\t\t//  - wait for exit\n\t\t\t\tconst writeStdin = Stream.run(tar, handle.stdin).pipe(\n\t\t\t\t\tEffect.mapError(\n\t\t\t\t\t\t(cause: unknown): DockerRuntimeError =>\n\t\t\t\t\t\t\tnew ImageLoadFailed({ detail: 'docker load stdin pipe failed', cause }),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t\tconst stdoutDrain = Stream.mkString(Stream.decodeText(handle.stdout)).pipe(\n\t\t\t\t\tEffect.mapError(\n\t\t\t\t\t\t(cause): DockerRuntimeError =>\n\t\t\t\t\t\t\tnew ImageLoadFailed({ detail: 'docker load stdout drain failed', cause }),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t\tconst stderrDrain = Stream.mkString(Stream.decodeText(handle.stderr)).pipe(\n\t\t\t\t\tEffect.mapError(\n\t\t\t\t\t\t(cause): DockerRuntimeError =>\n\t\t\t\t\t\t\tnew ImageLoadFailed({ detail: 'docker load stderr drain failed', cause }),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t\tconst exit = handle.exitCode.pipe(\n\t\t\t\t\tEffect.mapError(\n\t\t\t\t\t\t(cause): DockerRuntimeError =>\n\t\t\t\t\t\t\tnew ImageLoadFailed({ detail: 'docker load exit failed', cause }),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t\tconst [, stdoutText, stderrText, exitCode] = yield* Effect.all(\n\t\t\t\t\t[writeStdin, stdoutDrain, stderrDrain, exit] as const,\n\t\t\t\t\t{ concurrency: 'unbounded' },\n\t\t\t\t);\n\t\t\t\tif (exitCode !== 0) {\n\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\tnew ImageLoadFailed({\n\t\t\t\t\t\t\tdetail: `docker load exited ${exitCode}`,\n\t\t\t\t\t\t\tstderr: stderrText,\n\t\t\t\t\t\t}),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tconst parsed = parseLoadedRefs(stdoutText);\n\t\t\t\tif (parsed.length === 0) {\n\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\tnew ImageLoadFailed({\n\t\t\t\t\t\t\tdetail: 'docker load succeeded but no Loaded image lines found',\n\t\t\t\t\t\t\tstderr: stdoutText,\n\t\t\t\t\t\t}),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tconst refs = yield* Effect.forEach(\n\t\t\t\t\tparsed,\n\t\t\t\t\t(ref) =>\n\t\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\t\tif (ref.digest !== undefined) {\n\t\t\t\t\t\t\t\treturn refOf(ref.digest, ref.tag);\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tconst digest = yield* imageExists(ref.tag!);\n\t\t\t\t\t\t\tif (digest === null) {\n\t\t\t\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\t\t\t\tnew ImageLoadFailed({\n\t\t\t\t\t\t\t\t\t\tdetail: `loaded image '${ref.tag}' not visible to inspect`,\n\t\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\treturn refOf(digest, ref.tag);\n\t\t\t\t\t\t}),\n\t\t\t\t\t{ concurrency: 'unbounded' },\n\t\t\t\t);\n\t\t\t\treturn { refs };\n\t\t\t}),\n\t\t);\n\t}).pipe(Effect.withSpan('runtime.docker.image.load'));\n\n// -----------------------------------------------------------------------------\n// Cache integration\n// -----------------------------------------------------------------------------\n\nexport interface CachedBuildKey {\n\treadonly namespace: string;\n\treadonly chain: ChainId;\n\treadonly contentHash: ContentHash;\n}\n\n/** Content-addressed image build:\n *\n *    1. cache lookup keyed by (namespace, chainId, contentHash)\n *    2. on hit, verify the on-host tag still resolves; if so return\n *    3. on miss, run `docker build`, then write the resolved digest\n *       to the cache (best-effort — write failure does not roll back\n *       the on-host build).\n *\n *  Caller-supplied tag is the content-addressed name; the cache key\n *  is independent so an unrelated invalidation (e.g. base-image\n *  bump) can drop the cache without disturbing the tag scheme. */\nexport const ensureImageCached = (\n\topts: BuildOptions,\n\tkey: CachedBuildKey,\n): Effect.Effect<string, DockerRuntimeError, CacheService | DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst cache = yield* CacheService;\n\t\tconst hit = yield* cache\n\t\t\t.lookup({ namespace: key.namespace, chain: key.chain, contentHash: key.contentHash })\n\t\t\t.pipe(\n\t\t\t\t// Cache-side failures collapse to MISS — the contract is\n\t\t\t\t// best-effort. We still build.\n\t\t\t\tEffect.catch(() => Effect.succeed(null)),\n\t\t\t);\n\t\tif (hit !== null) {\n\t\t\tconst cached = decodeDigest(hit.bytes);\n\t\t\tif (cached !== null) {\n\t\t\t\t// Verify the on-host tag still resolves to something —\n\t\t\t\t// the cached digest may have been pruned out from under us.\n\t\t\t\tconst existing = yield* imageExists(opts.tag);\n\t\t\t\tif (existing !== null) {\n\t\t\t\t\treturn existing;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\t// On-host tag-exists short-circuit (defence-in-depth).\n\t\tconst onHost = yield* imageExists(opts.tag);\n\t\tif (onHost !== null) {\n\t\t\tyield* cache\n\t\t\t\t.write(\n\t\t\t\t\t{ namespace: key.namespace, chain: key.chain, contentHash: key.contentHash },\n\t\t\t\t\tencodeDigest(onHost),\n\t\t\t\t)\n\t\t\t\t.pipe(Effect.catch(() => Effect.void));\n\t\t\treturn onHost;\n\t\t}\n\t\tconst digest = yield* build(opts);\n\t\tyield* cache\n\t\t\t.write(\n\t\t\t\t{ namespace: key.namespace, chain: key.chain, contentHash: key.contentHash },\n\t\t\t\tencodeDigest(digest),\n\t\t\t)\n\t\t\t.pipe(Effect.catch(() => Effect.void));\n\t\treturn digest;\n\t}).pipe(Effect.withSpan('runtime.docker.image.ensureCached'));\n\n// -----------------------------------------------------------------------------\n// Contract-shaped ImageRef helpers\n// -----------------------------------------------------------------------------\n\nexport const refOf = (digest: string, tag?: string): ImageRef =>\n\ttag !== undefined ? { digest, tag } : { digest };\n"],"mappings":"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"}

package/dist/runtime/docker/index.d.mts

@@ -0,0 +1 @@
+import { ContainerRuntimeService } from "./service.mjs";

package/dist/runtime/docker/inventory.d.mts

@@ -0,0 +1 @@
+import { Effect } from "effect";

package/dist/runtime/docker/inventory.mjs

@@ -0,0 +1,167 @@
+import { decodeJsonTextSync } from "../../substrate/runtime/runtime-decode.mjs";
+import { dockerRunOk } from "./client.mjs";
+import { LabelKey, renderFilterArgs } from "./labels.mjs";
+import { wrapGeneric } from "./wrap.mjs";
+import { Effect, Schema } from "effect";
+//#region src/runtime/docker/inventory.ts
+const PsLine = Schema.Struct({
+	ID: Schema.String,
+	Names: Schema.String,
+	Image: Schema.String,
+	Status: Schema.String,
+	State: Schema.String,
+	Labels: Schema.optional(Schema.String)
+});
+const ImagesLine = Schema.Struct({
+	ID: Schema.String,
+	Repository: Schema.String,
+	Tag: Schema.String,
+	Labels: Schema.optional(Schema.String)
+});
+const NetworksLine = Schema.Struct({
+	ID: Schema.String,
+	Name: Schema.String,
+	Driver: Schema.String,
+	Labels: Schema.optional(Schema.String)
+});
+const VolumesLine = Schema.Struct({
+	Name: Schema.String,
+	Driver: Schema.String,
+	Mountpoint: Schema.String,
+	Labels: Schema.optional(Schema.String)
+});
+const parseLabelString = (s) => {
+	if (!s) return {};
+	const out = {};
+	for (const part of s.split(",")) {
+		const i = part.indexOf("=");
+		if (i < 0) continue;
+		out[part.slice(0, i).trim()] = part.slice(i + 1).trim();
+	}
+	return out;
+};
+const parseJsonLines = (schema, stdout) => {
+	const lines = stdout.split("\n").filter((l) => l.trim().length > 0);
+	const out = [];
+	for (const [index, line] of lines.entries()) try {
+		out.push(decodeJsonTextSync(schema, line, {
+			source: `docker inventory:${index + 1}`,
+			mkError: (issue) => issue
+		}));
+	} catch {}
+	return out;
+};
+const toContainerSummaries = (stdout) => {
+	return parseJsonLines(PsLine, stdout).map((l) => ({
+		id: l.ID,
+		name: l.Names.split(",")[0] ?? l.Names,
+		image: l.Image,
+		status: l.Status,
+		state: l.State,
+		labels: parseLabelString(l.Labels)
+	}));
+};
+const toImageSummaries = (stdout) => {
+	return parseJsonLines(ImagesLine, stdout).map((l) => ({
+		id: l.ID,
+		tag: `${l.Repository}:${l.Tag}`,
+		labels: parseLabelString(l.Labels)
+	}));
+};
+const toNetworkSummaries = (stdout) => {
+	return parseJsonLines(NetworksLine, stdout).map((l) => ({
+		id: l.ID,
+		name: l.Name,
+		driver: l.Driver,
+		labels: parseLabelString(l.Labels)
+	}));
+};
+const toVolumeSummaries = (stdout) => {
+	return parseJsonLines(VolumesLine, stdout).map((l) => ({
+		name: l.Name,
+		driver: l.Driver,
+		mountpoint: l.Mountpoint,
+		labels: parseLabelString(l.Labels)
+	}));
+};
+const devstackAppFilterArgs = ["--filter", `label=${LabelKey.app}`];
+const devstackRouterFilterArgs = [
+	"--filter",
+	`label=${LabelKey.managed}=true`,
+	"--filter",
+	`label=${LabelKey.routerMarker}=true`
+];
+const listContainers = (match) => Effect.gen(function* () {
+	return toContainerSummaries((yield* dockerRunOk("ps", [
+		"-a",
+		"--format",
+		"{{json .}}",
+		...renderFilterArgs(match)
+	]).pipe(Effect.mapError(wrapGeneric("docker.ps")))).stdout);
+}).pipe(Effect.withSpan("runtime.docker.inventory.containers"));
+const listDevstackContainers = () => Effect.gen(function* () {
+	return toContainerSummaries((yield* dockerRunOk("ps", [
+		"-a",
+		"--format",
+		"{{json .}}",
+		...devstackAppFilterArgs
+	]).pipe(Effect.mapError(wrapGeneric("docker.ps")))).stdout);
+}).pipe(Effect.withSpan("runtime.docker.inventory.devstackContainers"));
+const listDevstackRouterContainers = () => Effect.gen(function* () {
+	return toContainerSummaries((yield* dockerRunOk("ps", [
+		"-a",
+		"--format",
+		"{{json .}}",
+		...devstackRouterFilterArgs
+	]).pipe(Effect.mapError(wrapGeneric("docker.ps")))).stdout);
+}).pipe(Effect.withSpan("runtime.docker.inventory.devstackRouterContainers"));
+const listImages = (match) => Effect.gen(function* () {
+	return toImageSummaries((yield* dockerRunOk("images", [
+		"--format",
+		"{{json .}}",
+		...renderFilterArgs(match)
+	]).pipe(Effect.mapError(wrapGeneric("docker.images")))).stdout);
+}).pipe(Effect.withSpan("runtime.docker.inventory.images"));
+const listDevstackImages = () => Effect.gen(function* () {
+	return toImageSummaries((yield* dockerRunOk("images", [
+		"--format",
+		"{{json .}}",
+		...devstackAppFilterArgs
+	]).pipe(Effect.mapError(wrapGeneric("docker.images")))).stdout);
+}).pipe(Effect.withSpan("runtime.docker.inventory.devstackImages"));
+const listNetworks = (match) => Effect.gen(function* () {
+	return toNetworkSummaries((yield* dockerRunOk("network", [
+		"ls",
+		"--format",
+		"{{json .}}",
+		...renderFilterArgs(match)
+	]).pipe(Effect.mapError(wrapGeneric("docker.network.ls")))).stdout);
+}).pipe(Effect.withSpan("runtime.docker.inventory.networks"));
+const listDevstackNetworks = () => Effect.gen(function* () {
+	return toNetworkSummaries((yield* dockerRunOk("network", [
+		"ls",
+		"--format",
+		"{{json .}}",
+		...devstackAppFilterArgs
+	]).pipe(Effect.mapError(wrapGeneric("docker.network.ls")))).stdout);
+}).pipe(Effect.withSpan("runtime.docker.inventory.devstackNetworks"));
+const listVolumes = (match) => Effect.gen(function* () {
+	return toVolumeSummaries((yield* dockerRunOk("volume", [
+		"ls",
+		"--format",
+		"{{json .}}",
+		...renderFilterArgs(match)
+	]).pipe(Effect.mapError(wrapGeneric("docker.volume.ls")))).stdout);
+}).pipe(Effect.withSpan("runtime.docker.inventory.volumes"));
+const listDevstackVolumes = () => Effect.gen(function* () {
+	return toVolumeSummaries((yield* dockerRunOk("volume", [
+		"ls",
+		"--format",
+		"{{json .}}",
+		...devstackAppFilterArgs
+	]).pipe(Effect.mapError(wrapGeneric("docker.volume.ls")))).stdout);
+}).pipe(Effect.withSpan("runtime.docker.inventory.devstackVolumes"));
+//#endregion
+export { listContainers, listDevstackContainers, listDevstackImages, listDevstackNetworks, listDevstackRouterContainers, listDevstackVolumes, listImages, listNetworks, listVolumes };
+
+//# sourceMappingURL=inventory.mjs.map

package/dist/runtime/docker/inventory.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"inventory.mjs","names":[],"sources":["../../../src/runtime/docker/inventory.ts"],"sourcesContent":["// Label-driven inventory.\n//\n// Architecture § Container runtime § Label-driven inventory:\n//   inventory NEVER greps stdout for container names; it ALWAYS\n//   filters by labels via `--filter label=...`. The output format is\n//   the `--format` JSON line shape, which we parse line-by-line.\n//\n// Surface:\n//   - `listContainers(match)` → ContainerSummary[]\n//   - `listImages(match)`     → ImageSummary[]\n//   - `listNetworks(match)`   → NetworkSummary[]\n//   - `listVolumes(match)`    → VolumeSummary[]\n\nimport { Effect, Schema } from 'effect';\n\nimport type { ContainerLabelTuple } from '../../contracts/snapshotable.ts';\nimport { decodeJsonTextSync } from '../../substrate/runtime/runtime-decode.ts';\nimport { DockerHost, DockerSpawner, dockerRunOk } from './client.ts';\nimport type { DockerRuntimeError } from './errors.ts';\nimport { LabelKey, renderFilterArgs } from './labels.ts';\nimport { wrapGeneric } from './wrap.ts';\n\n// -----------------------------------------------------------------------------\n// Summary shapes — what the label-filter listers return\n// -----------------------------------------------------------------------------\n\nexport interface ContainerSummary {\n\treadonly id: string;\n\treadonly name: string;\n\treadonly image: string;\n\treadonly status: string;\n\treadonly state: string;\n\treadonly labels: Readonly<Record<string, string>>;\n}\n\nexport interface ImageSummary {\n\treadonly id: string;\n\treadonly tag: string;\n\treadonly labels: Readonly<Record<string, string>>;\n}\n\nexport interface NetworkSummary {\n\treadonly id: string;\n\treadonly name: string;\n\treadonly driver: string;\n\treadonly labels: Readonly<Record<string, string>>;\n}\n\nexport interface VolumeSummary {\n\treadonly name: string;\n\treadonly driver: string;\n\treadonly mountpoint: string;\n\treadonly labels: Readonly<Record<string, string>>;\n}\n\n// -----------------------------------------------------------------------------\n// JSON-line schemas (docker --format '{{json .}}')\n// -----------------------------------------------------------------------------\n\nconst PsLine = Schema.Struct({\n\tID: Schema.String,\n\tNames: Schema.String,\n\tImage: Schema.String,\n\tStatus: Schema.String,\n\tState: Schema.String,\n\tLabels: Schema.optional(Schema.String),\n});\n\nconst ImagesLine = Schema.Struct({\n\tID: Schema.String,\n\tRepository: Schema.String,\n\tTag: Schema.String,\n\tLabels: Schema.optional(Schema.String),\n});\n\nconst NetworksLine = Schema.Struct({\n\tID: Schema.String,\n\tName: Schema.String,\n\tDriver: Schema.String,\n\tLabels: Schema.optional(Schema.String),\n});\n\nconst VolumesLine = Schema.Struct({\n\tName: Schema.String,\n\tDriver: Schema.String,\n\tMountpoint: Schema.String,\n\tLabels: Schema.optional(Schema.String),\n});\n\n// -----------------------------------------------------------------------------\n// Label parsing — docker's `Labels` field is a comma-joined `k=v,k=v`\n// -----------------------------------------------------------------------------\n\nconst parseLabelString = (s: string | undefined): Record<string, string> => {\n\tif (!s) return {};\n\tconst out: Record<string, string> = {};\n\tfor (const part of s.split(',')) {\n\t\tconst i = part.indexOf('=');\n\t\tif (i < 0) continue;\n\t\tout[part.slice(0, i).trim()] = part.slice(i + 1).trim();\n\t}\n\treturn out;\n};\n\nconst parseJsonLines = <S extends Schema.Decoder<unknown>>(\n\tschema: S,\n\tstdout: string,\n): ReadonlyArray<S['Type']> => {\n\tconst lines = stdout.split('\\n').filter((l) => l.trim().length > 0);\n\tconst out: Array<S['Type']> = [];\n\tfor (const [index, line] of lines.entries()) {\n\t\ttry {\n\t\t\tout.push(\n\t\t\t\tdecodeJsonTextSync(schema, line, {\n\t\t\t\t\tsource: `docker inventory:${index + 1}`,\n\t\t\t\t\tmkError: (issue) => issue,\n\t\t\t\t}),\n\t\t\t);\n\t\t} catch {\n\t\t\t// Malformed line — skip. Inventory is best-effort; a single\n\t\t\t// torn line shouldn't poison the whole sweep.\n\t\t}\n\t}\n\treturn out;\n};\n\n// -----------------------------------------------------------------------------\n// Listers\n// -----------------------------------------------------------------------------\n\nconst toContainerSummaries = (stdout: string): ReadonlyArray<ContainerSummary> => {\n\tconst lines = parseJsonLines(PsLine, stdout);\n\treturn lines.map(\n\t\t(l): ContainerSummary => ({\n\t\t\tid: l.ID,\n\t\t\tname: l.Names.split(',')[0] ?? l.Names,\n\t\t\timage: l.Image,\n\t\t\tstatus: l.Status,\n\t\t\tstate: l.State,\n\t\t\tlabels: parseLabelString(l.Labels),\n\t\t}),\n\t);\n};\n\nconst toImageSummaries = (stdout: string): ReadonlyArray<ImageSummary> => {\n\tconst lines = parseJsonLines(ImagesLine, stdout);\n\treturn lines.map(\n\t\t(l): ImageSummary => ({\n\t\t\tid: l.ID,\n\t\t\ttag: `${l.Repository}:${l.Tag}`,\n\t\t\tlabels: parseLabelString(l.Labels),\n\t\t}),\n\t);\n};\n\nconst toNetworkSummaries = (stdout: string): ReadonlyArray<NetworkSummary> => {\n\tconst lines = parseJsonLines(NetworksLine, stdout);\n\treturn lines.map(\n\t\t(l): NetworkSummary => ({\n\t\t\tid: l.ID,\n\t\t\tname: l.Name,\n\t\t\tdriver: l.Driver,\n\t\t\tlabels: parseLabelString(l.Labels),\n\t\t}),\n\t);\n};\n\nconst toVolumeSummaries = (stdout: string): ReadonlyArray<VolumeSummary> => {\n\tconst lines = parseJsonLines(VolumesLine, stdout);\n\treturn lines.map(\n\t\t(l): VolumeSummary => ({\n\t\t\tname: l.Name,\n\t\t\tdriver: l.Driver,\n\t\t\tmountpoint: l.Mountpoint,\n\t\t\tlabels: parseLabelString(l.Labels),\n\t\t}),\n\t);\n};\n\nconst devstackAppFilterArgs: ReadonlyArray<string> = ['--filter', `label=${LabelKey.app}`];\nconst devstackRouterFilterArgs: ReadonlyArray<string> = [\n\t'--filter',\n\t`label=${LabelKey.managed}=true`,\n\t'--filter',\n\t`label=${LabelKey.routerMarker}=true`,\n];\n\nexport const listContainers = (\n\tmatch: Partial<ContainerLabelTuple>,\n): Effect.Effect<ReadonlyArray<ContainerSummary>, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst filters = renderFilterArgs(match);\n\t\tconst res = yield* dockerRunOk('ps', ['-a', '--format', '{{json .}}', ...filters]).pipe(\n\t\t\tEffect.mapError(wrapGeneric('docker.ps')),\n\t\t);\n\t\treturn toContainerSummaries(res.stdout);\n\t}).pipe(Effect.withSpan('runtime.docker.inventory.containers'));\n\nexport const listDevstackContainers = (): Effect.Effect<\n\tReadonlyArray<ContainerSummary>,\n\tDockerRuntimeError,\n\tDockerHost | DockerSpawner\n> =>\n\tEffect.gen(function* () {\n\t\tconst res = yield* dockerRunOk('ps', [\n\t\t\t'-a',\n\t\t\t'--format',\n\t\t\t'{{json .}}',\n\t\t\t...devstackAppFilterArgs,\n\t\t]).pipe(Effect.mapError(wrapGeneric('docker.ps')));\n\t\treturn toContainerSummaries(res.stdout);\n\t}).pipe(Effect.withSpan('runtime.docker.inventory.devstackContainers'));\n\nexport const listDevstackRouterContainers = (): Effect.Effect<\n\tReadonlyArray<ContainerSummary>,\n\tDockerRuntimeError,\n\tDockerHost | DockerSpawner\n> =>\n\tEffect.gen(function* () {\n\t\tconst res = yield* dockerRunOk('ps', [\n\t\t\t'-a',\n\t\t\t'--format',\n\t\t\t'{{json .}}',\n\t\t\t...devstackRouterFilterArgs,\n\t\t]).pipe(Effect.mapError(wrapGeneric('docker.ps')));\n\t\treturn toContainerSummaries(res.stdout);\n\t}).pipe(Effect.withSpan('runtime.docker.inventory.devstackRouterContainers'));\n\nexport const listImages = (\n\tmatch: Partial<ContainerLabelTuple>,\n): Effect.Effect<ReadonlyArray<ImageSummary>, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst filters = renderFilterArgs(match);\n\t\tconst res = yield* dockerRunOk('images', ['--format', '{{json .}}', ...filters]).pipe(\n\t\t\tEffect.mapError(wrapGeneric('docker.images')),\n\t\t);\n\t\treturn toImageSummaries(res.stdout);\n\t}).pipe(Effect.withSpan('runtime.docker.inventory.images'));\n\nexport const listDevstackImages = (): Effect.Effect<\n\tReadonlyArray<ImageSummary>,\n\tDockerRuntimeError,\n\tDockerHost | DockerSpawner\n> =>\n\tEffect.gen(function* () {\n\t\tconst res = yield* dockerRunOk('images', [\n\t\t\t'--format',\n\t\t\t'{{json .}}',\n\t\t\t...devstackAppFilterArgs,\n\t\t]).pipe(Effect.mapError(wrapGeneric('docker.images')));\n\t\treturn toImageSummaries(res.stdout);\n\t}).pipe(Effect.withSpan('runtime.docker.inventory.devstackImages'));\n\nexport const listNetworks = (\n\tmatch: Partial<ContainerLabelTuple>,\n): Effect.Effect<ReadonlyArray<NetworkSummary>, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst filters = renderFilterArgs(match);\n\t\tconst res = yield* dockerRunOk('network', ['ls', '--format', '{{json .}}', ...filters]).pipe(\n\t\t\tEffect.mapError(wrapGeneric('docker.network.ls')),\n\t\t);\n\t\treturn toNetworkSummaries(res.stdout);\n\t}).pipe(Effect.withSpan('runtime.docker.inventory.networks'));\n\nexport const listDevstackNetworks = (): Effect.Effect<\n\tReadonlyArray<NetworkSummary>,\n\tDockerRuntimeError,\n\tDockerHost | DockerSpawner\n> =>\n\tEffect.gen(function* () {\n\t\tconst res = yield* dockerRunOk('network', [\n\t\t\t'ls',\n\t\t\t'--format',\n\t\t\t'{{json .}}',\n\t\t\t...devstackAppFilterArgs,\n\t\t]).pipe(Effect.mapError(wrapGeneric('docker.network.ls')));\n\t\treturn toNetworkSummaries(res.stdout);\n\t}).pipe(Effect.withSpan('runtime.docker.inventory.devstackNetworks'));\n\nexport const listVolumes = (\n\tmatch: Partial<ContainerLabelTuple>,\n): Effect.Effect<ReadonlyArray<VolumeSummary>, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst filters = renderFilterArgs(match);\n\t\tconst res = yield* dockerRunOk('volume', ['ls', '--format', '{{json .}}', ...filters]).pipe(\n\t\t\tEffect.mapError(wrapGeneric('docker.volume.ls')),\n\t\t);\n\t\treturn toVolumeSummaries(res.stdout);\n\t}).pipe(Effect.withSpan('runtime.docker.inventory.volumes'));\n\nexport const listDevstackVolumes = (): Effect.Effect<\n\tReadonlyArray<VolumeSummary>,\n\tDockerRuntimeError,\n\tDockerHost | DockerSpawner\n> =>\n\tEffect.gen(function* () {\n\t\tconst res = yield* dockerRunOk('volume', [\n\t\t\t'ls',\n\t\t\t'--format',\n\t\t\t'{{json .}}',\n\t\t\t...devstackAppFilterArgs,\n\t\t]).pipe(Effect.mapError(wrapGeneric('docker.volume.ls')));\n\t\treturn toVolumeSummaries(res.stdout);\n\t}).pipe(Effect.withSpan('runtime.docker.inventory.devstackVolumes'));\n"],"mappings":"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"}

package/dist/runtime/docker/labels.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/runtime/docker/labels.mjs

@@ -0,0 +1,97 @@
+//#region src/runtime/docker/labels.ts
+/** Canonical label keys. Single source of truth. */
+const LabelKey = {
+	app: "devstack.app",
+	stack: "devstack.stack",
+	plugin: "devstack.plugin",
+	role: "devstack.role",
+	cycle: "devstack.cycle",
+	configHash: "devstack.config-hash",
+	managed: "devstack.managed",
+	networkMarker: "devstack.network",
+	volumeMarker: "devstack.volume",
+	routerMarker: "devstack.router",
+	routerProfile: "devstack.router.profile",
+	routerSpecVersion: "devstack.router.spec-version"
+};
+/** Docker Compose-compatible labels used only for Docker Desktop grouping.
+*  Cleanup and inventory remain keyed by `LabelKey` above. */
+const ComposeLabelKey = {
+	project: "com.docker.compose.project",
+	service: "com.docker.compose.service",
+	containerNumber: "com.docker.compose.container-number",
+	version: "com.docker.compose.version",
+	oneoff: "com.docker.compose.oneoff",
+	network: "com.docker.compose.network",
+	volume: "com.docker.compose.volume"
+};
+const COMPOSE_UI_VERSION = "2.0.0";
+const normalizeComposeSegment = (value) => {
+	const normalized = value.trim().replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+	return normalized.length > 0 ? normalized : "unnamed";
+};
+const composeProjectId = (app, stack) => `${normalizeComposeSegment(app)}-${normalizeComposeSegment(stack)}`;
+const composeServiceId = (tuple) => `${normalizeComposeSegment(tuple.plugin)}.${normalizeComposeSegment(tuple.role)}`;
+const renderComposeContainerLabels = (tuple) => [
+	`${ComposeLabelKey.project}=${composeProjectId(tuple.app, tuple.stack)}`,
+	`${ComposeLabelKey.service}=${composeServiceId(tuple)}`,
+	`${ComposeLabelKey.containerNumber}=1`,
+	`${ComposeLabelKey.version}=${COMPOSE_UI_VERSION}`,
+	`${ComposeLabelKey.oneoff}=False`
+];
+const renderComposeNetworkLabels = (name, app, stack) => [
+	`${ComposeLabelKey.project}=${composeProjectId(app, stack)}`,
+	`${ComposeLabelKey.network}=${name}`,
+	`${ComposeLabelKey.version}=${COMPOSE_UI_VERSION}`
+];
+const expectedContainerOwnershipLabels = (tuple) => ({
+	[LabelKey.managed]: "true",
+	[LabelKey.app]: tuple.app,
+	[LabelKey.stack]: tuple.stack,
+	[LabelKey.plugin]: tuple.plugin,
+	[LabelKey.role]: tuple.role
+});
+const expectedNetworkOwnershipLabels = (app, stack) => ({
+	[LabelKey.managed]: "true",
+	[LabelKey.networkMarker]: "true",
+	[LabelKey.app]: app,
+	[LabelKey.stack]: stack
+});
+const ownershipMismatchDetail = (expected, actual) => {
+	const mismatches = [];
+	for (const [key, expectedValue] of Object.entries(expected)) {
+		const actualValue = actual[key];
+		if (actualValue !== expectedValue) mismatches.push(`${key}: expected ${expectedValue}, found ${actualValue ?? "<missing>"}`);
+	}
+	return mismatches.length === 0 ? null : mismatches.join("; ");
+};
+/** Render a `ContainerLabelTuple` to docker `--label key=value` pairs.
+*  The cycle/managed labels are stamped at create time by `container.ts`. */
+const renderContainerLabels = (tuple, cycle, extra = {}) => {
+	return [...[
+		...Object.entries(expectedContainerOwnershipLabels(tuple)).map(([key, value]) => `${key}=${value}`),
+		`${LabelKey.cycle}=${cycle}`,
+		...Object.entries(extra).map(([key, value]) => `${key}=${value}`)
+	], ...renderComposeContainerLabels(tuple)];
+};
+/** Render a label-tuple as `--filter label=key=value` args for `docker ps`,
+*  `docker volume ls`, etc. Partial tuples allowed (sweep / inventory). */
+const renderFilterArgs = (match, extra = {}) => {
+	const filters = [`label=${LabelKey.managed}=true`];
+	if (match.app !== void 0) filters.push(`label=${LabelKey.app}=${match.app}`);
+	if (match.stack !== void 0) filters.push(`label=${LabelKey.stack}=${match.stack}`);
+	if (match.plugin !== void 0) filters.push(`label=${LabelKey.plugin}=${match.plugin}`);
+	if (match.role !== void 0) filters.push(`label=${LabelKey.role}=${match.role}`);
+	for (const [k, v] of Object.entries(extra)) filters.push(`label=${k}=${v}`);
+	return filters.flatMap((f) => ["--filter", f]);
+};
+/** Network-specific labels (shared `devstack` network is cross-stack;
+*  per-stack networks would stamp the full tuple). */
+const renderNetworkLabels = (name, app, stack, opts = {}) => {
+	const ownership = Object.entries(expectedNetworkOwnershipLabels(app, stack)).map(([key, value]) => `${key}=${value}`);
+	return opts.composeUi === false ? ownership : [...ownership, ...renderComposeNetworkLabels(name, app, stack)];
+};
+//#endregion
+export { ComposeLabelKey, LabelKey, expectedContainerOwnershipLabels, expectedNetworkOwnershipLabels, ownershipMismatchDetail, renderContainerLabels, renderFilterArgs, renderNetworkLabels };
+
+//# sourceMappingURL=labels.mjs.map