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

package/caps/Project.ts

@@ -0,0 +1,304 @@
+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': {},
+            '#': {
+                test: {
+                    type: CapsulePropertyTypes.Mapping,
+                    value: 't44/caps/ProjectTest',
+                },
+
+                cli: {
+                    type: CapsulePropertyTypes.Mapping,
+                    value: './Cli',
+                },
+
+                image: {
+                    type: CapsulePropertyTypes.Mapping,
+                    value: './Image',
+                    options: { /* requires new instance */ },
+                },
+
+                container: {
+                    type: CapsulePropertyTypes.Mapping,
+                    value: './Container',
+                    options: { /* requires new instance */ },
+                },
+
+                // --- Project-level config ---
+
+                dispose: {
+                    type: CapsulePropertyTypes.Literal,
+                    value: false as boolean,
+                },
+
+                // Internal state
+                _devContainerId: {
+                    type: CapsulePropertyTypes.Literal,
+                    value: undefined as string | undefined,
+                },
+
+                /**
+                 * Get development container configuration as a derived ContainerContext plain object.
+                 * Merges dev defaults (image tag, sanitized name, detach, waitFor) on top of
+                 * whatever is already configured on container.context.
+                 */
+                getDevelopmentContainerConfig: {
+                    type: CapsulePropertyTypes.Function,
+                    value: function (this: any): Record<string, any> {
+                        const imageCtx = this.image.context;
+                        const imageTag = imageCtx.getImageTag({
+                            variant: imageCtx.variant || 'alpine',
+                            arch: imageCtx.arch || this.cli.getCurrentPlatformArch(),
+                        });
+                        const sanitizedName = imageTag.replace(/[^a-zA-Z0-9_.-]/g, '-') + '-dev';
+
+                        return this.container.context.derive({
+                            image: imageTag,
+                            name: sanitizedName,
+                            detach: true,
+                            waitFor: this.container.context.waitFor ?? 'READY',
+                            waitTimeout: this.container.context.waitTimeout ?? 30000,
+                            verbose: this.container.context.verbose ?? imageCtx.verbose,
+                            showOutput: this.container.context.showOutput ?? imageCtx.verbose,
+                        });
+                    }
+                },
+
+                /**
+                 * Build development image (current platform, alpine variant)
+                 */
+                buildDev: {
+                    type: CapsulePropertyTypes.Function,
+                    value: async function (this: any, options?: {
+                        files?: Record<string, any>;
+                        tagLatest?: boolean;
+                        attestations?: { sbom?: boolean; provenance?: boolean };
+                    }): Promise<{ imageTag: string }> {
+                        const ctx = this.image.context;
+                        const files = (ctx.files || options?.files)
+                            ? { ...ctx.files, ...options?.files }
+                            : undefined;
+
+                        return await this.image.buildVariant({
+                            variant: ctx.variant || 'alpine',
+                            arch: this.cli.getCurrentPlatformArch(),
+                            files,
+                            tagLatest: options?.tagLatest,
+                            attestations: options?.attestations ?? ctx.attestations,
+                        });
+                    }
+                },
+
+                /**
+                 * Build all distribution images (all variants × all archs)
+                 */
+                buildDistribution: {
+                    type: CapsulePropertyTypes.Function,
+                    value: async function (this: any, options?: {
+                        files?: Record<string, any>;
+                        tagLatest?: boolean;
+                        attestations?: { sbom?: boolean; provenance?: boolean };
+                    }): Promise<{ imageTag: string }[]> {
+                        const ctx = this.image.context;
+                        const files = (ctx.files || options?.files)
+                            ? { ...ctx.files, ...options?.files }
+                            : undefined;
+
+                        const results: { imageTag: string }[] = [];
+
+                        const archKeys = ctx.arch
+                            ? [ctx.arch]
+                            : Object.keys(this.cli.DOCKER_ARCHS);
+                        const variantKeys = ctx.variant
+                            ? [ctx.variant]
+                            : Object.keys(ctx.DOCKERFILE_VARIANTS);
+
+                        for (const variantKey of variantKeys) {
+                            for (const archKey of archKeys) {
+                                results.push(await this.image.buildVariant({
+                                    variant: variantKey,
+                                    arch: archKey,
+                                    files,
+                                    tagLatest: options?.tagLatest,
+                                    attestations: options?.attestations ?? ctx.attestations,
+                                }));
+                            }
+                        }
+
+                        return results;
+                    }
+                },
+
+                /**
+                 * Run development container (with SIGINT/SIGTERM handlers)
+                 */
+                runDev: {
+                    type: CapsulePropertyTypes.Function,
+                    value: async function (this: any, options?: { showOutput?: boolean }): Promise<{
+                        containerId: string;
+                        stop: () => Promise<void>;
+                        ensureRunning: () => Promise<boolean>;
+                    }> {
+                        const containerContext = {
+                            ...this.getDevelopmentContainerConfig(),
+                            ...(options?.showOutput !== undefined ? { showOutput: options.showOutput } : {}),
+                        };
+
+                        let signalReceived = false;
+                        let signalName = '';
+
+                        const stop = async () => {
+                            await this.container.cleanup(containerContext);
+                            this._devContainerId = undefined;
+                        };
+
+                        const signalHandler = (signal: string) => {
+                            console.error(`\n[runDev] Received ${signal}, stopping container...`);
+                            signalReceived = true;
+                            signalName = signal;
+                        };
+
+                        process.on('SIGINT', signalHandler);
+                        process.on('SIGTERM', signalHandler);
+
+                        await this.container.ensureStopped(containerContext);
+                        if (containerContext.verbose) console.log(`\nRunning container from image: ${containerContext.image}...`);
+                        const containerId = await this.container.run(containerContext);
+                        if (containerContext.verbose) console.log(`✅ Container started: ${containerId}`);
+                        this._devContainerId = containerId;
+
+                        if (signalReceived) {
+                            console.error(`[runDev] Signal ${signalName} was received during startup, stopping container...`);
+                            await stop();
+                            process.exit(0);
+                        }
+
+                        const ensureRunning = async () => {
+                            const isRunning = await this.container.isRunning({
+                                ...containerContext,
+                                retryDelayMs: 2000,
+                                requestTimeoutMs: 5000,
+                                timeoutMs: 60000,
+                            });
+                            if (!isRunning) {
+                                throw new Error(`Container ${containerId} failed to respond`);
+                            }
+                            return true;
+                        };
+
+                        const runningSignalHandler = async (signal: string) => {
+                            console.error(`\n[runDev] Received ${signal}, stopping container...`);
+                            await stop();
+                            process.exit(0);
+                        };
+
+                        process.off('SIGINT', signalHandler);
+                        process.off('SIGTERM', signalHandler);
+                        process.on('SIGINT', runningSignalHandler);
+                        process.on('SIGTERM', runningSignalHandler);
+
+                        return { containerId, stop, ensureRunning };
+                    }
+                },
+
+                /**
+                 * Ensure dev container is running
+                 */
+                ensureDevRunning: {
+                    type: CapsulePropertyTypes.Function,
+                    value: async function (this: any): Promise<boolean> {
+                        if (!this._devContainerId) {
+                            throw new Error('Container must be started first using runDev()');
+                        }
+                        const containerContext = this.getDevelopmentContainerConfig();
+                        const isRunning = await this.container.isRunning({
+                            ...containerContext,
+                            retryDelayMs: 2000,
+                            requestTimeoutMs: 5000,
+                            timeoutMs: 60000,
+                        });
+                        if (!isRunning) {
+                            throw new Error('Container failed to respond after 60 seconds');
+                        }
+                        return true;
+                    }
+                },
+
+                /**
+                 * Stop dev container
+                 */
+                stopDev: {
+                    type: CapsulePropertyTypes.Function,
+                    value: async function (this: any): Promise<void> {
+                        if (!this._devContainerId) {
+                            throw new Error('Container must be started first using runDev()');
+                        }
+                        await this.container.cleanup();
+                        this._devContainerId = undefined;
+                    }
+                },
+
+                /**
+                 * Retag images from a source org/repo to this project's org/repo
+                 */
+                retagImages: {
+                    type: CapsulePropertyTypes.Function,
+                    value: async function (this: any, { organization, repository }: { organization: string; repository: string }): Promise<void> {
+                        const ctx = this.image.context;
+                        if (ctx.verbose) {
+                            console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+                            console.log(`Retagging images from ${organization}/${repository} to ${ctx.organization}/${ctx.repository}`);
+                            console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+                        }
+
+                        const tags = await this.image.getTags({ organization, repository });
+
+                        if (ctx.verbose) console.log(`Found ${tags.length} tags to retag`);
+
+                        for (const tagInfo of tags) {
+                            const tagSuffix = tagInfo.tag.split(':')[1];
+                            if (!tagSuffix) continue;
+
+                            const sourceImageTag = `${organization}/${repository}:${tagSuffix}`;
+                            const targetImageTag = `${ctx.organization}/${ctx.repository}:${tagSuffix}`;
+
+                            if (ctx.verbose) console.log(`  Tagging: ${sourceImageTag} -> ${targetImageTag}`);
+
+                            await this.cli.tagImage({ sourceImage: sourceImageTag, targetImage: targetImageTag });
+                        }
+
+                        if (ctx.verbose) console.log(`✅ Retagged ${tags.length} images`);
+                    }
+                },
+
+                Dispose: {
+                    type: CapsulePropertyTypes.Dispose,
+                    value: async function (this: any): Promise<void> {
+                        if (!this.dispose || !this._devContainerId) return;
+                        try {
+                            const containerContext = this.getDevelopmentContainerConfig();
+                            await this.container.cleanup(containerContext);
+                        } catch (error) {
+                            if (this.image.context.verbose) console.log(`Warning: Failed to cleanup dev container on dispose: ${error}`);
+                        }
+                        this._devContainerId = undefined;
+                    }
+                },
+            }
+        }
+    }, {
+        importMeta: import.meta,
+        importStack: makeImportStack(),
+        capsuleName: '@stream44.studio/t44-docker.com/caps/Project',
+    })
+}

