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

package/caps/Containers.test.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env bun test --timeout 30000
+
+import * as bunTest from 'bun:test'
+import { run } from 't44/standalone-rt'
+
+const {
+    test: { describe, it, expect },
+    containers,
+} = 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: {} } }
+                },
+                containers: {
+                    type: CapsulePropertyTypes.Mapping,
+                    value: './Containers',
+                },
+            }
+        }
+    }, {
+        importMeta: import.meta,
+        importStack: makeImportStack(),
+        capsuleName: '@stream44.studio/t44-docker.com/caps/Containers.test'
+    })
+    return { spine }
+}, async ({ spine, apis }: any) => {
+    return apis[spine.capsuleSourceLineRef]
+}, { importMeta: import.meta })
+
+describe('Containers Capsule', () => {
+
+    describe('list', () => {
+        it('should return a string with default format', async () => {
+            const result = await containers.list({ all: true });
+            expect(typeof result).toBe('string');
+        });
+
+        it('should return a string with custom format', async () => {
+            const result = await containers.list({ all: true, format: '{{.ID}}' });
+            expect(typeof result).toBe('string');
+        });
+
+        it('should return an array when json is true', async () => {
+            const result = await containers.list({ all: true, json: true });
+            expect(Array.isArray(result)).toBe(true);
+        });
+
+        it('should filter by name', async () => {
+            const result = await containers.list({ all: true, filter: 'name=nonexistent-container-xyz', format: '{{.ID}}' });
+            expect(typeof result).toBe('string');
+            expect((result as string).trim()).toBe('');
+        });
+    });
+});

package/caps/Containers.ts

@@ -0,0 +1,47 @@
+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': {},
+            '#': {
+                cli: {
+                    type: CapsulePropertyTypes.Mapping,
+                    value: './Cli',
+                },
+
+                list: {
+                    type: CapsulePropertyTypes.Function,
+                    value: async function (this: any, options: {
+                        all?: boolean; filter?: string; format?: string; json?: boolean;
+                    } = {}): Promise<string | any[]> {
+                        const { all = false, filter, format, json = false } = options;
+                        const args = ['ps'];
+                        if (all) args.push('-a');
+                        if (filter) args.push('--filter', filter);
+                        if (json && !format) { args.push('--format', 'json'); }
+                        else if (format) { args.push('--format', format); }
+                        const result = await this.cli.exec(args);
+                        if (json && !format) {
+                            const lines = result.split('\n').filter((line: string) => line.trim());
+                            if (lines.length === 0) return [];
+                            return lines.map((line: string) => JSON.parse(line));
+                        }
+                        return result;
+                    }
+                },
+            }
+        }
+    }, {
+        importMeta: import.meta,
+        importStack: makeImportStack(),
+        capsuleName: '@stream44.studio/t44-docker.com/caps/Containers',
+    })
+}

