@stream44.studio/t44-docker.com 0.1.0-rc.3

package/.repo-identifier

@@ -0,0 +1 @@
+did:repo:e3a028ddf2e2061c350dc3146a22165b667d93eb

package/DCO.md

@@ -0,0 +1,34 @@
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.

package/LICENSE.txt

@@ -0,0 +1,23 @@
+MIT License
+
+Docker Tools for Terminal44 Workspace
+
+Copyright 2026 Christoph Dorn - https://Christoph.diy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+<table>
+  <tr>
+    <td><a href="https://Stream44.Studio"><img src=".o/stream44.studio/assets/Icon-v1.svg" width="42" height="42"></a></td>
+    <td><strong><a href="https://Stream44.Studio">Stream44 Studio</a></strong><br/>Open Development Project</td>
+    <td>Preview release for community feedback.<br/>Get in touch on <a href="https://discord.gg/9eBcQXEJAN">discord</a>.</td>
+  </tr>
+</table>
+
+⚠️ **Disclaimer:** Under active development. Code has not been audited. APIs and interfaces are subject to change!
+
+`t44` Capsules for Docker [![Tests](https://github.com/Stream44/t44-docker.com/actions/workflows/test.yaml/badge.svg)](https://github.com/Stream44/t44-docker.com/actions/workflows/test.yaml?query=branch%3Amain)
+===
+
+This project [encapsulates](https://github.com/Stream44/encapsulate) the `docker` command-line tool from [Docker](https://docker.com/) for use in [t44](https://github.com/Stream44/t44).
+
+
+Capsules: High Level
+---
+
+### `Project`
+
+A curated API to build and run docker for a directory. Combines `Cli`, `Image` and `Container` capsules for a seamless developer experience.
+
+Capsules: Low Level
+---
+
+### `Hub`
+
+Utilities for working with [hub.docker.com](https://hub.docker.com).
+
+### `Image`
+
+Lifecycle methods for a **Docker Image**.
+
+### `ImageContext`
+
+Configurations for a spcific docker image.
+
+### `Container`
+
+Lifecycle methods for a **Docker Container**.
+
+### `ContainerContext`
+
+Configurations for a spcific docker container.
+
+### `Cli`
+
+Utility to wrap `docker` command-line tool.
+
+### `Containers`
+
+Utilities for working with containers in docker.
+
+
+Provenance
+===
+
+[![Gordian Open Integrity](https://github.com/Stream44/t44-docker.com/actions/workflows/gordian-open-integrity.yaml/badge.svg)](https://github.com/Stream44/t44-docker.com/actions/workflows/gordian-open-integrity.yaml?query=branch%3Amain) [![DCO Signatures](https://github.com/Stream44/t44-docker.com/actions/workflows/dco.yaml/badge.svg)](https://github.com/Stream44/t44-docker.com/actions/workflows/dco.yaml?query=branch%3Amain)
+
+Repository DID: `did:repo:e3a028ddf2e2061c350dc3146a22165b667d93eb`
+
+<table>
+  <tr>
+    <td><strong>Inception Mark</strong></td>
+    <td><img src=".o/GordianOpenIntegrity-InceptionLifehash.svg" width="64" height="64"></td>
+    <td><strong>Current Mark</strong></td>
+    <td><img src=".o/GordianOpenIntegrity-CurrentLifehash.svg" width="64" height="64"></td>
+    <td>Trust established using<br/><a href="https://github.com/Stream44/t44-blockchaincommons.com">Stream44/t44-BlockchainCommons.com</a></td>
+  </tr>
+</table>
+
+(c) 2026 [Christoph.diy](https://christoph.diy) • Code: [MIT](./LICENSE.txt) • Text: [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) • Created with [Stream44.Studio](https://Stream44.Studio)

package/caps/Cli.test.ts

@@ -0,0 +1,116 @@
+#!/usr/bin/env bun test
+
+import * as bunTest from 'bun:test'
+import { run } from 't44/standalone-rt'
+
+const {
+    test: { describe, it, expect },
+    cli,
+} = await run(async ({ encapsulate, CapsulePropertyTypes, makeImportStack }: any) => {
+    const spine = await encapsulate({
+        '#@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0': {
+            '#@stream44.studio/encapsulate/structs/Capsule': {},
+            '#': {
+                test: {
+                    type: CapsulePropertyTypes.Mapping,
+                    value: 't44/caps/ProjectTest',
+                    options: {
+                        '#': {
+                            bunTest,
+                            env: {}
+                        }
+                    }
+                },
+                cli: {
+                    type: CapsulePropertyTypes.Mapping,
+                    value: './Cli',
+                },
+            }
+        }
+    }, {
+        importMeta: import.meta,
+        importStack: makeImportStack(),
+        capsuleName: '@stream44.studio/t44-docker.com/caps/Cli.test'
+    })
+    return { spine }
+}, async ({ spine, apis }: any) => {
+    return apis[spine.capsuleSourceLineRef]
+}, {
+    importMeta: import.meta
+})
+
+describe('Cli Capsule', () => {
+
+    describe('Platform Utils', () => {
+        it('getCurrentPlatform should return valid platform', () => {
+            const platform = cli.getCurrentPlatform();
+            expect(['arm64', 'amd64']).toContain(platform);
+        });
+
+        it('getCurrentPlatformArch should return valid arch key', () => {
+            const archKey = cli.getCurrentPlatformArch();
+            expect(['linux-arm64', 'linux-x64']).toContain(archKey);
+        });
+
+        it('getCurrentPlatformArch should match getCurrentPlatform', () => {
+            const platform = cli.getCurrentPlatform();
+            const archKey = cli.getCurrentPlatformArch();
+            if (platform === 'arm64') {
+                expect(archKey).toBe('linux-arm64');
+            } else {
+                expect(archKey).toBe('linux-x64');
+            }
+        });
+    });
+
+    describe('DOCKER_ARCHS', () => {
+        it('should have correct structure', () => {
+            expect(cli.DOCKER_ARCHS).toBeDefined();
+            expect(cli.DOCKER_ARCHS['linux-arm64']).toBeDefined();
+            expect(cli.DOCKER_ARCHS['linux-x64']).toBeDefined();
+
+            expect(cli.DOCKER_ARCHS['linux-arm64'].archDir).toBe('linux-arm64');
+            expect(cli.DOCKER_ARCHS['linux-arm64'].arch).toBe('arm64');
+            expect(cli.DOCKER_ARCHS['linux-arm64'].os).toBe('linux');
+
+            expect(cli.DOCKER_ARCHS['linux-x64'].archDir).toBe('linux-x64');
+            expect(cli.DOCKER_ARCHS['linux-x64'].arch).toBe('amd64');
+            expect(cli.DOCKER_ARCHS['linux-x64'].os).toBe('linux');
+        });
+
+        it('keys should match archDir values', () => {
+            for (const [key, value] of Object.entries(cli.DOCKER_ARCHS) as any) {
+                expect(key).toBe(value.archDir);
+            }
+        });
+    });
+
+    describe('exec', () => {
+        it('should execute docker version', async () => {
+            const result = await cli.exec(['version', '--format', '{{.Client.Version}}']);
+            expect(result).toBeTruthy();
+            expect(typeof result).toBe('string');
+        });
+
+        it('should execute docker info format', async () => {
+            const result = await cli.exec(['info', '--format', '{{.OSType}}']);
+            expect(result).toBe('linux');
+        });
+    });
+
+    describe('tagImage', () => {
+        it('should tag an image', async () => {
+            // Pull a small image to test with
+            await cli.exec(['pull', 'hello-world']);
+            await cli.tagImage({
+                sourceImage: 'hello-world',
+                targetImage: 'test-cli-tag:latest',
+            });
+            // Verify the tag exists
+            const result = await cli.exec(['images', 'test-cli-tag:latest', '--format', '{{.Repository}}:{{.Tag}}']);
+            expect(result).toContain('test-cli-tag:latest');
+            // Cleanup
+            await cli.exec(['rmi', 'test-cli-tag:latest']);
+        });
+    });
+});

package/caps/Cli.ts

@@ -0,0 +1,134 @@
+import { $ } from 'bun'
+import * as path from 'path'
+
+/**
+ * Docker architectures configuration
+ * Keys are the architecture directory names, values contain metadata
+ */
+const DOCKER_ARCHS = {
+    'linux-arm64': { archDir: 'linux-arm64', arch: 'arm64', os: 'linux' },
+    'linux-x64': { archDir: 'linux-x64', arch: 'amd64', os: 'linux' },
+} as const;
+
+export async function capsule({
+    encapsulate,
+    CapsulePropertyTypes,
+    makeImportStack
+}: {
+    encapsulate: any
+    CapsulePropertyTypes: any
+    makeImportStack: any
+}) {
+
+    return encapsulate({
+        '#@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0': {
+            '#@stream44.studio/encapsulate/structs/Capsule': {},
+            '#': {
+                verbose: {
+                    type: CapsulePropertyTypes.Literal,
+                    value: false,
+                },
+
+                DOCKER_ARCHS: {
+                    type: CapsulePropertyTypes.Constant,
+                    value: DOCKER_ARCHS,
+                },
+
+                /**
+                 * Get the current architecture platform
+                 */
+                getCurrentPlatform: {
+                    type: CapsulePropertyTypes.Function,
+                    value: function (this: any): 'arm64' | 'amd64' {
+                        const arch = process.arch;
+                        if (arch === 'arm64') {
+                            return 'arm64';
+                        }
+                        return 'amd64';
+                    }
+                },
+
+                /**
+                 * Get the current platform's architecture key for DOCKER_ARCHS
+                 */
+                getCurrentPlatformArch: {
+                    type: CapsulePropertyTypes.Function,
+                    value: function (this: any): keyof typeof DOCKER_ARCHS {
+                        const platform = this.getCurrentPlatform();
+                        return platform === 'arm64' ? 'linux-arm64' : 'linux-x64';
+                    }
+                },
+
+                /**
+                 * Core exec method — ALL Docker CLI calls go through here.
+                 * Returns trimmed stdout text.
+                 */
+                exec: {
+                    type: CapsulePropertyTypes.Function,
+                    value: async function (this: any, args: string[], options?: { stdin?: string; retry?: number | boolean; retryDelayMs?: number }): Promise<string> {
+                        const maxAttempts = options?.retry === true ? 3 : (options?.retry || 1);
+                        const delayMs = options?.retryDelayMs ?? 5000;
+
+                        const attempt = async (): Promise<string> => {
+                            if (this.verbose) {
+                                console.log(`[docker] Executing: docker ${args.join(' ')}`);
+                            }
+                            if (options?.stdin !== undefined) {
+                                const proc = Bun.spawn(['docker', ...args], {
+                                    stdin: 'pipe',
+                                    stdout: 'pipe',
+                                    stderr: 'pipe',
+                                });
+                                proc.stdin.write(options.stdin);
+                                proc.stdin.end();
+                                const [stdout, stderr] = await Promise.all([
+                                    new Response(proc.stdout).text(),
+                                    new Response(proc.stderr).text(),
+                                ]);
+                                await proc.exited;
+                                if (proc.exitCode !== 0) {
+                                    throw new Error(`docker ${args[0]} failed (exit ${proc.exitCode}): ${stderr}`);
+                                }
+                                return stdout.trim();
+                            }
+                            const result = await $`docker ${args}`.text();
+                            return result.trim();
+                        };
+
+                        let lastError: unknown;
+                        for (let i = 1; i <= maxAttempts; i++) {
+                            try {
+                                return await attempt();
+                            } catch (err) {
+                                lastError = err;
+                                if (i < maxAttempts) {
+                                    console.error(`  ⚠️  docker ${args[0]} attempt ${i}/${maxAttempts} failed, retrying in ${delayMs / 1000}s...`);
+                                    await new Promise(r => setTimeout(r, delayMs));
+                                }
+                            }
+                        }
+                        throw lastError;
+                    }
+                },
+
+                /**
+                 * Tag a Docker image — shared by Image and Context capsules
+                 */
+                tagImage: {
+                    type: CapsulePropertyTypes.Function,
+                    value: async function (this: any, options: { sourceImage: string; targetImage: string }): Promise<string> {
+                        const { sourceImage, targetImage } = options;
+                        if (this.verbose) {
+                            console.log(`[docker:tagImage] Tagging image: ${sourceImage} -> ${targetImage}`);
+                        }
+                        return await this.exec(['tag', sourceImage, targetImage]);
+                    }
+                },
+            }
+        }
+    }, {
+        importMeta: import.meta,
+        importStack: makeImportStack(),
+        capsuleName: '@stream44.studio/t44-docker.com/caps/Cli',
+    })
+}

package/caps/Container.test.ts

@@ -0,0 +1,168 @@
+#!/usr/bin/env bun test --timeout 120000
+
+import * as bunTest from 'bun:test'
+import { run } from 't44/standalone-rt'
+import { join } from 'path'
+import { mkdir, writeFile } from 'fs/promises'
+
+const {
+    test: { describe, it, expect, workbenchDir },
+    container,
+    image,
+} = await run(async ({ encapsulate, CapsulePropertyTypes, makeImportStack }: any) => {
+    const spine = await encapsulate({
+        '#@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0': {
+            '#@stream44.studio/encapsulate/structs/Capsule': {},
+            '#': {
+                test: {
+                    type: CapsulePropertyTypes.Mapping,
+                    value: 't44/caps/ProjectTest',
+                    options: {
+                        '#': {
+                            bunTest,
+                            env: {}
+                        }
+                    }
+                },
+                container: {
+                    type: CapsulePropertyTypes.Mapping,
+                    value: './Container',
+                },
+                image: {
+                    type: CapsulePropertyTypes.Mapping,
+                    value: './Image',
+                },
+            }
+        }
+    }, {
+        importMeta: import.meta,
+        importStack: makeImportStack(),
+        capsuleName: '@stream44.studio/t44-docker.com/caps/Container.test'
+    })
+    return { spine }
+}, async ({ spine, apis }: any) => {
+    return apis[spine.capsuleSourceLineRef]
+}, {
+    importMeta: import.meta
+})
+
+/**
+ * Create a minimal test app and build a Docker image for container tests
+ */
+async function buildTestImage(baseDir: string, org: string, repo: string): Promise<string> {
+    await mkdir(baseDir, { recursive: true });
+
+    await writeFile(join(baseDir, 'index.ts'), `
+const server = Bun.serve({
+    port: 3000,
+    fetch(req) {
+        return new Response("Hello from container test!");
+    },
+});
+console.log("READY");
+console.log(\`Server running on port \${server.port}\`);
+`);
+
+    await writeFile(join(baseDir, 'package.json'), JSON.stringify({
+        name: 'container-test-app',
+        version: '0.1.0',
+        scripts: {
+            start: 'bun run index.ts'
+        }
+    }, null, 2));
+
+    image.context.organization = org;
+    image.context.repository = repo;
+    image.context.appBaseDir = baseDir;
+    image.context.buildContextBaseDir = join(baseDir, '.~o/t44-docker.com');
+    image.context.verbose = false;
+
+    const currentArch = image.cli.getCurrentPlatformArch();
+    const result = await image.buildVariant({ variant: 'alpine', arch: currentArch });
+    return result.imageTag;
+}
+
+describe('Container Capsule', () => {
+
+    describe('run / stop / cleanup', () => {
+        it('should run, verify, and cleanup a container', async () => {
+            const appDir = join(workbenchDir, 'container-run-test');
+            const imageTag = await buildTestImage(appDir, 'test-docker-com', 'container-run-test');
+
+            // Configure container via derive() and pass to run()
+            const containerContext = container.context.derive({
+                image: imageTag,
+                name: `t44-docker-test-${Date.now()}`,
+                ports: [{ internal: 3000, external: 13579 }],
+                detach: true,
+                waitFor: 'READY',
+                waitTimeout: 30000,
+                verbose: false,
+                showOutput: false,
+            });
+            // Ensure no leftover container from a previous run
+            await container.ensureStopped(containerContext);
+
+            // Run — stores _containerId internally
+            const containerId = await container.run(containerContext);
+            expect(containerId).toBeTruthy();
+
+            // Verify running
+            const isRunning = await container.isRunning({
+                ...containerContext,
+                retryDelayMs: 1000,
+                requestTimeoutMs: 5000,
+                timeoutMs: 30000,
+            });
+            expect(isRunning).toBe(true);
+
+            // List
+            const containers = await container.list(containerContext);
+            expect(containers.length).toBeGreaterThan(0);
+
+            // Cleanup
+            await container.cleanup(containerContext);
+
+            // Cleanup image
+            await image.removeImage({ image: imageTag, force: true }).catch(() => { });
+        }, 120000);
+    });
+
+    describe('ensureStopped', () => {
+        it('should remove existing container with same name', async () => {
+            const appDir = join(workbenchDir, 'container-ensure-test');
+            const imageTag = await buildTestImage(appDir, 'test-docker-com', 'container-ensure-test');
+
+            const containerName = `t44-docker-ensure-${Date.now()}`;
+
+            // Start a container via derive()
+            const containerContext = container.context.derive({
+                image: imageTag,
+                name: containerName,
+                ports: [{ internal: 3000, external: 13580 }],
+                detach: true,
+                waitFor: 'READY',
+                waitTimeout: 30000,
+                verbose: false,
+                showOutput: false,
+            });
+            const containerId = await container.run(containerContext);
+            expect(containerId).toBeTruthy();
+
+            // ensureStopped should remove it
+            await container.ensureStopped(containerContext);
+
+            // Verify it's gone
+            const output = await container.containers.list({
+                all: true,
+                filter: `name=${containerName}`,
+                format: '{{.Names}}',
+            });
+            const lines = (output as string).split('\n').filter((l: string) => l.trim() === containerName);
+            expect(lines.length).toBe(0);
+
+            // Cleanup image
+            await image.removeImage({ image: imageTag, force: true }).catch(() => { });
+        }, 120000);
+    });
+});