package/lib/waitForFetch.ts

@@ -0,0 +1,95 @@
+/**
+ * Wait for a URL to respond with a specific condition
+ */
+export interface WaitForFetchOptions {
+    url: string;
+    method?: string;  // HTTP method (GET, POST, etc.)
+    headers?: Record<string, string>;  // Request headers
+    body?: string;  // Request body
+    status: true | false | number;  // true = any response, false = no response (fetch fails), number = specific status code
+    retryDelayMs?: number;
+    requestTimeoutMs?: number;
+    timeoutMs?: number;
+    verbose?: boolean;
+    returnResponse?: boolean;  // If true, return the Response object instead of boolean
+}
+
+export async function waitForFetch(options: WaitForFetchOptions & { returnResponse: true }): Promise<Response>;
+export async function waitForFetch(options: WaitForFetchOptions & { returnResponse?: false }): Promise<boolean>;
+export async function waitForFetch(options: WaitForFetchOptions): Promise<boolean | Response> {
+    const {
+        url,
+        method = 'GET',
+        headers,
+        body,
+        status,
+        retryDelayMs = 1000,
+        requestTimeoutMs = 2000,
+        timeoutMs = 30000,
+        verbose = false,
+        returnResponse = false
+    } = options;
+
+    const startTime = Date.now();
+    let attemptCount = 0;
+
+    while (Date.now() - startTime < timeoutMs) {
+        attemptCount++;
+        const elapsed = Date.now() - startTime;
+
+        try {
+            const response = await fetch(url, {
+                method,
+                headers,
+                body,
+                signal: AbortSignal.timeout(requestTimeoutMs)
+            });
+
+            // Check if condition is met
+            if (status === true) {
+                // Any response is success
+                if (verbose) {
+                    console.log(`[waitForFetch] URL ${url} responded (status: ${response.status}) after ${attemptCount} attempts (${elapsed}ms)`);
+                }
+                return returnResponse ? response : true;
+            } else if (typeof status === 'number') {
+                // Specific status code required
+                if (response.status === status) {
+                    if (verbose) {
+                        console.log(`[waitForFetch] URL ${url} responded with status ${status} after ${attemptCount} attempts (${elapsed}ms)`);
+                    }
+                    return returnResponse ? response : true;
+                } else {
+                    if (verbose) {
+                        console.log(`[waitForFetch] Attempt ${attemptCount}: Got status ${response.status}, expected ${status} (${elapsed}ms)`);
+                    }
+                }
+            }
+            // If status === false, we want fetch to fail, so getting a response means condition not met
+        } catch (error) {
+            // Fetch failed
+            if (status === false) {
+                // We want fetch to fail, so this is success
+                if (verbose) {
+                    console.log(`[waitForFetch] URL ${url} is not responding (as expected) after ${attemptCount} attempts (${elapsed}ms)`);
+                }
+                return true;
+            } else {
+                if (verbose) {
+                    console.log(`[waitForFetch] Attempt ${attemptCount}: Request failed (${elapsed}ms)`);
+                }
+            }
+        }
+
+        // Wait before next attempt, but don't exceed total timeout
+        const remainingTime = timeoutMs - (Date.now() - startTime);
+        if (remainingTime > 0) {
+            await new Promise(resolve => setTimeout(resolve, Math.min(retryDelayMs, remainingTime)));
+        }
+    }
+
+    if (verbose) {
+        console.log(`[waitForFetch] Timeout reached after ${attemptCount} attempts (${Date.now() - startTime}ms)`);
+    }
+    return false;
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+    "name": "@stream44.studio/t44-docker.com",
+    "version": "0.1.0-rc.3",
+    "private": false,
+    "license": "MIT",
+    "type": "module",
+    "scripts": {
+        "test": "bun test"
+    },
+    "dependencies": {
+        "t44": "^0.4.0-rc.17",
+        "@stream44.studio/encapsulate": "^0.4.0-rc.19"
+    },
+    "devDependencies": {
+        "@types/bun": "^1.3.4",
+        "@types/node": "^25.0.3",
+        "bun-types": "^1.3.4"
+    }
+}