package/caps/Hub.test.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env bun test --timeout 60000
+
+import * as bunTest from 'bun:test'
+import { run } from 't44/workspace-rt'
+
+const {
+    test: { describe, it, expect },
+    hub,
+} = 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: {
+                                DOCKERHUB_USERNAME: { factReference: '@stream44.studio/t44-docker.com/structs/Hub/WorkspaceConnectionConfig:username' },
+                                DOCKERHUB_PASSWORD: { factReference: '@stream44.studio/t44-docker.com/structs/Hub/WorkspaceConnectionConfig:password' },
+                                DOCKERHUB_ORGANIZATION: { factReference: '@stream44.studio/t44-docker.com/structs/Hub/WorkspaceConnectionConfig:organization' },
+                            }
+                        }
+                    }
+                },
+                hub: {
+                    type: CapsulePropertyTypes.Mapping,
+                    value: './Hub',
+                },
+            }
+        }
+    }, {
+        importMeta: import.meta,
+        importStack: makeImportStack(),
+        capsuleName: '@stream44.studio/t44-docker.com/caps/Hub.test'
+    })
+    return { spine }
+}, async ({ spine, apis }: any) => {
+    return apis[spine.capsuleSourceLineRef]
+}, {
+    importMeta: import.meta
+})
+
+describe('Docker Hub Capsule', function () {
+
+    it('should have default values', function () {
+        expect(hub.verbose).toBe(false);
+        expect(hub._token).toBeUndefined();
+    })
+
+    it('authenticate()', async function () {
+        const token = await hub.authenticate();
+        expect(token).toBeTruthy();
+        expect(typeof token).toBe('string');
+        expect(hub._token).toBe(token);
+    })
+
+    it('getNamespace() returns organization or username', async function () {
+        const ns = await hub.getNamespace();
+        expect(ns).toBeTruthy();
+        expect(typeof ns).toBe('string');
+    })
+
+    it('getStats() for a public repository', async function () {
+        const stats = await hub.getStats({
+            repository: 'alpine',
+            namespace: 'library',
+        });
+
+        expect(stats).toBeDefined();
+        expect(stats.name).toBe('alpine');
+        expect(stats.namespace).toBe('library');
+        expect(stats.pull_count).toBeGreaterThan(0);
+    })
+
+    it('getTags() for a public repository', async function () {
+        const tags = await hub.getTags({
+            repository: 'alpine',
+            namespace: 'library',
+        });
+
+        expect(tags).toBeArray();
+        expect(tags.length).toBeGreaterThan(0);
+        expect(tags).toContain('latest');
+    })
+
+    it('ensureTagged() succeeds for existing tag', async function () {
+        const tag = await hub.ensureTagged({
+            repository: 'alpine',
+            namespace: 'library',
+            tag: 'latest',
+        });
+
+        expect(tag).toBe('latest');
+    })
+
+    it('ensureTagged() throws for non-existent tag', async function () {
+        await expect(hub.ensureTagged({
+            repository: 'alpine',
+            namespace: 'library',
+            tag: 'this-tag-does-not-exist-ever-12345',
+        })).rejects.toThrow('not found');
+    })
+
+})

package/caps/Hub.ts

