@open-kingdom/shared-backend-integration-test-doubles 0.0.2-17

package/README.md

@@ -0,0 +1,242 @@
+# Integration Test Doubles
+
+A library for creating integration test doubles (fakes) for external services. Provides local twins that can be used in place of real services during testing and development.
+
+## Features
+
+- **GCS Twin**: Local fake for Google Cloud Storage using `fsouza/fake-gcs-server`
+- **Configuration**: Environment-based configuration with sensible defaults and validation
+- **Lifecycle Management**: Start, stop, and reset twins programmatically
+- **NestJS Integration**: REST API controller for managing twins at runtime
+
+## Quick Start
+
+### Using GCS Twin
+
+```typescript
+import { GcsTwin } from '@open-kingdom/shared-backend-integration-test-doubles';
+
+// Start the twin (default port 9013)
+const twin = new GcsTwin();
+await twin.start();
+
+// GCS_EMULATOR_URL is automatically set to http://localhost:9013
+// Use the twin URL in your SDK configuration
+const client = new Storage({
+  apiEndpoint: twin.getEmulatorHost(),
+  projectId: 'emulator-project',
+  credentials: {
+    client_email: 'emulator@emulator.iam',
+    private_key: 'unused',
+  },
+});
+
+// Run your tests...
+
+// Clean up (also unsets GCS_EMULATOR_URL)
+await twin.stop();
+```
+
+### NestJS Integration
+
+Use the `TwinService` to manage the twin lifecycle within a NestJS application:
+
+```typescript
+import { TwinService } from './twin/twin.service';
+
+// The service wraps GcsTwin and exposes start/stop/status methods.
+// See the demo-scaffold-backend app for a full controller example.
+const twinService = new TwinService();
+await twinService.start();
+const status = await twinService.status();
+await twinService.stop();
+```
+
+## API Reference
+
+### GcsTwin
+
+#### Constructor
+
+```typescript
+constructor(overrides?: Partial<GcsTwinConfig>, docker?: Docker)
+```
+
+- `overrides.port`: Port to run the twin on (default: 9013, or from `GCS_TWIN_PORT` env var; must be within 9010-9020)
+- `overrides.externalUrl`: External URL for the twin (default: `http://localhost:{port}`)
+- `overrides.dataDir`: Optional persistent data directory
+- `overrides.buckets`: Buckets to create and seed (default: `[{ name: 'app-assets' }, { name: 'user-uploads' }]`)
+- `docker`: Optional Docker instance (for testing)
+
+Config merges defaults, environment variables, and explicit overrides (explicit overrides take precedence).
+
+#### Methods
+
+- `start()`: Start the twin container, create buckets, and set `GCS_EMULATOR_URL` env var
+- `stop()`: Stop and remove the container, unset `GCS_EMULATOR_URL`
+- `reset()`: Reset the twin to its initial seeded state
+- `getEmulatorHost()`: Get the twin URL (e.g., `http://localhost:9013`)
+- `isHealthy()`: Check if the twin is running and responding
+
+#### GcsTwinConfig
+
+```typescript
+interface GcsTwinConfig {
+  port: number; // Port the fake-gcs-server listens on
+  externalUrl: string; // External URL for SDK configuration (e.g., http://localhost:9013)
+  dataDir?: string; // Optional persistent data directory
+  buckets: BucketConfig[]; // Buckets to create on startup
+}
+
+interface BucketConfig {
+  name: string; // Bucket name
+}
+```
+
+### Exports
+
+```typescript
+// GCS twin
+export { GcsTwin } from './gcs/gcs-twin.js';
+export type { GcsTwinConfig, BucketConfig } from './gcs/gcs-twin.config.js';
+export { defaultGcsConfig } from './gcs/gcs-twin.config.js';
+
+// Shared constants and utilities
+export { PORT_RANGE, DEFAULT_PORTS, ENV_VARS } from './shared/constants.js';
+export { isTestMode } from './shared/activation.js';
+export { createGcsConfig, defaultGcsConfig } from './shared/config.js';
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable            | Description                           | Default                   |
+| ------------------- | ------------------------------------- | ------------------------- |
+| `GCS_TWIN_PORT`     | Port for GCS twin (must be 9010-9020) | 9013                      |
+| `GCS_TWIN_DATA_DIR` | Persistent data directory (optional)  | (ephemeral)               |
+| `GCS_EMULATOR_URL`  | Auto-set by `GcsTwin.start()`         | `http://localhost:{port}` |
+| `TEST_MODE`         | Activation gate; must be `'true'`     | (unset)                   |
+
+### Port Assignments
+
+The library reserves ports 9010-9020 for test doubles:
+
+| Twin            | Default Port  |
+| --------------- | ------------- |
+| GCS             | 9013          |
+| Gmail           | 9014 (future) |
+| Google Auth     | 9015 (future) |
+| YouTube         | 9016 (future) |
+| Google Calendar | 9017 (future) |
+| Spotify         | 9018 (future) |
+
+Configure in `constants.ts` if you need to change this range.
+
+### How Configuration Merging Works
+
+Configuration is resolved in this order (later takes precedence):
+
+1. **Defaults** (`defaultGcsConfig`)
+2. **Environment variables** (`GCS_TWIN_PORT`, `GCS_TWIN_DATA_DIR`)
+3. **Explicit overrides** (passed to constructor or `createGcsConfig()`)
+
+Port validation ensures the value is within the reserved range (9010-9020).
+
+## Scripts
+
+### Start Twin Manually
+
+```bash
+# Start on default port (9013)
+npx tsx scripts/start-twin.ts
+
+# Start on specific port
+npx tsx scripts/start-twin.ts 9013
+```
+
+The script outputs the twin URL and sets `GCS_EMULATOR_URL`. Keeps running until Ctrl+C.
+
+## Architecture
+
+### Components
+
+```
+┌─────────────────┐     ┌────────────────────┐
+│  NestJS App     │     │  GcsTwin            │
+│  (GcsStorage    │────▶│  (fake-gcs-server   │
+│   Service)      │     │   Docker container) │
+└─────────────────┘     └────────────────────┘
+```
+
+### How It Works
+
+1. **GcsTwin** starts a Docker container running `fsouza/fake-gcs-server`
+2. `GCS_EMULATOR_URL` is automatically set in `process.env` on start and unset on stop
+3. **GcsStorageService** (in `feature-gcp-resources`) reads `GCS_EMULATOR_URL` or `STORAGE_EMULATOR_HOST` and configures the Google Cloud Storage SDK with `apiEndpoint` pointing to the twin
+4. When no emulator is configured, `GcsStorageService` falls back to real GCS with signed URLs
+
+### Default Buckets
+
+Two buckets are created by default:
+
+- **app-assets** - Application static assets
+- **user-uploads** - User-uploaded files
+
+## Troubleshooting
+
+### Docker Not Running
+
+```
+Error: connect ENOENT /var/run/docker.sock
+```
+
+**Solution**: Ensure Docker Desktop is running.
+
+### Port Already in Use
+
+```
+Error: Port 9013 is already in use
+```
+
+**Solution**:
+
+- Use a different port: `new GcsTwin({ port: 9014 })`
+- Or set `GCS_TWIN_PORT=9014`
+
+### Container Won't Start
+
+```
+Error: (HTTP code 404) not found - No such image: fsouza/fake-gcs-server:latest
+```
+
+**Solution**: Pull the image manually:
+
+```bash
+docker pull fsouza/fake-gcs-server
+```
+
+### Port Out of Range
+
+```
+Error: GCS twin port 9099 is outside the reserved range 9010-9020
+```
+
+**Solution**: Use a port within 9010-9020, or adjust `PORT_RANGE` in `constants.ts`.
+
+### Tests Fail When Run Together
+
+**Symptoms**: Tests pass in isolation but fail in suite.
+
+**Cause**: Port conflicts between tests.
+
+**Solution**: Use unique ports for each test suite:
+
+```typescript
+const twin1 = new GcsTwin({ port: 9013 });
+const twin2 = new GcsTwin({ port: 9014 });
+```
+
+## License
+
+MIT