package/structs/Hub/WorkspaceConnectionConfig.ts

@@ -0,0 +1,53 @@
+
+export async function capsule({
+    encapsulate,
+    CapsulePropertyTypes,
+    makeImportStack
+}: any) {
+    return encapsulate({
+        '#@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0': {
+            '#t44/caps/ConfigSchemaStruct': {
+                as: 'schema',
+                options: {
+                    '#': {
+                        schema: {
+                            type: 'object',
+                            properties: {
+                                username: {
+                                    type: 'string',
+                                    title: 'Docker Hub Username',
+                                    description: 'Your Docker Hub username from https://hub.docker.com',
+                                    minLength: 1,
+                                },
+                                password: {
+                                    type: 'string',
+                                    title: 'Docker Hub Password or Personal Access Token',
+                                    description: 'Your Docker Hub password or a Personal Access Token (PAT) from https://hub.docker.com/settings/security',
+                                    minLength: 1,
+                                },
+                                organization: {
+                                    type: 'string',
+                                    title: 'Docker Hub Organization (optional)',
+                                    description: 'Your Docker Hub organization name. Leave empty to use your username as the namespace.',
+                                },
+                            },
+                            required: ['username', 'password']
+                        }
+                    }
+                }
+            },
+            '#': {
+                capsuleName: {
+                    type: CapsulePropertyTypes.Literal,
+                    value: capsule['#']
+                },
+            }
+        }
+    }, {
+        extendsCapsule: 't44/caps/WorkspaceConnection',
+        importMeta: import.meta,
+        importStack: makeImportStack(),
+        capsuleName: capsule['#'],
+    })
+}
+capsule['#'] = '@stream44.studio/t44-docker.com/structs/Hub/WorkspaceConnectionConfig'

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+    "extends": "../../../tsconfig.paths.json",
+    "compilerOptions": {
+        "target": "es2021",
+        "module": "esnext",
+        "lib": [
+            "ES2021",
+            "DOM"
+        ],
+        "types": [
+            "bun",
+            "node"
+        ],
+        "moduleResolution": "bundler",
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "resolveJsonModule": true,
+        "allowSyntheticDefaultImports": true
+    },
+    "include": [
+        "**/*.ts"
+    ],
+    "exclude": [
+        "node_modules"
+    ]
+}