@@ -0,0 +1,367 @@
+/**
+ * Docker Hub API Capsule
+ * @see https://docs.docker.com/docker-hub/api/latest/
+ */
+
+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': {},
+            '#@stream44.studio/t44-docker.com/structs/Hub/WorkspaceConnectionConfig': {
+                as: '$ConnectionConfig'
+            },
+            '#': {
+
+                verbose: {
+                    type: CapsulePropertyTypes.Literal,
+                    value: false,
+                },
+
+                _token: {
+                    type: CapsulePropertyTypes.Literal,
+                    value: undefined as string | undefined,
+                },
+
+                /**
+                 * Get the namespace (organization or username)
+                 */
+                getNamespace: {
+                    type: CapsulePropertyTypes.Function,
+                    value: async function (this: any): Promise<string> {
+                        const org = await this.$ConnectionConfig.getConfigValue('organization').catch(() => undefined);
+                        const username = await this.$ConnectionConfig.getConfigValue('username');
+                        return org || username;
+                    }
+                },
+
+                /**
+                 * Authenticate with Docker Hub and get a JWT token
+                 */
+                authenticate: {
+                    type: CapsulePropertyTypes.Function,
+                    value: async function (this: any): Promise<string> {
+                        const username = await this.$ConnectionConfig.getConfigValue('username');
+                        const password = await this.$ConnectionConfig.getConfigValue('password');
+
+                        if (this.verbose) {
+                            console.log(`[Hub] Authenticating as ${username}`);
+                        }
+
+                        const response = await fetch('https://hub.docker.com/v2/users/login', {
+                            method: 'POST',
+                            headers: { 'Content-Type': 'application/json' },
+                            body: JSON.stringify({
+                                username,
+                                password,
+                            }),
+                        });
+
+                        if (!response.ok) {
+                            const error = await response.text();
+                            throw new Error(`Docker Hub authentication failed: ${response.status} ${error}`);
+                        }
+
+                        const data = await response.json() as { token?: string };
+                        this._token = data.token;
+
+                        if (!this._token) {
+                            throw new Error('Docker Hub authentication failed: No token received');
+                        }
+
+                        if (this.verbose) {
+                            console.log(`[Hub] Authentication successful`);
+                        }
+
+                        return this._token;
+                    }
+                },
+
+                /**
+                 * Ensure we have a valid token
+                 */
+                ensureAuthenticated: {
+                    type: CapsulePropertyTypes.Function,
+                    value: async function (this: any): Promise<string> {
+                        if (!this._token) {
+                            await this.authenticate();
+                        }
+                        return this._token!;
+                    }
+                },
+
+                /**
+                 * Internal helper to make API calls to Docker Hub
+                 */
+                apiCall: {
+                    type: CapsulePropertyTypes.Function,
+                    value: async function (this: any, options: {
+                        method: 'GET' | 'POST' | 'DELETE';
+                        path: string;
+                        requireAuth?: boolean;
+                        body?: any;
+                    }): Promise<any> {
+                        const { method, path, requireAuth = true, body } = options;
+
+                        const headers: Record<string, string> = {};
+
+                        if (requireAuth) {
+                            const token = await this.ensureAuthenticated();
+                            headers['Authorization'] = `JWT ${token}`;
+                        } else if (this._token) {
+                            headers['Authorization'] = `JWT ${this._token}`;
+                        }
+
+                        if (body) {
+                            headers['Content-Type'] = 'application/json';
+                        }
+
+                        const url = `https://hub.docker.com${path}`;
+
+                        if (this.verbose) {
+                            console.log(`[Hub] ${method} ${path}`);
+                        }
+
+                        const response = await fetch(url, {
+                            method,
+                            headers,
+                            body: body ? JSON.stringify(body) : undefined,
+                        });
+
+                        if (!response.ok) {
+                            const error = await response.text();
+                            throw new Error(`API call failed: ${method} ${path} - ${response.status} ${error}`);
+                        }
+
+                        if (method === 'DELETE') {
+                            return {};
+                        }
+
+                        return await response.json();
+                    }
+                },
+
+                /**
+                 * Get all tags in a repository
+                 */
+                getTags: {
+                    type: CapsulePropertyTypes.Function,
+                    value: async function (this: any, options: {
+                        repository: string;
+                        namespace?: string;
+                    }): Promise<string[]> {
+                        const namespace = options.namespace || this.getNamespace();
+                        const repository = options.repository;
+
+                        const data = await this.apiCall({
+                            method: 'GET',
+                            path: `/v2/repositories/${namespace}/${repository}/tags/?page_size=100`,
+                        });
+
+                        return data.results?.map((result: any) => result.name) || [];
+                    }
+                },
+
+                /**
+                 * Verify that a tag exists in the repository
+                 */
+                ensureTagged: {
+                    type: CapsulePropertyTypes.Function,
+                    value: async function (this: any, options: {
+                        repository: string;
+                        tag: string;
+                        namespace?: string;
+                    }): Promise<string> {
+                        const tags = await this.getTags({
+                            repository: options.repository,
+                            namespace: options.namespace,
+                        });
+
+                        if (!tags.includes(options.tag)) {
+                            throw new Error(`Tag ${options.tag} not found in repository`);
+                        }
+
+                        return options.tag;
+                    }
+                },
+
+                /**
+                 * Get repository statistics including pull count, star count, etc.
+                 */
+                getStats: {
+                    type: CapsulePropertyTypes.Function,
+                    value: async function (this: any, options: {
+                        repository: string;
+                        namespace?: string;
+                    }): Promise<{
+                        pull_count: number;
+                        star_count: number;
+                        name: string;
+                        namespace: string;
+                        description: string;
+                        is_private: boolean;
+                        last_updated: string;
+                    }> {
+                        const namespace = options.namespace || this.getNamespace();
+                        const repository = options.repository;
+
+                        const data = await this.apiCall({
+                            method: 'GET',
+                            path: `/v2/repositories/${namespace}/${repository}/`,
+                            requireAuth: false,
+                        });
+
+                        return {
+                            pull_count: data.pull_count || 0,
+                            star_count: data.star_count || 0,
+                            name: data.name,
+                            namespace: data.namespace,
+                            description: data.description || '',
+                            is_private: data.is_private || false,
+                            last_updated: data.last_updated,
+                        };
+                    }
+                },
+
+                /**
+                 * Delete a specific tag from a repository
+                 */
+                deleteTag: {
+                    type: CapsulePropertyTypes.Function,
+                    value: async function (this: any, options: {
+                        repository: string;
+                        tag: string;
+                        namespace?: string;
+                        timeoutMs?: number;
+                        pollIntervalMs?: number;
+                    }): Promise<void> {
+                        const namespace = options.namespace || this.getNamespace();
+                        const repository = options.repository;
+                        const tag = options.tag;
+                        const timeoutMs = options.timeoutMs ?? 30000;
+                        const pollIntervalMs = options.pollIntervalMs ?? 2000;
+
+                        if (this.verbose) {
+                            console.log(`[Hub] Deleting tag ${namespace}/${repository}:${tag}`);
+                        }
+
+                        try {
+                            await this.apiCall({
+                                method: 'DELETE',
+                                path: `/v2/repositories/${namespace}/${repository}/tags/${tag}/`,
+                            });
+                        } catch (error: any) {
+                            if (error?.message?.includes('403')) {
+                                throw new Error('Tag deletion not permitted: token lacks delete permissions');
+                            }
+                            throw error;
+                        }
+
+                        // Poll to verify deletion
+                        const startTime = Date.now();
+                        while (Date.now() - startTime < timeoutMs) {
+                            const tags = await this.getTags({ repository, namespace });
+                            if (!tags.includes(tag)) {
+                                if (this.verbose) {
+                                    console.log(`[Hub] Tag deleted successfully`);
+                                }
+                                return;
+                            }
+                            await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+                        }
+
+                        throw new Error(`Tag deletion verification timed out after ${timeoutMs}ms`);
+                    }
+                },
+
+                /**
+                 * Delete an entire repository from Docker Hub
+                 */
+                deleteRepository: {
+                    type: CapsulePropertyTypes.Function,
+                    value: async function (this: any, options: {
+                        repository: string;
+                        namespace?: string;
+                        wait?: boolean;
+                        timeoutMs?: number;
+                        pollIntervalMs?: number;
+                    }): Promise<void> {
+                        const namespace = options.namespace || this.getNamespace();
+                        const repository = options.repository;
+                        const { wait = false, timeoutMs = 5 * 60 * 1000, pollIntervalMs = 15000 } = options;
+
+                        if (this.verbose) {
+                            console.log(`[Hub] Deleting repository ${namespace}/${repository}`);
+                        }
+
+                        await this.apiCall({
+                            method: 'DELETE',
+                            path: `/v2/repositories/${namespace}/${repository}/`,
+                        });
+
+                        if (wait) {
+                            const startTime = Date.now();
+                            while (Date.now() - startTime < timeoutMs) {
+                                try {
+                                    await this.getStats({ repository, namespace });
+                                    await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+                                } catch (error: any) {
+                                    if (error?.message?.includes('404') || error?.message?.includes('not found')) {
+                                        if (this.verbose) {
+                                            console.log(`[Hub] Repository deletion confirmed`);
+                                        }
+                                        return;
+                                    }
+                                    await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+                                }
+                            }
+                            throw new Error(`Timeout waiting for repository deletion after ${timeoutMs}ms`);
+                        }
+                    }
+                },
+
+                /**
+                 * Login to Docker Hub registry via CLI
+                 */
+                loginCli: {
+                    type: CapsulePropertyTypes.Function,
+                    value: async function (this: any, options?: { cli?: any }): Promise<string> {
+                        const cli = options?.cli;
+                        if (!cli) {
+                            throw new Error('cli capsule must be provided to loginCli');
+                        }
+
+                        const username = await this.$ConnectionConfig.getConfigValue('username');
+                        const password = await this.$ConnectionConfig.getConfigValue('password');
+
+                        if (this.verbose) {
+                            console.log(`[Hub] Logging in to Docker Hub as ${username}`);
+                        }
+
+                        const result = await cli.exec([
+                            'login',
+                            '-u', username,
+                            '--password-stdin',
+                            'registry.hub.docker.com'
+                        ], { stdin: password + '\n' });
+
+                        return result;
+                    }
+                },
+
+            }
+        }
+    }, {
+        importMeta: import.meta,
+        importStack: makeImportStack(),
+        capsuleName: '@stream44.studio/t44-docker.com/caps/Hub',
+    })
+}

