@git.zone/cli 2.22.0 → 2.24.0

package/ts/mod_services/classes.servicemanager.ts

@@ -3,7 +3,43 @@ import * as helpers from './helpers.js';
 import { ServiceConfiguration } from './classes.serviceconfiguration.js';
 import { DockerContainer } from './classes.dockercontainer.js';
 import { GlobalRegistry } from './classes.globalregistry.js';
+import {
+  getServiceContainerLabels,
+  recordServiceDataDirectory,
+  serviceImages,
+  type TServiceName,
+} from './classes.servicedatamarker.js';
 import { logger } from '../gitzone.logging.js';
+import type { ContainerStatus } from './classes.dockercontainer.js';
+
+export interface IServiceStatus {
+  service: TServiceName;
+  enabled: boolean;
+  container: string;
+  status: ContainerStatus;
+  port: string;
+  connectionString: string;
+  dataDirectory: string;
+  dataSizeBytes: number;
+  /** Only meaningful when the container does not exist yet. */
+  portAvailable: boolean | null;
+  /** MongoDB only: whether the instance enforces authentication. */
+  authEnabled?: boolean;
+}
+
+export interface IServicesStatus {
+  project: {
+    name: string;
+    path: string;
+    enabledServices: string[];
+  };
+  services: {
+    mongodb: IServiceStatus;
+    minio: IServiceStatus;
+    elasticsearch: IServiceStatus;
+  };
+  totalDataBytes: number;
+}
 
 export class ServiceManager {
   private config: ServiceConfiguration;
@@ -31,11 +67,32 @@ export class ServiceManager {
     await this.config.loadOrCreate();
     logger.log('info', `📋 Project: ${this.config.getConfig().PROJECT_NAME}`);
 
+    // The unsafe-exposure guard is deliberately NOT enforced here. init() runs
+    // for every project command, so refusing at this point would also block
+    // stop, remove, clean, status and logs — the commands needed to recover from
+    // the misconfiguration. It is enforced where it matters, on the path that
+    // actually starts an unauthenticated database.
+    if (!this.config.isMongoAuthEnabled()) {
+      logger.log('note', '⚠️  MongoDB auth is disabled for this project (loopback only)');
+    }
+
     // Load service selection from .smartconfig.json
     await this.loadServiceConfiguration();
 
     // Validate and update ports if needed
     await this.config.validateAndUpdatePorts();
+
+    // Any services command run in a project counts as activity. Without this
+    // lastActive only advanced on start, so an actively used project could look
+    // stale to the reaper.
+    await this.globalRegistry.touchProject(process.cwd());
+  }
+
+  /**
+   * Expose the resolved service configuration to the command layer.
+   */
+  public getConfiguration(): ServiceConfiguration {
+    return this.config;
   }
 
   /**
@@ -113,9 +170,32 @@ export class ServiceManager {
   }
 
   /**
-   * Register this project with the global registry
+   * Prepare a service's data directory: create it and record tool ownership.
+   *
+   * The marker written here is what later allows `gitzone services prune` to
+   * prove the directory is reclaimable instead of guessing from its path.
    */
-  private async registerWithGlobalRegistry(): Promise<void> {
+  private async prepareDataDirectory(
+    serviceArg: TServiceName,
+    dataPathArg: string,
+  ): Promise<{ [key: string]: string }> {
+    await plugins.smartfs.directory(dataPathArg).recursive().create();
+    await recordServiceDataDirectory(process.cwd(), serviceArg);
+    return getServiceContainerLabels({
+      projectPath: process.cwd(),
+      service: serviceArg,
+      dataPath: dataPathArg,
+    });
+  }
+
+  /**
+   * Register this project with the global registry.
+   *
+   * Public and called from the command layer after any start path: previously
+   * only `startAll` registered, so `gitzone services start mongo` created a
+   * container the registry never knew about and prune could never account for.
+   */
+  public async registerWithGlobalRegistry(): Promise<void> {
     const config = this.config.getConfig();
     const containers = this.config.getContainerNames();
 
@@ -157,85 +237,81 @@ export class ServiceManager {
       await this.startElasticsearch();
       first = false;
     }
-
-    // Register with global registry
-    await this.registerWithGlobalRegistry();
   }
 
   /**
-   * Stop all enabled services
+   * Stop every service container belonging to this project.
+   *
+   * Deliberately not filtered by the enabled-service list: disabling a service
+   * previously left its container running with no command able to stop it,
+   * which is how projects accumulated forgotten containers. Stopping a service
+   * that is not running is a no-op, so covering all three is always safe.
    */
   public async stopAll(): Promise<void> {
-    let first = true;
-    if (this.isServiceEnabled('mongodb')) {
-      if (!first) console.log();
-      await this.stopMongoDB();
-      first = false;
-    }
-    if (this.isServiceEnabled('minio')) {
-      if (!first) console.log();
-      await this.stopMinIO();
-      first = false;
-    }
-    if (this.isServiceEnabled('elasticsearch')) {
-      if (!first) console.log();
-      await this.stopElasticsearch();
-      first = false;
-    }
+    await this.stopMongoDB();
+    console.log();
+    await this.stopMinIO();
+    console.log();
+    await this.stopElasticsearch();
   }
 
   /**
    * Start MongoDB service
+   *
+   * MongoDB runs as a single-node replica set so that multi-document
+   * transactions work. Auth + replSet requires a keyfile; mongod listens on
+   * MONGODB_PORT inside the container too, so the advertised member address
+   * (localhost:MONGODB_PORT) is reachable from host and container alike.
    */
   public async startMongoDB(): Promise<void> {
     logger.log('note', '📦 MongoDB:');
-    
+
     const config = this.config.getConfig();
     const containers = this.config.getContainerNames();
     const directories = this.config.getDataDirectories();
-    
-    // Ensure data directory exists
-    await plugins.smartfs.directory(directories.mongo).recursive().create();
-    
+
+    // Ensure data directory exists and is marked as tool-owned
+    await this.prepareDataDirectory('mongodb', directories.mongo);
+
     const status = await this.docker.getStatus(containers.mongo);
-    
+
+    // Containers created before replica-set support, with a changed port, or
+    // running the other auth mode must be recreated; the data is preserved.
+    let needsRecreate = false;
+    if (status !== 'not_exists') {
+      const containerCmd = await this.getMongoContainerCmd(containers.mongo);
+      const hasReplSet = containerCmd.includes('--replSet');
+      const hasKeyFile = containerCmd.includes('--keyFile');
+      const portMappings = await this.docker.getPortMappings(containers.mongo);
+      const portMatches =
+        !!portMappings && portMappings[config.MONGODB_PORT] === config.MONGODB_PORT;
+      const authMatches = hasKeyFile === this.config.isMongoAuthEnabled();
+      needsRecreate = !hasReplSet || !portMatches || !authMatches;
+      if (!authMatches) {
+        logger.log(
+          'note',
+          `  Auth mode changed to ${this.config.isMongoAuthEnabled() ? 'enabled' : 'disabled'}, recreating container...`,
+        );
+      }
+    }
+
     switch (status) {
       case 'running':
-        logger.log('ok', '  Already running ✓');
+        if (!needsRecreate) {
+          logger.log('ok', '  Already running ✓');
+          break;
+        }
+        logger.log('note', '  Upgrading to single-node replica set, recreating container...');
+        await this.docker.remove(containers.mongo, true);
+        await this.createMongoContainer();
         break;
-        
+
       case 'stopped':
-        // Check if port mapping matches config
-        const mongoPortMappings = await this.docker.getPortMappings(containers.mongo);
-        if (mongoPortMappings && mongoPortMappings['27017'] !== config.MONGODB_PORT) {
-          logger.log('note', '  Port configuration changed, recreating container...');
+        if (needsRecreate) {
+          logger.log('note', '  Configuration changed, recreating container...');
           await this.docker.remove(containers.mongo, true);
-          // Fall through to create new container
-          const success = await this.docker.run({
-            name: containers.mongo,
-            image: 'mongo:7.0',
-            ports: {
-              [`0.0.0.0:${config.MONGODB_PORT}`]: '27017'
-            },
-            volumes: {
-              [directories.mongo]: '/data/db'
-            },
-            environment: {
-              MONGO_INITDB_ROOT_USERNAME: config.MONGODB_USER,
-              MONGO_INITDB_ROOT_PASSWORD: config.MONGODB_PASS,
-              MONGO_INITDB_DATABASE: config.MONGODB_NAME
-            },
-            restart: 'unless-stopped',
-            command: '--bind_ip_all'
-          });
-          
-          if (success) {
-            logger.log('ok', '  Recreated with new port ✓');
-          } else {
-            logger.log('error', '  Failed to recreate container');
-          }
+          await this.createMongoContainer();
         } else {
-          // Ports match, just start the container
           if (await this.docker.start(containers.mongo)) {
             logger.log('ok', '  Started ✓');
           } else {
@@ -243,44 +319,218 @@ export class ServiceManager {
           }
         }
         break;
-        
+
       case 'not_exists':
         logger.log('note', '  Creating container...');
-        
-        const success = await this.docker.run({
-          name: containers.mongo,
-          image: 'mongo:7.0',
-          ports: {
-            [`0.0.0.0:${config.MONGODB_PORT}`]: '27017'
-          },
-          volumes: {
-            [directories.mongo]: '/data/db'
-          },
-          environment: {
-            MONGO_INITDB_ROOT_USERNAME: config.MONGODB_USER,
-            MONGO_INITDB_ROOT_PASSWORD: config.MONGODB_PASS,
-            MONGO_INITDB_DATABASE: config.MONGODB_NAME
-          },
-          restart: 'unless-stopped',
-          command: '--bind_ip_all'
-        });
-        
-        if (success) {
-          logger.log('ok', '  Created and started ✓');
-        } else {
-          logger.log('error', '  Failed to create container');
-        }
+        await this.createMongoContainer();
         break;
     }
-    
+
+    await this.ensureMongoRootUser();
+    await this.ensureMongoReplicaSetInitiated();
+
     logger.log('info', `  Container: ${containers.mongo}`);
     logger.log('info', `  Port: ${config.MONGODB_PORT}`);
+    if (!this.config.isMongoAuthEnabled()) {
+      logger.log('note', '  ⚠️  Auth: DISABLED — published on loopback only (127.0.0.1)');
+    }
     logger.log('info', `  Connection: ${this.config.getMongoConnectionString()}`);
-    
-    // Show Compass connection string
-    const networkIp = await helpers.getLocalNetworkIp();
-    const compassString = `mongodb://${config.MONGODB_USER}:${config.MONGODB_PASS}@${networkIp}:${config.MONGODB_PORT}/${config.MONGODB_NAME}?authSource=admin`;
-    logger.log('ok', `  Compass: ${compassString}`);
+
+    // Show Compass connection string. Only meaningful while the database is
+    // reachable off-host, which is exactly the auth-enabled case.
+    if (this.config.isMongoAuthEnabled()) {
+      const networkIp = await helpers.getLocalNetworkIp();
+      const compassString = `mongodb://${config.MONGODB_USER}:${config.MONGODB_PASS}@${networkIp}:${config.MONGODB_PORT}/${config.MONGODB_NAME}?authSource=admin&directConnection=true`;
+      logger.log('ok', `  Compass: ${compassString}`);
+    }
+  }
+
+  /**
+   * Create the MongoDB container as a single-node replica set
+   */
+  private async createMongoContainer(): Promise<void> {
+    const config = this.config.getConfig();
+    const containers = this.config.getContainerNames();
+    const directories = this.config.getDataDirectories();
+    const authEnabled = this.config.isMongoAuthEnabled();
+
+    // Never create an unauthenticated instance that is reachable off-host.
+    this.config.assertMongoExposureIsSafe();
+
+    const labels = getServiceContainerLabels({
+      projectPath: process.cwd(),
+      service: 'mongodb',
+      dataPath: directories.mongo,
+    });
+
+    // Auth + replSet requires a keyfile. Without auth no keyfile is needed, and
+    // the root-user env vars must be omitted because the official entrypoint
+    // turns them into `--auth`.
+    const command = authEnabled
+      ? `--replSet rs0 --keyFile /data/db/mongo-keyfile --port ${config.MONGODB_PORT} --bind_ip_all`
+      : `--replSet rs0 --port ${config.MONGODB_PORT} --bind_ip_all`;
+    const environment: { [key: string]: string } = {
+      MONGO_INITDB_DATABASE: config.MONGODB_NAME,
+    };
+    if (authEnabled) {
+      environment.MONGO_INITDB_ROOT_USERNAME = config.MONGODB_USER;
+      environment.MONGO_INITDB_ROOT_PASSWORD = config.MONGODB_PASS;
+    }
+    // Publishing scope is the actual exposure control: mongod's --bind_ip_all
+    // only binds inside the container's netns.
+    const publishHost = authEnabled ? '0.0.0.0' : '127.0.0.1';
+
+    if (authEnabled) {
+      await this.ensureMongoKeyfile(directories.mongo);
+    }
+
+    const success = await this.docker.run({
+      name: containers.mongo,
+      image: 'mongo:7.0',
+      ports: {
+        [`${publishHost}:${config.MONGODB_PORT}`]: config.MONGODB_PORT
+      },
+      volumes: {
+        [directories.mongo]: '/data/db'
+      },
+      environment,
+      labels,
+      restart: 'unless-stopped',
+      command
+    });
+
+    if (success) {
+      logger.log('ok', '  Created and started ✓');
+    } else {
+      logger.log('error', '  Failed to create container');
+    }
+  }
+
+  /**
+   * Generate the replica-set keyfile inside the data volume if missing.
+   * Created through a root one-off container so ownership (mongodb uid 999)
+   * is correct under both rootful and rootless Docker.
+   */
+  private async ensureMongoKeyfile(mongoDataDir: string): Promise<void> {
+    const keyfilePath = plugins.path.join(mongoDataDir, 'mongo-keyfile');
+    if (await plugins.smartfs.file(keyfilePath).exists()) {
+      return;
+    }
+    logger.log('note', '  Generating replica set keyfile...');
+    await this.docker.runOneOff({
+      image: 'mongo:7.0',
+      command:
+        'openssl rand -base64 756 > /data/db/mongo-keyfile && chown 999:999 /data/db/mongo-keyfile && chmod 400 /data/db/mongo-keyfile',
+      volumes: { [mongoDataDir]: '/data/db' },
+      user: '0'
+    });
+  }
+
+  /**
+   * The mongod argv the container was created with
+   */
+  private async getMongoContainerCmd(containerName: string): Promise<string[]> {
+    const info = await this.docker.inspect(containerName);
+    return info?.[0]?.Config?.Cmd ?? [];
+  }
+
+  /**
+   * Make sure the configured root user exists when auth is enabled.
+   *
+   * `MONGO_INITDB_ROOT_USERNAME` only takes effect on an empty dbpath, so data
+   * that was first created with auth disabled has no user at all. Enabling auth
+   * over it would leave an unusable database. MongoDB's localhost exception is
+   * the designed bootstrap path for exactly this: while zero users exist, a
+   * connection from localhost — which, inside the container, is what this is —
+   * may create the first one. If users already exist the exception does not
+   * apply and creation fails, so this can never overwrite or escalate anything.
+   */
+  private async ensureMongoRootUser(): Promise<void> {
+    if (!this.config.isMongoAuthEnabled()) {
+      return;
+    }
+    const config = this.config.getConfig();
+    const containers = this.config.getContainerNames();
+
+    for (let attempt = 0; attempt < 30; attempt++) {
+      const probe = await this.docker.execCombined(
+        containers.mongo,
+        `mongosh --quiet --port ${config.MONGODB_PORT} ` +
+          `-u "${config.MONGODB_USER}" -p "${config.MONGODB_PASS}" --authenticationDatabase admin ` +
+          `--eval 'print("AUTH_OK")'`,
+      );
+      if (probe.output.includes('AUTH_OK')) {
+        return;
+      }
+      if (probe.output.includes('Authentication failed')) {
+        break;
+      }
+      // A missing or dead container will never become reachable; retrying 30
+      // times only delays a failure that is already terminal.
+      if (probe.output.includes('No such container') || probe.output.includes('is restarting')) {
+        throw new Error(
+          `MongoDB container "${containers.mongo}" is not running (${probe.output.trim()}). ` +
+            `Inspect it with \`gitzone services logs mongo 100\`.`,
+        );
+      }
+      // mongod not accepting connections yet
+      await plugins.smartdelay.delayFor(1000);
+    }
+
+    logger.log('note', '  No usable root user in existing data, bootstrapping...');
+    const createScript =
+      `db.getSiblingDB("admin").createUser({user: "${config.MONGODB_USER}", ` +
+      `pwd: "${config.MONGODB_PASS}", roles: [{role: "root", db: "admin"}]}); ` +
+      'print("USER_CREATED");';
+    const create = await this.docker.execCombined(
+      containers.mongo,
+      `mongosh --quiet --port ${config.MONGODB_PORT} --eval '${createScript}'`,
+    );
+    if (create.output.includes('USER_CREATED')) {
+      logger.log('ok', '  Root user created ✓');
+      return;
+    }
+
+    throw new Error(
+      `MongoDB rejected the configured credentials for "${containers.mongo}" and the root user could not be ` +
+        'bootstrapped (the localhost exception only applies while no users exist). Either correct ' +
+        'MONGODB_USER/MONGODB_PASS in .nogit/env.json to match the existing data, or discard the data with ' +
+        '`gitzone services clean`.',
+    );
+  }
+
+  /**
+   * Initiate the single-node replica set once mongod is reachable
+   */
+  private async ensureMongoReplicaSetInitiated(): Promise<boolean> {
+    const config = this.config.getConfig();
+    const containers = this.config.getContainerNames();
+    const evalScript =
+      'try { rs.status(); print("RS_OK"); } catch (e) { ' +
+      'if (e.codeName === "NotYetInitialized") { ' +
+      `rs.initiate({_id: "rs0", members: [{_id: 0, host: "localhost:${config.MONGODB_PORT}"}]}); ` +
+      'print("RS_INITIATED"); } else { print("RS_ERROR: " + e.message); } }';
+    const authArgs = this.config.isMongoAuthEnabled()
+      ? `-u "${config.MONGODB_USER}" -p "${config.MONGODB_PASS}" --authenticationDatabase admin `
+      : '';
+    const command =
+      `mongosh --quiet --port ${config.MONGODB_PORT} ` +
+      authArgs +
+      `--eval '${evalScript}'`;
+
+    for (let attempt = 0; attempt < 30; attempt++) {
+      const output = await this.docker.exec(containers.mongo, command);
+      if (output.includes('RS_INITIATED')) {
+        logger.log('ok', '  Replica set initiated ✓');
+        return true;
+      }
+      if (output.includes('RS_OK')) {
+        return true;
+      }
+      await plugins.smartdelay.delayFor(1000);
+    }
+    logger.log('error', '  Replica set not ready after 30s — transactions unavailable');
+    return false;
   }
   
   /**
@@ -293,9 +543,9 @@ export class ServiceManager {
     const containers = this.config.getContainerNames();
     const directories = this.config.getDataDirectories();
     
-    // Ensure data directory exists
-    await plugins.smartfs.directory(directories.minio).recursive().create();
-    
+    // Ensure data directory exists and is marked as tool-owned
+    const minioLabels = await this.prepareDataDirectory('minio', directories.minio);
+
     const status = await this.docker.getStatus(containers.minio);
     
     switch (status) {
@@ -326,10 +576,11 @@ export class ServiceManager {
               MINIO_ROOT_USER: config.S3_ACCESSKEY,
               MINIO_ROOT_PASSWORD: config.S3_SECRETKEY
             },
+            labels: minioLabels,
             restart: 'unless-stopped',
             command: 'server /data --console-address ":9001"'
           });
-          
+
           if (success) {
             logger.log('ok', '  Recreated with new ports ✓');
             
@@ -378,10 +629,11 @@ export class ServiceManager {
             MINIO_ROOT_USER: config.S3_ACCESSKEY,
             MINIO_ROOT_PASSWORD: config.S3_SECRETKEY
           },
+          labels: minioLabels,
           restart: 'unless-stopped',
           command: 'server /data --console-address ":9001"'
         });
-        
+
         if (success) {
           logger.log('ok', '  Created and started ✓');
           
@@ -423,8 +675,8 @@ export class ServiceManager {
     const containers = this.config.getContainerNames();
     const directories = this.config.getDataDirectories();
 
-    // Ensure data directory exists
-    await plugins.smartfs.directory(directories.elasticsearch).recursive().create();
+    // Ensure data directory exists and is marked as tool-owned
+    const esLabels = await this.prepareDataDirectory('elasticsearch', directories.elasticsearch);
 
     const status = await this.docker.getStatus(containers.elasticsearch);
 
@@ -455,6 +707,7 @@ export class ServiceManager {
               'ELASTIC_PASSWORD': config.ELASTICSEARCH_PASS,
               'ES_JAVA_OPTS': '-Xms512m -Xmx512m'
             },
+            labels: esLabels,
             restart: 'unless-stopped'
           });
 
@@ -491,6 +744,7 @@ export class ServiceManager {
             'ELASTIC_PASSWORD': config.ELASTICSEARCH_PASS,
             'ES_JAVA_OPTS': '-Xms512m -Xmx512m'
           },
+          labels: esLabels,
           restart: 'unless-stopped'
         });
 
@@ -569,18 +823,88 @@ export class ServiceManager {
     }
   }
 
+  /**
+   * Collect service status as structured data.
+   *
+   * This is the machine-readable surface behind `gitzone services status
+   * --json`; consumers such as test suites can read a connection string from it
+   * without scraping human output or re-deriving it from `.nogit/env.json`.
+   */
+  public async collectStatus(): Promise<IServicesStatus> {
+    const config = this.config.getConfig();
+    const containers = this.config.getContainerNames();
+    const directories = this.config.getDataDirectories();
+
+    const describe = async (
+      service: TServiceName,
+      containerName: string,
+      dataPath: string,
+      port: string,
+      connectionString: string,
+    ): Promise<IServiceStatus> => {
+      const status = await this.docker.getStatus(containerName);
+      const dataExists = await plugins.smartfs.directory(dataPath).exists();
+      return {
+        service,
+        enabled: this.isServiceEnabled(service),
+        container: containerName,
+        status,
+        port,
+        connectionString,
+        dataDirectory: dataPath,
+        dataSizeBytes: dataExists ? await helpers.getDirectorySize(dataPath) : 0,
+        portAvailable:
+          status === 'not_exists' ? await helpers.isPortAvailable(parseInt(port)) : null,
+      };
+    };
+
+    const mongo = await describe(
+      'mongodb',
+      containers.mongo,
+      directories.mongo,
+      config.MONGODB_PORT,
+      this.config.getMongoConnectionString(),
+    );
+    mongo.authEnabled = this.config.isMongoAuthEnabled();
+
+    const minio = await describe(
+      'minio',
+      containers.minio,
+      directories.minio,
+      config.S3_PORT,
+      `http://${config.S3_HOST}:${config.S3_PORT}`,
+    );
+    const elasticsearch = await describe(
+      'elasticsearch',
+      containers.elasticsearch,
+      directories.elasticsearch,
+      config.ELASTICSEARCH_PORT,
+      config.ELASTICSEARCH_URL,
+    );
+
+    return {
+      project: {
+        name: config.PROJECT_NAME,
+        path: process.cwd(),
+        enabledServices: this.enabledServices || [],
+      },
+      services: { mongodb: mongo, minio, elasticsearch },
+      totalDataBytes: mongo.dataSizeBytes + minio.dataSizeBytes + elasticsearch.dataSizeBytes,
+    };
+  }
+
   /**
    * Show service status
    */
   public async showStatus(): Promise<void> {
     helpers.printHeader('Service Status');
-    
+
     const config = this.config.getConfig();
     const containers = this.config.getContainerNames();
-    
+
     logger.log('info', `Project: ${config.PROJECT_NAME}`);
     console.log();
-    
+
     // MongoDB status
     const mongoStatus = await this.docker.getStatus(containers.mongo);
     switch (mongoStatus) {
@@ -588,8 +912,11 @@ export class ServiceManager {
         logger.log('ok', '📦 MongoDB: 🟢 Running');
         logger.log('info', `   ├─ Container: ${containers.mongo}`);
         logger.log('info', `   ├─ Port: ${config.MONGODB_PORT}`);
+        if (!this.config.isMongoAuthEnabled()) {
+          logger.log('note', '   ├─ ⚠️  Auth: DISABLED (loopback only)');
+        }
         logger.log('info', `   ├─ Connection: ${this.config.getMongoConnectionString()}`);
-        
+
         // Show Compass connection string
         const networkIp = await helpers.getLocalNetworkIp();
         const compassString = `mongodb://${config.MONGODB_USER}:${config.MONGODB_PASS}@${networkIp}:${config.MONGODB_PORT}/${config.MONGODB_NAME}?authSource=admin`;
@@ -682,6 +1009,44 @@ export class ServiceManager {
         }
         break;
     }
+
+    await this.showDiskUsage();
+  }
+
+  /**
+   * Report on-disk size of this project's service data.
+   *
+   * Reporting comes before any deletion: knowing what a project holds is what
+   * makes reclaiming it a decision rather than a guess.
+   */
+  public async showDiskUsage(): Promise<void> {
+    const directories = this.config.getDataDirectories();
+    const entries: Array<{ label: string; path: string }> = [
+      { label: 'MongoDB', path: directories.mongo },
+      { label: 'S3/MinIO', path: directories.minio },
+      { label: 'Elasticsearch', path: directories.elasticsearch },
+    ];
+
+    console.log();
+    logger.log('note', 'Data on disk:');
+    let total = 0;
+    for (const entry of entries) {
+      if (!(await plugins.smartfs.directory(entry.path).exists())) {
+        continue;
+      }
+      const size = await helpers.getDirectorySize(entry.path);
+      total += size;
+      logger.log('info', `  ${entry.label}: ${helpers.formatBytes(size)}  (${entry.path})`);
+    }
+    if (total === 0) {
+      logger.log('info', '  No service data directories present');
+      return;
+    }
+    logger.log('info', `  Total: ${helpers.formatBytes(total)}`);
+    logger.log(
+      'note',
+      '  Remove containers but keep data: `gitzone services remove`; remove data too: `gitzone services clean`',
+    );
   }
 
   /**
@@ -857,23 +1222,21 @@ export class ServiceManager {
    */
   public async cleanData(): Promise<void> {
     const directories = this.config.getDataDirectories();
-    let cleaned = false;
-
-    if (await plugins.smartfs.directory(directories.mongo).exists()) {
-      await plugins.smartfs.directory(directories.mongo).recursive().delete();
-      logger.log('ok', '  MongoDB data removed ✓');
-      cleaned = true;
-    }
-
-    if (await plugins.smartfs.directory(directories.minio).exists()) {
-      await plugins.smartfs.directory(directories.minio).recursive().delete();
-      logger.log('ok', '  S3/MinIO data removed ✓');
-      cleaned = true;
-    }
+    const targets: Array<{ label: string; service: TServiceName; path: string }> = [
+      { label: 'MongoDB', service: 'mongodb', path: directories.mongo },
+      { label: 'S3/MinIO', service: 'minio', path: directories.minio },
+      { label: 'Elasticsearch', service: 'elasticsearch', path: directories.elasticsearch },
+    ];
 
-    if (await plugins.smartfs.directory(directories.elasticsearch).exists()) {
-      await plugins.smartfs.directory(directories.elasticsearch).recursive().delete();
-      logger.log('ok', '  Elasticsearch data removed ✓');
+    let cleaned = false;
+    for (const target of targets) {
+      if (!(await plugins.smartfs.directory(target.path).exists())) {
+        continue;
+      }
+      // Escalates to a privileged one-off container when needed; throws rather
+      // than leaving a partially deleted (and for MongoDB, corrupt) directory.
+      await this.docker.removeDataDirectory(target.path, serviceImages[target.service]);
+      logger.log('ok', `  ${target.label} data removed ✓`);
       cleaned = true;
     }