package/dist/gcs/gcs-twin.config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * GCS twin configuration.
+ *
+ * Re‑exports the shared GcsTwinConfig and BucketConfig interfaces
+ * along with the default configuration.
+ */
+export type { GcsTwinConfig, BucketConfig } from '../shared/config.js';
+export { defaultGcsConfig } from '../shared/config.js';
+//# sourceMappingURL=gcs-twin.config.d.ts.map

package/dist/gcs/gcs-twin.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcs-twin.config.d.ts","sourceRoot":"","sources":["../../src/gcs/gcs-twin.config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/gcs/gcs-twin.config.js

@@ -0,0 +1,8 @@
+/**
+ * GCS twin configuration.
+ *
+ * Re‑exports the shared GcsTwinConfig and BucketConfig interfaces
+ * along with the default configuration.
+ */ export { defaultGcsConfig } from '../shared/config.js';
+
+//# sourceMappingURL=gcs-twin.config.js.map

package/dist/gcs/gcs-twin.config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/gcs/gcs-twin.config.ts"],"sourcesContent":["/**\n * GCS twin configuration.\n *\n * Re‑exports the shared GcsTwinConfig and BucketConfig interfaces\n * along with the default configuration.\n */\n\nexport type { GcsTwinConfig, BucketConfig } from '../shared/config.js';\nexport { defaultGcsConfig } from '../shared/config.js';\n"],"names":["defaultGcsConfig"],"rangeMappings":";;;;;","mappings":"AAAA;;;;;CAKC,GAGD,SAASA,gBAAgB,QAAQ,sBAAsB"}

package/dist/gcs/gcs-twin.d.ts

@@ -0,0 +1,58 @@
+import Docker from 'dockerode';
+import { GcsTwinConfig } from '../shared/config.js';
+/**
+ * GCS twin lifecycle manager.
+ *
+ * Starts/stops a fake‑gcs‑server Docker container, creates buckets,
+ * and sets the GCS_EMULATOR_URL environment variable.
+ */
+export declare class GcsTwin {
+    private readonly config;
+    private readonly docker;
+    private container;
+    private readonly containerName;
+    /**
+     * Create a new GCS twin.
+     *
+     * @param overrides Optional configuration overrides (merged with defaults and env vars).
+     * @param docker Optional Docker instance (for testing).
+     */
+    constructor(overrides?: Partial<GcsTwinConfig>, docker?: Docker);
+    /**
+     * Start the Docker container and create buckets.
+     *
+     * @throws {Error} If the container fails to start.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop and remove the Docker container.
+     */
+    stop(): Promise<void>;
+    /**
+     * Reset all data: delete buckets then re‑create them.
+     */
+    reset(): Promise<void>;
+    /**
+     * Get the emulator host URL for SDK configuration.
+     */
+    getEmulatorHost(): string;
+    /**
+     * Check if the twin is running and healthy.
+     */
+    isHealthy(): Promise<boolean>;
+    private ensureContainerRemoved;
+    private ensureImageExists;
+    private pullImage;
+    private createContainer;
+    private startContainer;
+    private waitForHealthy;
+    /**
+     * Internal: create buckets. Errors are logged but not thrown.
+     */
+    private createBuckets;
+    /**
+     * Fetch with a timeout. Aborts the request if it exceeds the given duration.
+     */
+    private fetchWithTimeout;
+}
+//# sourceMappingURL=gcs-twin.d.ts.map

package/dist/gcs/gcs-twin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcs-twin.d.ts","sourceRoot":"","sources":["../../src/gcs/gcs-twin.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,WAAW,CAAC;AAC/B,OAAO,EAAmB,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAErE;;;;;GAKG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,SAAS,CAAiC;IAClD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAEvC;;;;;OAKG;gBACS,SAAS,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM;IAM/D;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB3B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAe5B;;OAEG;IACH,eAAe,IAAI,MAAM;IAIzB;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;YAWrB,sBAAsB;YAkBtB,iBAAiB;YAYjB,SAAS;YAwBT,eAAe;YAwBf,cAAc;YAOd,cAAc;IAqB5B;;OAEG;YACW,aAAa;IA+B3B;;OAEG;YACW,gBAAgB;CAkB/B"}

package/dist/gcs/gcs-twin.js