package/caps/Image/tpl/Dockerfile.alpine

@@ -0,0 +1,40 @@
+# Smallest option: Alpine with glibc (~16MB base + binary)
+# Best for: Production where size is critical
+# Trade-off: Minimal debugging tools
+
+FROM frolvlad/alpine-glibc:latest
+
+# Install wget for health checks and bun for native modules
+RUN apk add --no-cache wget ca-certificates unzip bash curl libstdc++ libgcc
+
+# Install Bun to system-wide location
+RUN wget -qO- https://bun.sh/install | bash -s -- bun-v1.2.0 && \
+    mv /root/.bun/bin/bun /usr/local/bin/bun && \
+    chmod +x /usr/local/bin/bun
+
+# Set working directory
+WORKDIR /app
+
+# Copy all app files from build context
+COPY . /app/
+
+# Install only production dependencies (native modules)
+RUN bun install --production --no-save
+
+# Make binaries executable (if any)
+RUN find /app -type f -name "*.sh" -exec chmod +x {} \; || true
+RUN find /app/dist -type f -executable -exec chmod +x {} \; 2>/dev/null || true
+
+# Create non-root user
+RUN addgroup -g 1001 -S appuser && \
+    adduser -u 1001 -S appuser -G appuser && \
+    chown -R appuser:appuser /app
+
+# Switch to non-root user
+USER appuser
+
+# Environment variables (can be overridden at runtime)
+ENV IPFS_GATEWAY_TOKEN=""
+
+# Run the app using bun
+CMD ["bun", "run", "start"]

package/caps/Image/tpl/Dockerfile.distroless

@@ -0,0 +1,45 @@
+# Most secure option: Google Distroless (~20-30MB base)
+# Best for: Production security (no shell, minimal attack surface)
+# Trade-off: No wget for health checks, harder to debug
+
+# Build stage for installing native dependencies
+FROM oven/bun:1.2-slim AS builder
+WORKDIR /app
+# Copy all app files
+COPY . /app/
+RUN bun install --production --no-save
+
+# Use Debian base for glibc compatibility
+FROM gcr.io/distroless/base-debian12:latest
+
+# Set working directory
+WORKDIR /app
+
+# Copy Bun runtime from builder
+COPY --from=builder /usr/local/bin/bun /usr/local/bin/bun
+
+# Copy C++ runtime libraries from builder (required by libsql native module)
+COPY --from=builder /usr/lib/*/libstdc++.so.6 /usr/lib/
+COPY --from=builder /usr/lib/*/libgcc_s.so.1 /usr/lib/
+
+# Copy native dependencies from builder
+COPY --from=builder /app/node_modules ./node_modules
+
+# Copy all app files from builder
+COPY --from=builder /app /app
+
+# Create non-root user and set ownership
+# Note: distroless uses numeric UIDs since there's no shell to create users
+COPY --from=builder --chown=1001:1001 /app /app
+
+# Switch to non-root user (numeric UID since distroless has no user database)
+USER 1001
+
+# Environment variables (can be overridden at runtime)
+ENV IPFS_GATEWAY_TOKEN=""
+
+# Note: Health checks won't work without wget/curl
+# You'll need to rely on external monitoring or TCP checks
+
+# Run the app using bun
+CMD ["bun", "run", "start"]

package/caps/Image/tpl/package.json

@@ -0,0 +1,8 @@
+{
+    "name": "ncloud-docker-image",
+    "version": "0.1.0",
+    "private": true,
+    "scripts": {
+        "start": "echo 'Specify your own package.json file!'"
+    }
+}