@@ -0,0 +1,219 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import Docker from 'dockerode';
+import { createGcsConfig } from '../shared/config.js';
+/**
+ * GCS twin lifecycle manager.
+ *
+ * Starts/stops a fake‑gcs‑server Docker container, creates buckets,
+ * and sets the GCS_EMULATOR_URL environment variable.
+ */ export class GcsTwin {
+    /**
+   * Start the Docker container and create buckets.
+   *
+   * @throws {Error} If the container fails to start.
+   */ async start() {
+        console.log(`Starting GCS twin on port ${this.config.port}...`);
+        await this.ensureImageExists();
+        await this.ensureContainerRemoved();
+        await this.createContainer();
+        await this.startContainer();
+        await this.waitForHealthy();
+        await this.createBuckets();
+        process.env.GCS_EMULATOR_URL = this.config.externalUrl;
+        console.log(`GCS twin ready at ${this.config.externalUrl}`);
+    }
+    /**
+   * Stop and remove the Docker container.
+   */ async stop() {
+        if (!this.container) {
+            return;
+        }
+        console.log(`Stopping GCS twin (${this.containerName})...`);
+        try {
+            await this.container.stop();
+            await this.container.remove();
+        } catch (err) {
+            console.warn('Error stopping container:', err);
+        }
+        this.container = null;
+        delete process.env.GCS_EMULATOR_URL;
+        console.log('GCS twin stopped');
+    }
+    /**
+   * Reset all data: delete buckets then re‑create them.
+   */ async reset() {
+        console.log('Resetting GCS twin...');
+        for (const bucket of this.config.buckets){
+            try {
+                await fetch(`${this.config.externalUrl}/storage/v1/b/${bucket.name}`, {
+                    method: 'DELETE'
+                });
+            } catch (_err) {
+            // Bucket may not exist; ignore
+            }
+        }
+        await this.createBuckets();
+        console.log('GCS twin reset complete');
+    }
+    /**
+   * Get the emulator host URL for SDK configuration.
+   */ getEmulatorHost() {
+        return this.config.externalUrl;
+    }
+    /**
+   * Check if the twin is running and healthy.
+   */ async isHealthy() {
+        try {
+            const response = await fetch(`${this.config.externalUrl}/storage/v1/b`);
+            return response.ok;
+        } catch (e) {
+            return false;
+        }
+    }
+    // --- internal helpers ---
+    async ensureContainerRemoved() {
+        try {
+            const existing = this.docker.getContainer(this.containerName);
+            const info = await existing.inspect().catch(()=>null);
+            if (info) {
+                console.log(`Removing existing container ${this.containerName}...`);
+                await existing.stop().catch(()=>{
+                /* ignore */ });
+                await existing.remove().catch(()=>{
+                /* ignore */ });
+            }
+        } catch (_err) {
+        // No existing container
+        }
+    }
+    async ensureImageExists() {
+        const imageName = 'fsouza/fake-gcs-server';
+        const images = await this.docker.listImages({
+            filters: JSON.stringify({
+                reference: [
+                    imageName
+                ]
+            })
+        });
+        if (images.length === 0) {
+            console.log(`Image ${imageName} not found. Pulling...`);
+            await this.pullImage(imageName);
+        }
+    }
+    async pullImage(imageName) {
+        return new Promise((resolve, reject)=>{
+            this.docker.pull(imageName, {}, (err, stream)=>{
+                if (err || !stream) return reject(err != null ? err : new Error('No stream returned from docker.pull'));
+                this.docker.modem.followProgress(stream, (err, output)=>err ? reject(err) : resolve(output), (event)=>{
+                    if (event.status === 'Downloading' || event.status === 'Extracting') {
+                    // Optionally log progress here
+                    }
+                });
+            });
+        });
+    }
+    async createContainer() {
+        const container = await this.docker.createContainer({
+            Image: 'fsouza/fake-gcs-server',
+            name: this.containerName,
+            HostConfig: {
+                PortBindings: {
+                    '4443/tcp': [
+                        {
+                            HostPort: `${this.config.port}`
+                        }
+                    ]
+                }
+            },
+            ExposedPorts: {
+                '4443/tcp': {}
+            },
+            Cmd: [
+                '-scheme',
+                'http',
+                '-port',
+                '4443',
+                '-external-url',
+                this.config.externalUrl
+            ]
+        });
+        this.container = container;
+    }
+    async startContainer() {
+        if (!this.container) {
+            throw new Error('Container not created');
+        }
+        await this.container.start();
+    }
+    async waitForHealthy() {
+        const maxAttempts = 30;
+        const intervalMs = 500;
+        for(let attempt = 0; attempt < maxAttempts; attempt++){
+            if (await this.isHealthy()) {
+                // Small delay after health check passes — the container may report
+                // healthy before all HTTP methods are ready (common with fake-gcs-server).
+                await new Promise((resolve)=>setTimeout(resolve, 1000));
+                return;
+            }
+            await new Promise((resolve)=>setTimeout(resolve, intervalMs));
+        }
+        throw new Error(`GCS twin did not become healthy within ${maxAttempts * intervalMs / 1000}s`);
+    }
+    /**
+   * Internal: create buckets. Errors are logged but not thrown.
+   */ async createBuckets() {
+        console.log('Creating buckets...');
+        for (const bucket of this.config.buckets){
+            try {
+                const createRes = await this.fetchWithTimeout(`${this.config.externalUrl}/storage/v1/b`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json'
+                    },
+                    body: JSON.stringify({
+                        name: bucket.name
+                    })
+                }, 10000);
+                if (!createRes.ok && createRes.status !== 409) {
+                    console.warn(`Warning: failed to create bucket ${bucket.name}: ${createRes.status} ${createRes.statusText}`);
+                } else {
+                    console.log(`  Created bucket ${bucket.name}`);
+                }
+            } catch (err) {
+                console.warn(`Warning: failed to create bucket ${bucket.name}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        console.log('Bucket creation complete');
+    }
+    /**
+   * Fetch with a timeout. Aborts the request if it exceeds the given duration.
+   */ async fetchWithTimeout(url, init, timeoutMs) {
+        const controller = new AbortController();
+        const timer = setTimeout(()=>controller.abort(), timeoutMs);
+        try {
+            return await fetch(url, _extends({}, init, {
+                signal: controller.signal
+            }));
+        } catch (err) {
+            if (controller.signal.aborted) {
+                throw new Error(`Request to ${url} timed out after ${timeoutMs}ms`);
+            }
+            throw err;
+        } finally{
+            clearTimeout(timer);
+        }
+    }
+    /**
+   * Create a new GCS twin.
+   *
+   * @param overrides Optional configuration overrides (merged with defaults and env vars).
+   * @param docker Optional Docker instance (for testing).
+   */ constructor(overrides, docker){
+        this.container = null;
+        this.config = createGcsConfig(overrides);
+        this.docker = docker != null ? docker : new Docker();
+        this.containerName = `itd-gcs-twin-${this.config.port}`;
+    }
+}
+
+//# sourceMappingURL=gcs-twin.js.map

package/dist/gcs/gcs-twin.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/gcs/gcs-twin.ts"],"sourcesContent":["import Docker from 'dockerode';\nimport { createGcsConfig, GcsTwinConfig } from '../shared/config.js';\n\n/**\n * GCS twin lifecycle manager.\n *\n * Starts/stops a fake‑gcs‑server Docker container, creates buckets,\n * and sets the GCS_EMULATOR_URL environment variable.\n */\nexport class GcsTwin {\n  private readonly config: GcsTwinConfig;\n  private readonly docker: Docker;\n  private container: Docker.Container | null = null;\n  private readonly containerName: string;\n\n  /**\n   * Create a new GCS twin.\n   *\n   * @param overrides Optional configuration overrides (merged with defaults and env vars).\n   * @param docker Optional Docker instance (for testing).\n   */\n  constructor(overrides?: Partial<GcsTwinConfig>, docker?: Docker) {\n    this.config = createGcsConfig(overrides);\n    this.docker = docker ?? new Docker();\n    this.containerName = `itd-gcs-twin-${this.config.port}`;\n  }\n\n  /**\n   * Start the Docker container and create buckets.\n   *\n   * @throws {Error} If the container fails to start.\n   */\n  async start(): Promise<void> {\n    console.log(`Starting GCS twin on port ${this.config.port}...`);\n    await this.ensureImageExists();\n    await this.ensureContainerRemoved();\n    await this.createContainer();\n    await this.startContainer();\n    await this.waitForHealthy();\n    await this.createBuckets();\n    process.env.GCS_EMULATOR_URL = this.config.externalUrl;\n    console.log(`GCS twin ready at ${this.config.externalUrl}`);\n  }\n\n  /**\n   * Stop and remove the Docker container.\n   */\n  async stop(): Promise<void> {\n    if (!this.container) {\n      return;\n    }\n    console.log(`Stopping GCS twin (${this.containerName})...`);\n    try {\n      await this.container.stop();\n      await this.container.remove();\n    } catch (err) {\n      console.warn('Error stopping container:', err);\n    }\n    this.container = null;\n    delete process.env.GCS_EMULATOR_URL;\n    console.log('GCS twin stopped');\n  }\n\n  /**\n   * Reset all data: delete buckets then re‑create them.\n   */\n  async reset(): Promise<void> {\n    console.log('Resetting GCS twin...');\n    for (const bucket of this.config.buckets) {\n      try {\n        await fetch(`${this.config.externalUrl}/storage/v1/b/${bucket.name}`, {\n          method: 'DELETE',\n        });\n      } catch (_err) {\n        // Bucket may not exist; ignore\n      }\n    }\n    await this.createBuckets();\n    console.log('GCS twin reset complete');\n  }\n\n  /**\n   * Get the emulator host URL for SDK configuration.\n   */\n  getEmulatorHost(): string {\n    return this.config.externalUrl;\n  }\n\n  /**\n   * Check if the twin is running and healthy.\n   */\n  async isHealthy(): Promise<boolean> {\n    try {\n      const response = await fetch(`${this.config.externalUrl}/storage/v1/b`);\n      return response.ok;\n    } catch {\n      return false;\n    }\n  }\n\n  // --- internal helpers ---\n\n  private async ensureContainerRemoved(): Promise<void> {\n    try {\n      const existing = this.docker.getContainer(this.containerName);\n      const info = await existing.inspect().catch(() => null);\n      if (info) {\n        console.log(`Removing existing container ${this.containerName}...`);\n        await existing.stop().catch(() => {\n          /* ignore */\n        });\n        await existing.remove().catch(() => {\n          /* ignore */\n        });\n      }\n    } catch (_err) {\n      // No existing container\n    }\n  }\n\n  private async ensureImageExists(): Promise<void> {\n    const imageName = 'fsouza/fake-gcs-server';\n    const images = await this.docker.listImages({\n      filters: JSON.stringify({ reference: [imageName] }),\n    });\n\n    if (images.length === 0) {\n      console.log(`Image ${imageName} not found. Pulling...`);\n      await this.pullImage(imageName);\n    }\n  }\n\n  private async pullImage(imageName: string): Promise<void> {\n    return new Promise((resolve, reject) => {\n      this.docker.pull(imageName, {}, (err, stream) => {\n        if (err || !stream)\n          return reject(\n            err ?? new Error('No stream returned from docker.pull')\n          );\n        this.docker.modem.followProgress(\n          stream,\n          (err: Error | null, output: any) =>\n            err ? reject(err) : resolve(output),\n          (event: any) => {\n            if (\n              event.status === 'Downloading' ||\n              event.status === 'Extracting'\n            ) {\n              // Optionally log progress here\n            }\n          }\n        );\n      });\n    });\n  }\n\n  private async createContainer(): Promise<void> {\n    const container = await this.docker.createContainer({\n      Image: 'fsouza/fake-gcs-server',\n      name: this.containerName,\n      HostConfig: {\n        PortBindings: {\n          '4443/tcp': [{ HostPort: `${this.config.port}` }],\n        },\n      },\n      ExposedPorts: {\n        '4443/tcp': {},\n      },\n      Cmd: [\n        '-scheme',\n        'http',\n        '-port',\n        '4443',\n        '-external-url',\n        this.config.externalUrl,\n      ],\n    });\n    this.container = container;\n  }\n\n  private async startContainer(): Promise<void> {\n    if (!this.container) {\n      throw new Error('Container not created');\n    }\n    await this.container.start();\n  }\n\n  private async waitForHealthy(): Promise<void> {\n    const maxAttempts = 30;\n    const intervalMs = 500;\n\n    for (let attempt = 0; attempt < maxAttempts; attempt++) {\n      if (await this.isHealthy()) {\n        // Small delay after health check passes — the container may report\n        // healthy before all HTTP methods are ready (common with fake-gcs-server).\n        await new Promise((resolve) => setTimeout(resolve, 1000));\n        return;\n      }\n      await new Promise((resolve) => setTimeout(resolve, intervalMs));\n    }\n\n    throw new Error(\n      `GCS twin did not become healthy within ${\n        (maxAttempts * intervalMs) / 1000\n      }s`\n    );\n  }\n\n  /**\n   * Internal: create buckets. Errors are logged but not thrown.\n   */\n  private async createBuckets(): Promise<void> {\n    console.log('Creating buckets...');\n    for (const bucket of this.config.buckets) {\n      try {\n        const createRes = await this.fetchWithTimeout(\n          `${this.config.externalUrl}/storage/v1/b`,\n          {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ name: bucket.name }),\n          },\n          10_000\n        );\n        if (!createRes.ok && createRes.status !== 409) {\n          console.warn(\n            `Warning: failed to create bucket ${bucket.name}: ${createRes.status} ${createRes.statusText}`\n          );\n        } else {\n          console.log(`  Created bucket ${bucket.name}`);\n        }\n      } catch (err) {\n        console.warn(\n          `Warning: failed to create bucket ${bucket.name}: ${\n            err instanceof Error ? err.message : String(err)\n          }`\n        );\n      }\n    }\n    console.log('Bucket creation complete');\n  }\n\n  /**\n   * Fetch with a timeout. Aborts the request if it exceeds the given duration.\n   */\n  private async fetchWithTimeout(\n    url: string,\n    init: RequestInit,\n    timeoutMs: number\n  ): Promise<Response> {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), timeoutMs);\n    try {\n      return await fetch(url, { ...init, signal: controller.signal });\n    } catch (err) {\n      if (controller.signal.aborted) {\n        throw new Error(`Request to ${url} timed out after ${timeoutMs}ms`);\n      }\n      throw err;\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n}\n"],"names":["Docker","createGcsConfig","GcsTwin","start","console","log","config","port","ensureImageExists","ensureContainerRemoved","createContainer","startContainer","waitForHealthy","createBuckets","process","env","GCS_EMULATOR_URL","externalUrl","stop","container","containerName","remove","err","warn","reset","bucket","buckets","fetch","name","method","_err","getEmulatorHost","isHealthy","response","ok","existing","docker","getContainer","info","inspect","catch","imageName","images","listImages","filters","JSON","stringify","reference","length","pullImage","Promise","resolve","reject","pull","stream","Error","modem","followProgress","output","event","status","Image","HostConfig","PortBindings","HostPort","ExposedPorts","Cmd","maxAttempts","intervalMs","attempt","setTimeout","createRes","fetchWithTimeout","headers","body","statusText","message","String","url","init","timeoutMs","controller","AbortController","timer","abort","signal","aborted","clearTimeout","constructor","overrides"],"rangeMappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;","mappings":"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"}

package/dist/gcs/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Public API for the GCS twin.
+ */
+export { GcsTwin } from './gcs-twin.js';
+export type { GcsTwinConfig, BucketConfig } from './gcs-twin.config.js';
+export { defaultGcsConfig } from './gcs-twin.config.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/gcs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/gcs/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/gcs/index.js

@@ -0,0 +1,6 @@
+/**
+ * Public API for the GCS twin.
+ */ export { GcsTwin } from './gcs-twin.js';
+export { defaultGcsConfig } from './gcs-twin.config.js';
+
+//# sourceMappingURL=index.js.map

package/dist/gcs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/gcs/index.ts"],"sourcesContent":["/**\n * Public API for the GCS twin.\n */\n\nexport { GcsTwin } from './gcs-twin.js';\nexport type { GcsTwinConfig, BucketConfig } from './gcs-twin.config.js';\nexport { defaultGcsConfig } from './gcs-twin.config.js';\n"],"names":["GcsTwin","defaultGcsConfig"],"rangeMappings":";;;","mappings":"AAAA;;CAEC,GAED,SAASA,OAAO,QAAQ,gBAAgB;AAExC,SAASC,gBAAgB,QAAQ,uBAAuB"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './lib/integration-test-doubles.js';
+export * from './shared/constants.js';
+export * from './shared/activation.js';
+export * from './shared/config.js';
+export * from './gcs/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mCAAmC,CAAC;AAGlD,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from './lib/integration-test-doubles.js';
+// Shared constants and utilities
+export * from './shared/constants.js';
+export * from './shared/activation.js';
+export * from './shared/config.js';
+// GCS twin
+export * from './gcs/index.js';
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './lib/integration-test-doubles.js';\n\n// Shared constants and utilities\nexport * from './shared/constants.js';\nexport * from './shared/activation.js';\nexport * from './shared/config.js';\n\n// GCS twin\nexport * from './gcs/index.js';\n"],"names":[],"rangeMappings":";;;;;;","mappings":"AAAA,cAAc,oCAAoC;AAElD,iCAAiC;AACjC,cAAc,wBAAwB;AACtC,cAAc,yBAAyB;AACvC,cAAc,qBAAqB;AAEnC,WAAW;AACX,cAAc,iBAAiB"}

package/dist/lib/integration-test-doubles.d.ts

@@ -0,0 +1,2 @@
+export declare function integrationTestDoubles(): string;
+//# sourceMappingURL=integration-test-doubles.d.ts.map

package/dist/lib/integration-test-doubles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration-test-doubles.d.ts","sourceRoot":"","sources":["../../src/lib/integration-test-doubles.ts"],"names":[],"mappings":"AAAA,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C"}

package/dist/lib/integration-test-doubles.js

@@ -0,0 +1,5 @@
+export function integrationTestDoubles() {
+    return 'integration-test-doubles';
+}
+
+//# sourceMappingURL=integration-test-doubles.js.map

package/dist/lib/integration-test-doubles.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/integration-test-doubles.ts"],"sourcesContent":["export function integrationTestDoubles(): string {\n  return 'integration-test-doubles';\n}\n"],"names":["integrationTestDoubles"],"rangeMappings":";;","mappings":"AAAA,OAAO,SAASA;IACd,OAAO;AACT"}

package/dist/shared/activation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Activation gate for integration‑test‑doubles.
+ * Twins should only start when the test‑mode environment variable is set.
+ */
+/**
+ * Returns `true` if the library is running in test mode.
+ *
+ * Test mode is enabled when the environment variable `TEST_MODE` is exactly the string `'true'`.
+ * This check is case‑sensitive.
+ *
+ * @example
+ * ```ts
+ * if (isTestMode()) {
+ *   await twin.start();
+ * }
+ * ```
+ */
+export declare function isTestMode(): boolean;
+//# sourceMappingURL=activation.d.ts.map

package/dist/shared/activation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation.d.ts","sourceRoot":"","sources":["../../src/shared/activation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAEpC"}

package/dist/shared/activation.js

@@ -0,0 +1,20 @@
+/**
+ * Activation gate for integration‑test‑doubles.
+ * Twins should only start when the test‑mode environment variable is set.
+ */ /**
+ * Returns `true` if the library is running in test mode.
+ *
+ * Test mode is enabled when the environment variable `TEST_MODE` is exactly the string `'true'`.
+ * This check is case‑sensitive.
+ *
+ * @example
+ * ```ts
+ * if (isTestMode()) {
+ *   await twin.start();
+ * }
+ * ```
+ */ export function isTestMode() {
+    return process.env.TEST_MODE === 'true';
+}
+
+//# sourceMappingURL=activation.js.map

package/dist/shared/activation.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/shared/activation.ts"],"sourcesContent":["/**\n * Activation gate for integration‑test‑doubles.\n * Twins should only start when the test‑mode environment variable is set.\n */\n\n/**\n * Returns `true` if the library is running in test mode.\n *\n * Test mode is enabled when the environment variable `TEST_MODE` is exactly the string `'true'`.\n * This check is case‑sensitive.\n *\n * @example\n * ```ts\n * if (isTestMode()) {\n *   await twin.start();\n * }\n * ```\n */\nexport function isTestMode(): boolean {\n  return process.env.TEST_MODE === 'true';\n}\n"],"names":["isTestMode","process","env","TEST_MODE"],"rangeMappings":";;;;;;;;;;;;;;;;;","mappings":"AAAA;;;CAGC,GAED;;;;;;;;;;;;CAYC,GACD,OAAO,SAASA;IACd,OAAOC,QAAQC,GAAG,CAACC,SAAS,KAAK;AACnC"}

package/dist/shared/config.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Configuration for a single bucket to create on startup.
+ */
+export interface BucketConfig {
+    /** Bucket name */
+    name: string;
+}
+/**
+ * Configuration for the GCS twin.
+ */
+export interface GcsTwinConfig {
+    /** Port the fake‑gcs‑server listens on */
+    port: number;
+    /** External URL the SDK will connect to (e.g., http://localhost:9013) */
+    externalUrl: string;
+    /** Optional persistent data directory (if not set, data is ephemeral) */
+    dataDir?: string;
+    /** Buckets to create on startup */
+    buckets: BucketConfig[];
+}
+/**
+ * Default configuration for the GCS twin.
+ *
+ * Values are derived from the implementation guide (docs/replication‑engine/twins/01‑gcs‑twin.md).
+ */
+export declare const defaultGcsConfig: GcsTwinConfig;
+/**
+ * Creates a GcsTwinConfig by merging defaults, environment variables, and explicit overrides.
+ *
+ * Environment variables take precedence over defaults.
+ * Explicit overrides (passed as argument) take precedence over environment variables.
+ *
+ * @param overrides - Partial configuration that overrides both defaults and environment variables.
+ * @returns A complete GcsTwinConfig.
+ */
+export declare function createGcsConfig(overrides?: Partial<GcsTwinConfig>): GcsTwinConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/shared/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/shared/config.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,aAI9B,CAAC;AA6BF;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,SAAS,GAAE,OAAO,CAAC,aAAa,CAAM,GACrC,aAAa,CAoCf"}

package/dist/shared/config.js

@@ -0,0 +1,70 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { ConfigService, nodeEnvAdapter } from '@open-kingdom/shared-poly-util-env-config';
+import { DEFAULT_PORTS, ENV_VARS, PORT_RANGE } from './constants.js';
+/**
+ * Default configuration for the GCS twin.
+ *
+ * Values are derived from the implementation guide (docs/replication‑engine/twins/01‑gcs‑twin.md).
+ */ export const defaultGcsConfig = {
+    port: DEFAULT_PORTS.GCS,
+    externalUrl: `http://localhost:${DEFAULT_PORTS.GCS}`,
+    buckets: [
+        {
+            name: 'app-assets'
+        },
+        {
+            name: 'user-uploads'
+        }
+    ]
+};
+/**
+ * Environment‑variable keys that affect GCS twin configuration.
+ */ const _CONFIG_ENV_KEYS = [
+    ENV_VARS.GCS_TWIN_PORT,
+    ENV_VARS.GCS_TWIN_DATA_DIR
+];
+/**
+ * Creates a typed ConfigService for GCS twin environment variables.
+ */ function createEnvConfigService() {
+    return new ConfigService(nodeEnvAdapter);
+}
+/**
+ * Parses a string environment variable as a number.
+ * Returns undefined if the variable is not set or cannot be parsed.
+ */ function parseOptionalInt(value) {
+    if (value === undefined) return undefined;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isNaN(parsed) ? undefined : parsed;
+}
+/**
+ * Creates a GcsTwinConfig by merging defaults, environment variables, and explicit overrides.
+ *
+ * Environment variables take precedence over defaults.
+ * Explicit overrides (passed as argument) take precedence over environment variables.
+ *
+ * @param overrides - Partial configuration that overrides both defaults and environment variables.
+ * @returns A complete GcsTwinConfig.
+ */ export function createGcsConfig(overrides = {}) {
+    const env = createEnvConfigService();
+    // Environment‑variable overrides
+    const envPort = parseOptionalInt(env.get(ENV_VARS.GCS_TWIN_PORT));
+    const envDataDir = env.get(ENV_VARS.GCS_TWIN_DATA_DIR);
+    const baseConfig = _extends({}, defaultGcsConfig, envPort !== undefined && {
+        port: envPort
+    }, envDataDir !== undefined && {
+        dataDir: envDataDir
+    });
+    // Explicit overrides take final precedence
+    const finalConfig = _extends({}, baseConfig, overrides);
+    // Validate port is within reserved range
+    if (finalConfig.port < PORT_RANGE.min || finalConfig.port > PORT_RANGE.max) {
+        throw new Error(`GCS twin port ${finalConfig.port} is outside the reserved range ${PORT_RANGE.min}‑${PORT_RANGE.max}. ` + `Adjust PORT_RANGE in constants.ts or set ${ENV_VARS.GCS_TWIN_PORT} appropriately.`);
+    }
+    // Ensure externalUrl matches the port (unless explicitly overridden)
+    if (!overrides.externalUrl && finalConfig.externalUrl === defaultGcsConfig.externalUrl) {
+        finalConfig.externalUrl = `http://localhost:${finalConfig.port}`;
+    }
+    return finalConfig;
+}
+
+//# sourceMappingURL=config.js.map

package/dist/shared/config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/shared/config.ts"],"sourcesContent":["import {\n  ConfigService,\n  nodeEnvAdapter,\n} from '@open-kingdom/shared-poly-util-env-config';\nimport { DEFAULT_PORTS, ENV_VARS, PORT_RANGE } from './constants.js';\n\n/**\n * Configuration for a single bucket to create on startup.\n */\nexport interface BucketConfig {\n  /** Bucket name */\n  name: string;\n}\n\n/**\n * Configuration for the GCS twin.\n */\nexport interface GcsTwinConfig {\n  /** Port the fake‑gcs‑server listens on */\n  port: number;\n  /** External URL the SDK will connect to (e.g., http://localhost:9013) */\n  externalUrl: string;\n  /** Optional persistent data directory (if not set, data is ephemeral) */\n  dataDir?: string;\n  /** Buckets to create on startup */\n  buckets: BucketConfig[];\n}\n\n/**\n * Default configuration for the GCS twin.\n *\n * Values are derived from the implementation guide (docs/replication‑engine/twins/01‑gcs‑twin.md).\n */\nexport const defaultGcsConfig: GcsTwinConfig = {\n  port: DEFAULT_PORTS.GCS,\n  externalUrl: `http://localhost:${DEFAULT_PORTS.GCS}`,\n  buckets: [{ name: 'app-assets' }, { name: 'user-uploads' }],\n};\n\n/**\n * Environment‑variable keys that affect GCS twin configuration.\n */\nconst _CONFIG_ENV_KEYS = [\n  ENV_VARS.GCS_TWIN_PORT,\n  ENV_VARS.GCS_TWIN_DATA_DIR,\n] as const;\n\n/**\n * Creates a typed ConfigService for GCS twin environment variables.\n */\nfunction createEnvConfigService(): ConfigService<\n  (typeof _CONFIG_ENV_KEYS)[number]\n> {\n  return new ConfigService(nodeEnvAdapter);\n}\n\n/**\n * Parses a string environment variable as a number.\n * Returns undefined if the variable is not set or cannot be parsed.\n */\nfunction parseOptionalInt(value: string | undefined): number | undefined {\n  if (value === undefined) return undefined;\n  const parsed = Number.parseInt(value, 10);\n  return Number.isNaN(parsed) ? undefined : parsed;\n}\n\n/**\n * Creates a GcsTwinConfig by merging defaults, environment variables, and explicit overrides.\n *\n * Environment variables take precedence over defaults.\n * Explicit overrides (passed as argument) take precedence over environment variables.\n *\n * @param overrides - Partial configuration that overrides both defaults and environment variables.\n * @returns A complete GcsTwinConfig.\n */\nexport function createGcsConfig(\n  overrides: Partial<GcsTwinConfig> = {}\n): GcsTwinConfig {\n  const env = createEnvConfigService();\n\n  // Environment‑variable overrides\n  const envPort = parseOptionalInt(env.get(ENV_VARS.GCS_TWIN_PORT));\n  const envDataDir = env.get(ENV_VARS.GCS_TWIN_DATA_DIR);\n\n  const baseConfig: GcsTwinConfig = {\n    ...defaultGcsConfig,\n    ...(envPort !== undefined && { port: envPort }),\n    ...(envDataDir !== undefined && { dataDir: envDataDir }),\n  };\n\n  // Explicit overrides take final precedence\n  const finalConfig: GcsTwinConfig = {\n    ...baseConfig,\n    ...overrides,\n  };\n\n  // Validate port is within reserved range\n  if (finalConfig.port < PORT_RANGE.min || finalConfig.port > PORT_RANGE.max) {\n    throw new Error(\n      `GCS twin port ${finalConfig.port} is outside the reserved range ${PORT_RANGE.min}‑${PORT_RANGE.max}. ` +\n        `Adjust PORT_RANGE in constants.ts or set ${ENV_VARS.GCS_TWIN_PORT} appropriately.`\n    );\n  }\n\n  // Ensure externalUrl matches the port (unless explicitly overridden)\n  if (\n    !overrides.externalUrl &&\n    finalConfig.externalUrl === defaultGcsConfig.externalUrl\n  ) {\n    finalConfig.externalUrl = `http://localhost:${finalConfig.port}`;\n  }\n\n  return finalConfig;\n}\n"],"names":["ConfigService","nodeEnvAdapter","DEFAULT_PORTS","ENV_VARS","PORT_RANGE","defaultGcsConfig","port","GCS","externalUrl","buckets","name","_CONFIG_ENV_KEYS","GCS_TWIN_PORT","GCS_TWIN_DATA_DIR","createEnvConfigService","parseOptionalInt","value","undefined","parsed","Number","parseInt","isNaN","createGcsConfig","overrides","env","envPort","get","envDataDir","baseConfig","dataDir","finalConfig","min","max","Error"],"rangeMappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;","mappings":";AAAA,SACEA,aAAa,EACbC,cAAc,QACT,4CAA4C;AACnD,SAASC,aAAa,EAAEC,QAAQ,EAAEC,UAAU,QAAQ,iBAAiB;AAwBrE;;;;CAIC,GACD,OAAO,MAAMC,mBAAkC;IAC7CC,MAAMJ,cAAcK,GAAG;IACvBC,aAAa,CAAC,iBAAiB,EAAEN,cAAcK,GAAG,CAAC,CAAC;IACpDE,SAAS;QAAC;YAAEC,MAAM;QAAa;QAAG;YAAEA,MAAM;QAAe;KAAE;AAC7D,EAAE;AAEF;;CAEC,GACD,MAAMC,mBAAmB;IACvBR,SAASS,aAAa;IACtBT,SAASU,iBAAiB;CAC3B;AAED;;CAEC,GACD,SAASC;IAGP,OAAO,IAAId,cAAcC;AAC3B;AAEA;;;CAGC,GACD,SAASc,iBAAiBC,KAAyB;IACjD,IAAIA,UAAUC,WAAW,OAAOA;IAChC,MAAMC,SAASC,OAAOC,QAAQ,CAACJ,OAAO;IACtC,OAAOG,OAAOE,KAAK,CAACH,UAAUD,YAAYC;AAC5C;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASI,gBACdC,YAAoC,CAAC,CAAC;IAEtC,MAAMC,MAAMV;IAEZ,iCAAiC;IACjC,MAAMW,UAAUV,iBAAiBS,IAAIE,GAAG,CAACvB,SAASS,aAAa;IAC/D,MAAMe,aAAaH,IAAIE,GAAG,CAACvB,SAASU,iBAAiB;IAErD,MAAMe,aAA4B,aAC7BvB,kBACCoB,YAAYR,aAAa;QAAEX,MAAMmB;IAAQ,GACzCE,eAAeV,aAAa;QAAEY,SAASF;IAAW;IAGxD,2CAA2C;IAC3C,MAAMG,cAA6B,aAC9BF,YACAL;IAGL,yCAAyC;IACzC,IAAIO,YAAYxB,IAAI,GAAGF,WAAW2B,GAAG,IAAID,YAAYxB,IAAI,GAAGF,WAAW4B,GAAG,EAAE;QAC1E,MAAM,IAAIC,MACR,CAAC,cAAc,EAAEH,YAAYxB,IAAI,CAAC,+BAA+B,EAAEF,WAAW2B,GAAG,CAAC,CAAC,EAAE3B,WAAW4B,GAAG,CAAC,EAAE,CAAC,GACrG,CAAC,yCAAyC,EAAE7B,SAASS,aAAa,CAAC,eAAe,CAAC;IAEzF;IAEA,qEAAqE;IACrE,IACE,CAACW,UAAUf,WAAW,IACtBsB,YAAYtB,WAAW,KAAKH,iBAAiBG,WAAW,EACxD;QACAsB,YAAYtB,WAAW,GAAG,CAAC,iBAAiB,EAAEsB,YAAYxB,IAAI,CAAC,CAAC;IAClE;IAEA,OAAOwB;AACT"}

package/dist/shared/constants.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared constants for integration‑test‑doubles library.
+ */
+/**
+ * Port range reserved for twin emulators.
+ * Twins should use fixed ports within this range to avoid collisions.
+ */
+export declare const PORT_RANGE: {
+    readonly min: 9010;
+    readonly max: 9020;
+};
+/**
+ * Default port assignments for each twin.
+ */
+export declare const DEFAULT_PORTS: {
+    /** Google Cloud Storage twin */
+    readonly GCS: 9013;
+    /** Gmail/Google Workspace Email twin (future) */
+    readonly GMAIL: 9014;
+    /** Google Auth twin (future) */
+    readonly GOOGLE_AUTH: 9015;
+    /** YouTube twin (future) */
+    readonly YOUTUBE: 9016;
+    /** Google Calendar twin (future) */
+    readonly GOOGLE_CALENDAR: 9017;
+    /** Spotify twin (future) */
+    readonly SPOTIFY: 9018;
+};
+/**
+ * Environment variable names used by the library.
+ */
+export declare const ENV_VARS: {
+    /** Activation gate — must be 'true' for twins to start */
+    readonly TEST_MODE: "TEST_MODE";
+    /** GCS twin port override */
+    readonly GCS_TWIN_PORT: "GCS_TWIN_PORT";
+    /** GCS twin persistent data directory (optional) */
+    readonly GCS_TWIN_DATA_DIR: "GCS_TWIN_DATA_DIR";
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/shared/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/shared/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,eAAO,MAAM,UAAU;;;CAGb,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,aAAa;IACxB,gCAAgC;;IAEhC,iDAAiD;;IAEjD,gCAAgC;;IAEhC,4BAA4B;;IAE5B,oCAAoC;;IAEpC,4BAA4B;;CAEpB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,QAAQ;IACnB,0DAA0D;;IAE1D,6BAA6B;;IAE7B,oDAAoD;;CAE5C,CAAC"}

package/dist/shared/constants.js

@@ -0,0 +1,28 @@
+/**
+ * Shared constants for integration‑test‑doubles library.
+ */ /**
+ * Port range reserved for twin emulators.
+ * Twins should use fixed ports within this range to avoid collisions.
+ */ export const PORT_RANGE = {
+    min: 9010,
+    max: 9020
+};
+/**
+ * Default port assignments for each twin.
+ */ export const DEFAULT_PORTS = {
+    /** Google Cloud Storage twin */ GCS: 9013,
+    /** Gmail/Google Workspace Email twin (future) */ GMAIL: 9014,
+    /** Google Auth twin (future) */ GOOGLE_AUTH: 9015,
+    /** YouTube twin (future) */ YOUTUBE: 9016,
+    /** Google Calendar twin (future) */ GOOGLE_CALENDAR: 9017,
+    /** Spotify twin (future) */ SPOTIFY: 9018
+};
+/**
+ * Environment variable names used by the library.
+ */ export const ENV_VARS = {
+    /** Activation gate — must be 'true' for twins to start */ TEST_MODE: 'TEST_MODE',
+    /** GCS twin port override */ GCS_TWIN_PORT: 'GCS_TWIN_PORT',
+    /** GCS twin persistent data directory (optional) */ GCS_TWIN_DATA_DIR: 'GCS_TWIN_DATA_DIR'
+};
+
+//# sourceMappingURL=constants.js.map

package/dist/shared/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/shared/constants.ts"],"sourcesContent":["/**\n * Shared constants for integration‑test‑doubles library.\n */\n\n/**\n * Port range reserved for twin emulators.\n * Twins should use fixed ports within this range to avoid collisions.\n */\nexport const PORT_RANGE = {\n  min: 9010,\n  max: 9020,\n} as const;\n\n/**\n * Default port assignments for each twin.\n */\nexport const DEFAULT_PORTS = {\n  /** Google Cloud Storage twin */\n  GCS: 9013,\n  /** Gmail/Google Workspace Email twin (future) */\n  GMAIL: 9014,\n  /** Google Auth twin (future) */\n  GOOGLE_AUTH: 9015,\n  /** YouTube twin (future) */\n  YOUTUBE: 9016,\n  /** Google Calendar twin (future) */\n  GOOGLE_CALENDAR: 9017,\n  /** Spotify twin (future) */\n  SPOTIFY: 9018,\n} as const;\n\n/**\n * Environment variable names used by the library.\n */\nexport const ENV_VARS = {\n  /** Activation gate — must be 'true' for twins to start */\n  TEST_MODE: 'TEST_MODE',\n  /** GCS twin port override */\n  GCS_TWIN_PORT: 'GCS_TWIN_PORT',\n  /** GCS twin persistent data directory (optional) */\n  GCS_TWIN_DATA_DIR: 'GCS_TWIN_DATA_DIR',\n} as const;\n"],"names":["PORT_RANGE","min","max","DEFAULT_PORTS","GCS","GMAIL","GOOGLE_AUTH","YOUTUBE","GOOGLE_CALENDAR","SPOTIFY","ENV_VARS","TEST_MODE","GCS_TWIN_PORT","GCS_TWIN_DATA_DIR"],"rangeMappings":";;;;;;;;;;;;;;;;;;;;;;;;;","mappings":"AAAA;;CAEC,GAED;;;CAGC,GACD,OAAO,MAAMA,aAAa;IACxBC,KAAK;IACLC,KAAK;AACP,EAAW;AAEX;;CAEC,GACD,OAAO,MAAMC,gBAAgB;IAC3B,8BAA8B,GAC9BC,KAAK;IACL,+CAA+C,GAC/CC,OAAO;IACP,8BAA8B,GAC9BC,aAAa;IACb,0BAA0B,GAC1BC,SAAS;IACT,kCAAkC,GAClCC,iBAAiB;IACjB,0BAA0B,GAC1BC,SAAS;AACX,EAAW;AAEX;;CAEC,GACD,OAAO,MAAMC,WAAW;IACtB,wDAAwD,GACxDC,WAAW;IACX,2BAA2B,GAC3BC,eAAe;IACf,kDAAkD,GAClDC,mBAAmB;AACrB,EAAW"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@open-kingdom/shared-backend-integration-test-doubles",
+  "version": "0.0.2-17",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@open-kingdom/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "README.md",
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "nx": {
+    "name": "integration-test-doubles",
+    "sourceRoot": "libs/shared/backend/integration-test-doubles/src",
+    "tags": [
+      "scope:shared",
+      "type:feature",
+      "environment:backend"
+    ],
+    "targets": {
+      "build": {
+        "executor": "@nx/js:swc",
+        "outputs": [
+          "{options.outputPath}"
+        ],
+        "options": {
+          "outputPath": "libs/shared/backend/integration-test-doubles/dist",
+          "main": "libs/shared/backend/integration-test-doubles/src/index.ts",
+          "tsConfig": "libs/shared/backend/integration-test-doubles/tsconfig.lib.json",
+          "skipTypeCheck": true,
+          "stripLeadingPaths": true
+        }
+      },
+      "start:twin": {
+        "command": "npx tsx libs/shared/backend/integration-test-doubles/scripts/start-twin.ts",
+        "dependsOn": [
+          "^build"
+        ]
+      }
+    }
+  },
+  "dependencies": {
+    "@open-kingdom/shared-poly-util-env-config": "0.0.2-17",
+    "dockerode": "^4.0.6",
+    "tslib": "^2.3.0"
+  }
+}