@git.zone/cli 2.23.0 → 2.25.0

package/ts/mod_services/index.ts

@@ -2,9 +2,19 @@ import * as plugins from "./mod.plugins.js";
 import * as helpers from "./helpers.js";
 import { ServiceManager } from "./classes.servicemanager.js";
 import { GlobalRegistry } from "./classes.globalregistry.js";
+import { getServiceDataDirectory } from "./classes.servicedatamarker.js";
+import {
+  ServicePruner,
+  defaultStaleDays,
+  type IServicePrunePlan,
+} from "./classes.servicepruner.js";
 import { logger } from "../gitzone.logging.js";
 import type { ICliMode } from "../helpers.climode.js";
-import { getCliMode, printJson } from "../helpers.climode.js";
+import {
+  getCliMode,
+  printJson,
+  runWithSuppressedOutput,
+} from "../helpers.climode.js";
 import {
   getCliConfigValueFromData,
   readSmartconfigFile,
@@ -24,7 +34,7 @@ export const run = async (argvArg: any) => {
 
   // Handle global commands first
   if (isGlobal) {
-    await handleGlobalCommand(command);
+    await handleGlobalCommand(command, argvArg, mode);
     return;
   }
 
@@ -53,6 +63,14 @@ export const run = async (argvArg: any) => {
       await handleDisableServices(argvArg._.slice(2), mode);
       break;
 
+    case "prune":
+      await handlePrune(argvArg, mode);
+      break;
+
+    case "auth":
+      await handleAuth(argvArg._[2], argvArg._[3], mode);
+      break;
+
     case "start":
     case "stop":
     case "restart":
@@ -63,11 +81,13 @@ export const run = async (argvArg: any) => {
     case "clean":
     case "reconfigure": {
       const serviceManager = new ServiceManager();
-      await serviceManager.init();
+      // Initialisation is chatty. In JSON mode that chatter would land on stdout
+      // ahead of the payload and make the output unparseable.
+      await withJsonSafeOutput(mode, () => serviceManager.init());
 
       switch (command) {
         case "start":
-          await handleStart(serviceManager, service);
+          await handleStart(serviceManager, service, mode);
           break;
 
         case "stop":
@@ -79,7 +99,12 @@ export const run = async (argvArg: any) => {
           break;
 
         case "status":
+          if (mode.json) {
+            printJson(await serviceManager.collectStatus());
+            break;
+          }
           await serviceManager.showStatus();
+          await printStaleHint();
           break;
 
         case "compass":
@@ -93,11 +118,11 @@ export const run = async (argvArg: any) => {
         }
 
         case "remove":
-          await handleRemove(serviceManager);
+          await handleRemove(serviceManager, mode);
           break;
 
         case "clean":
-          await handleClean(serviceManager);
+          await handleClean(serviceManager, mode);
           break;
 
         case "reconfigure":
@@ -112,6 +137,21 @@ export const run = async (argvArg: any) => {
   }
 };
 
+/**
+ * Run work that logs for humans, keeping stdout clean when the caller asked for
+ * JSON. Without this, `--json` output is preceded by log lines and cannot be
+ * parsed by a consumer such as a test suite.
+ */
+async function withJsonSafeOutput<T>(
+  mode: ICliMode,
+  work: () => Promise<T>,
+): Promise<T> {
+  if (!mode.json) {
+    return work();
+  }
+  return runWithSuppressedOutput(work);
+}
+
 const allowedServices = ["mongodb", "minio", "elasticsearch"];
 
 const normalizeServiceName = (service: string): string => {
@@ -193,7 +233,11 @@ async function handleShowConfig(mode: ICliMode) {
   logger.log("info", `  Container: ${env.PROJECT_NAME}-mongodb`);
   logger.log(
     "info",
-    `  Data: ${plugins.path.join(process.cwd(), ".nogit", "mongodata")}`,
+    `  Auth: ${env.MONGODB_AUTH_ENABLED === false ? "DISABLED (loopback only)" : "enabled"}`,
+  );
+  logger.log(
+    "info",
+    `  Data: ${getServiceDataDirectory(process.cwd(), "mongodb")}`,
   );
   logger.log("info", `  Connection: ${env.MONGODB_URL}`);
   console.log();
@@ -206,7 +250,7 @@ async function handleShowConfig(mode: ICliMode) {
   logger.log("info", `  Container: ${env.PROJECT_NAME}-minio`);
   logger.log(
     "info",
-    `  Data: ${plugins.path.join(process.cwd(), ".nogit", "miniodata")}`,
+    `  Data: ${getServiceDataDirectory(process.cwd(), "minio")}`,
   );
   logger.log("info", `  Endpoint: ${env.S3_ENDPOINT}`);
   console.log();
@@ -220,7 +264,7 @@ async function handleShowConfig(mode: ICliMode) {
   logger.log("info", `  Container: ${env.PROJECT_NAME}-elasticsearch`);
   logger.log(
     "info",
-    `  Data: ${plugins.path.join(process.cwd(), ".nogit", "esdata")}`,
+    `  Data: ${getServiceDataDirectory(process.cwd(), "elasticsearch")}`,
   );
   logger.log("info", `  Connection: ${env.ELASTICSEARCH_URL}`);
 }
@@ -304,34 +348,93 @@ function validateRequestedServices(services: string[]): void {
   }
 }
 
-async function handleStart(serviceManager: ServiceManager, service: string) {
-  helpers.printHeader("Starting Services");
-
-  switch (service) {
-    case "mongo":
-    case "mongodb":
-      await serviceManager.startMongoDB();
-      break;
+async function handleStart(
+  serviceManager: ServiceManager,
+  service: string,
+  mode: ICliMode,
+) {
+  const startService = async (): Promise<boolean> => {
+    switch (service) {
+      case "mongo":
+      case "mongodb":
+        await serviceManager.startMongoDB();
+        break;
+
+      case "minio":
+      case "s3":
+        await serviceManager.startMinIO();
+        break;
+
+      case "elasticsearch":
+      case "es":
+        await serviceManager.startElasticsearch();
+        break;
+
+      case "all":
+      case "":
+        await serviceManager.startAll();
+        break;
+
+      default:
+        return false;
+    }
 
-    case "minio":
-    case "s3":
-      await serviceManager.startMinIO();
-      break;
+    // Register on every start path so the global registry never drifts from
+    // reality; prune relies on this claim to identify tool-owned containers.
+    await serviceManager.registerWithGlobalRegistry();
+    return true;
+  };
 
-    case "elasticsearch":
-    case "es":
-      await serviceManager.startElasticsearch();
-      break;
+  if (mode.json) {
+    const started = await runWithSuppressedOutput(startService);
+    if (!started) {
+      throw new Error(
+        `Unknown service: ${service}. Use: mongo, s3, elasticsearch, or all`,
+      );
+    }
+    printJson(await serviceManager.collectStatus());
+    return;
+  }
 
-    case "all":
-    case "":
-      await serviceManager.startAll();
-      break;
+  helpers.printHeader("Starting Services");
+  if (!(await startService())) {
+    logger.log("error", `Unknown service: ${service}`);
+    logger.log("note", "Use: mongo, s3, elasticsearch, or all");
+    return;
+  }
+  await printStaleHint();
+}
 
-    default:
-      logger.log("error", `Unknown service: ${service}`);
-      logger.log("note", "Use: mongo, s3, elasticsearch, or all");
-      break;
+/**
+ * Non-blocking hint that reclaimable service data exists elsewhere on the
+ * machine. Detection is automatic; deletion never is.
+ */
+async function printStaleHint() {
+  try {
+    const summary = await GlobalRegistry.getInstance().getStaleSummary(
+      defaultStaleDays,
+    );
+    if (summary.orphaned === 0 && summary.stale === 0) {
+      return;
+    }
+    const parts: string[] = [];
+    if (summary.stale > 0) {
+      parts.push(`${summary.stale} inactive`);
+    }
+    if (summary.orphaned > 0) {
+      parts.push(`${summary.orphaned} with a deleted directory`);
+    }
+    console.log();
+    logger.log(
+      "note",
+      `💡 ${parts.join(", ")} gitzone services project(s) registered on this machine.`,
+    );
+    logger.log(
+      "note",
+      "   Review what can be reclaimed with `gitzone services prune` (read-only).",
+    );
+  } catch {
+    // A hint must never break the command that produced it.
   }
 }
 
@@ -404,43 +507,272 @@ async function handleRestart(serviceManager: ServiceManager, service: string) {
   }
 }
 
-async function handleRemove(serviceManager: ServiceManager) {
+async function handleRemove(serviceManager: ServiceManager, mode: ICliMode) {
   helpers.printHeader("Removing Containers");
   logger.log("note", "⚠️  This will remove containers but preserve data");
 
-  const shouldContinue =
-    await plugins.smartinteract.SmartInteract.getCliConfirmation(
-      "Continue?",
-      false,
-    );
-
-  if (shouldContinue) {
-    await serviceManager.removeContainers();
-  } else {
-    logger.log("note", "Cancelled");
+  if (!mode.yes) {
+    if (!mode.interactive) {
+      throw new Error(
+        "`services remove` needs confirmation. Re-run with --yes to remove containers non-interactively.",
+      );
+    }
+    const shouldContinue =
+      await plugins.smartinteract.SmartInteract.getCliConfirmation(
+        "Continue?",
+        false,
+      );
+    if (!shouldContinue) {
+      logger.log("note", "Cancelled");
+      return;
+    }
   }
+
+  await serviceManager.removeContainers();
 }
 
-async function handleClean(serviceManager: ServiceManager) {
+async function handleClean(serviceManager: ServiceManager, mode: ICliMode) {
   helpers.printHeader("Clean All");
   logger.log("error", "⚠️  WARNING: This will remove all containers and data!");
   logger.log("error", "This action cannot be undone!");
+  await serviceManager.showDiskUsage();
+  console.log();
+
+  if (!mode.yes) {
+    if (!mode.interactive) {
+      throw new Error(
+        "`services clean` destroys data and needs explicit intent. Re-run with --yes to confirm non-interactively.",
+      );
+    }
+    const smartinteraction = new plugins.smartinteract.SmartInteract();
+    const confirmAnswer = await smartinteraction.askQuestion({
+      name: "confirm",
+      type: "input",
+      message: 'Type "yes" to confirm:',
+      default: "no",
+    });
+    if (confirmAnswer.value !== "yes") {
+      logger.log("note", "Cancelled");
+      return;
+    }
+  }
+
+  await serviceManager.removeContainers();
+  console.log();
+  await serviceManager.cleanData();
+  logger.log("ok", "All cleaned ✓");
+}
 
-  const smartinteraction = new plugins.smartinteract.SmartInteract();
-  const confirmAnswer = await smartinteraction.askQuestion({
-    name: "confirm",
-    type: "input",
-    message: 'Type "yes" to confirm:',
-    default: "no",
+/**
+ * Toggle MongoDB authentication for this project.
+ *
+ * Opt-in only, and never silent: disabling auth also restricts publishing to
+ * loopback and is refused outright for a non-local MONGODB_HOST.
+ */
+async function handleAuth(
+  rawService: string | undefined,
+  rawValue: string | undefined,
+  mode: ICliMode,
+) {
+  const service = normalizeServiceName((rawService || "").trim());
+  if (service !== "mongodb") {
+    throw new Error(
+      "Only `mongodb` supports an auth toggle. Usage: gitzone services auth mongodb <on|off>",
+    );
+  }
+
+  const value = (rawValue || "").trim().toLowerCase();
+  if (value !== "on" && value !== "off") {
+    throw new Error("Usage: gitzone services auth mongodb <on|off>");
+  }
+
+  const serviceManager = new ServiceManager();
+  const configuration = await withJsonSafeOutput(mode, async () => {
+    await serviceManager.init();
+    const resolvedConfiguration = serviceManager.getConfiguration();
+    await resolvedConfiguration.setMongoAuthEnabled(value === "on");
+    return resolvedConfiguration;
   });
 
-  if (confirmAnswer.value === "yes") {
-    await serviceManager.removeContainers();
-    console.log();
-    await serviceManager.cleanData();
-    logger.log("ok", "All cleaned ✓");
+  if (mode.json) {
+    printJson({
+      ok: true,
+      action: "auth",
+      service: "mongodb",
+      authEnabled: value === "on",
+      connectionString: configuration.getMongoConnectionString(),
+    });
+    return;
+  }
+
+  if (value === "off") {
+    logger.log("error", "⚠️  MongoDB authentication is now DISABLED for this project.");
+    logger.log(
+      "note",
+      "   The database will be published on 127.0.0.1 only. Do not use this for anything but local development.",
+    );
   } else {
+    logger.log("ok", "MongoDB authentication is now enabled for this project.");
+  }
+  logger.log("info", `Connection: ${configuration.getMongoConnectionString()}`);
+  logger.log(
+    "note",
+    "Run `gitzone services start mongo` to recreate the container in the new mode.",
+  );
+}
+
+/**
+ * Report — and only with --apply, reclaim — resources left behind by
+ * `gitzone services` across every registered project on this machine.
+ */
+async function handlePrune(argvArg: any, mode: ICliMode) {
+  const staleDaysRaw = argvArg["stale-days"] ?? argvArg.staleDays;
+  const staleDays =
+    staleDaysRaw === undefined ? defaultStaleDays : parseInt(String(staleDaysRaw));
+  if (!Number.isFinite(staleDays) || staleDays < 1) {
+    throw new Error("--stale-days must be a positive number of days");
+  }
+
+  const apply = Boolean(argvArg.apply);
+  const pruner = new ServicePruner({ staleDays });
+  const plan = await pruner.createPlan();
+
+  const nothingToDo =
+    plan.containersToRemove.length === 0 &&
+    plan.dataDirsToRemove.length === 0 &&
+    plan.registryEntriesToRemove.length === 0;
+
+  // Deleting data always needs intent beyond --apply. Enforced before the
+  // output branches so JSON mode cannot bypass the gate the human path applies.
+  const confirmDataRemoval = async (): Promise<boolean> => {
+    if (!apply || nothingToDo || plan.dataDirsToRemove.length === 0 || mode.yes) {
+      return true;
+    }
+    if (!mode.interactive) {
+      throw new Error(
+        "`services prune --apply` would delete data directories. Re-run with --yes to confirm non-interactively.",
+      );
+    }
+    const smartinteraction = new plugins.smartinteract.SmartInteract();
+    const confirmAnswer = await smartinteraction.askQuestion({
+      name: "confirm",
+      type: "input",
+      message: `Type "yes" to permanently delete ${plan.dataDirsToRemove.length} data directory/ies:`,
+      default: "no",
+    });
+    return confirmAnswer.value === "yes";
+  };
+
+  if (mode.json) {
+    let applied = false;
+    if (apply && !nothingToDo) {
+      // Non-interactive by definition, so this throws unless --yes was passed.
+      await confirmDataRemoval();
+      await runWithSuppressedOutput(() => pruner.applyPlan(plan));
+      applied = true;
+    }
+    printJson({ applied, ...plan });
+    return;
+  }
+
+  printPrunePlan(plan, apply);
+
+  if (!apply || nothingToDo) {
+    return;
+  }
+
+  if (!(await confirmDataRemoval())) {
     logger.log("note", "Cancelled");
+    return;
+  }
+
+  await pruner.applyPlan(plan);
+  logger.log("ok", "Prune applied ✓");
+}
+
+function printPrunePlan(plan: IServicePrunePlan, applyArg: boolean) {
+  helpers.printHeader(
+    applyArg ? "Prune Services (apply)" : "Prune Services (dry run)",
+  );
+
+  logger.log("info", `Inactivity threshold: ${plan.staleDays} days`);
+  if (!plan.dockerAvailable) {
+    logger.log(
+      "error",
+      "Docker is not reachable — container and data reclamation is disabled.",
+    );
+  }
+  console.log();
+
+  if (plan.projects.length === 0) {
+    logger.log("note", "No gitzone services projects known on this machine");
+    return;
+  }
+
+  for (const project of plan.projects) {
+    const stateIcon =
+      project.state === "live"
+        ? "🟢"
+        : project.state === "stale"
+          ? "🟡"
+          : project.state === "orphaned"
+            ? "⚫"
+            : "❓";
+    logger.log("ok", `${stateIcon} ${project.projectName} [${project.state}]`);
+    logger.log("info", `   Path: ${project.projectPath}`);
+    logger.log("info", `   ${project.stateReason}`);
+    for (const container of project.containers) {
+      const marker = container.reclaimable ? "REMOVE" : "keep";
+      logger.log(
+        "info",
+        `   ${marker === "REMOVE" ? "🗑 " : "   "}container ${container.name} (${container.state}) — ${marker}: ${container.reason}`,
+      );
+    }
+    for (const dataDir of project.dataDirectories) {
+      if (!dataDir.exists) {
+        continue;
+      }
+      const marker = dataDir.reclaimable ? "REMOVE" : "keep";
+      logger.log(
+        "info",
+        `   ${marker === "REMOVE" ? "🗑 " : "   "}${dataDir.service} data ${helpers.formatBytes(dataDir.sizeBytes)} — ${marker}: ${dataDir.reason}`,
+      );
+    }
+    console.log();
+  }
+
+  for (const skipped of plan.skipped) {
+    logger.log("note", `skipped ${skipped.target}: ${skipped.reason}`);
+  }
+
+  logger.log("note", "Summary:");
+  logger.log("info", `  Projects known: ${plan.totals.projects}`);
+  logger.log(
+    "info",
+    `  Service data on disk: ${helpers.formatBytes(plan.totals.totalDataBytes)}`,
+  );
+  logger.log(
+    "info",
+    `  Reclaimable now: ${helpers.formatBytes(plan.totals.reclaimableDataBytes)} across ${plan.dataDirsToRemove.length} directory/ies`,
+  );
+  if (plan.totals.blockedByRunningBytes > 0) {
+    logger.log(
+      "info",
+      `  Held by running containers: ${helpers.formatBytes(plan.totals.blockedByRunningBytes)} — stop them first (\`gitzone services stop\` in the project, or \`gitzone services stop -g\`)`,
+    );
+  }
+  logger.log("info", `  Containers to remove: ${plan.containersToRemove.length}`);
+  logger.log(
+    "info",
+    `  Stale registry entries to remove: ${plan.registryEntriesToRemove.length}`,
+  );
+
+  if (!applyArg) {
+    console.log();
+    logger.log(
+      "note",
+      "Dry run only. Re-run with --apply to reclaim the items marked REMOVE.",
+    );
   }
 }
 
@@ -475,11 +807,25 @@ export function showHelp(mode?: ICliMode) {
         { name: "start [service]", description: "Start services" },
         { name: "stop [service]", description: "Stop services" },
         { name: "status", description: "Show service status" },
+        {
+          name: "auth mongodb <on|off>",
+          description:
+            "Toggle MongoDB authentication; off publishes on loopback only",
+        },
+        {
+          name: "prune",
+          description:
+            "Report reclaimable containers, data and registry entries (dry run; --apply to reclaim)",
+        },
       ],
       examples: [
         "gitzone services config --json",
+        "gitzone services status --json",
         "gitzone services set mongodb,minio",
         "gitzone services enable elasticsearch",
+        "gitzone services auth mongodb off",
+        "gitzone services prune",
+        "gitzone services prune --apply --yes",
       ],
     });
     return;
@@ -524,11 +870,32 @@ export function showHelp(mode?: ICliMode) {
     "  logs [service]    Show logs (mongo|s3|elasticsearch|all) [lines]",
   );
   logger.log("info", "  reconfigure       Reassign ports and restart services");
-  logger.log("info", "  remove            Remove all containers");
+  logger.log(
+    "info",
+    "  auth mongodb <on|off>  Toggle MongoDB auth (off = loopback only) ⚠️",
+  );
+  logger.log(
+    "info",
+    "  prune             Report reclaimable data/containers machine-wide",
+  );
+  logger.log("info", "  remove            Remove all containers (keeps data)");
   logger.log("info", "  clean             Remove all containers and data ⚠️");
   logger.log("info", "  help              Show this help message");
   console.log();
 
+  logger.log("note", "Cleanup levels (least to most destructive):");
+  logger.log("info", "  stop     Containers stay, data stays — fully resumable");
+  logger.log("info", "  remove   Containers removed, data kept — resumable");
+  logger.log(
+    "info",
+    "  clean    Containers and this project's data removed — irreversible, needs typed confirmation or --yes",
+  );
+  logger.log(
+    "info",
+    "  prune    Machine-wide reclamation of inactive/orphaned projects — dry run unless --apply",
+  );
+  console.log();
+
   logger.log("note", "Available Services:");
   logger.log("info", "  • MongoDB (mongo) - Document database");
   logger.log("info", "  • MinIO (s3) - S3-compatible object storage");
@@ -604,6 +971,10 @@ export function showHelp(mode?: ICliMode) {
     "  stop -g           Stop all containers across all projects",
   );
   logger.log("info", "  cleanup -g        Remove stale registry entries");
+  logger.log(
+    "info",
+    "  prune             Report/reclaim inactive project data (--stale-days N, --apply)",
+  );
   console.log();
 
   logger.log("note", "Global Examples:");
@@ -623,7 +994,11 @@ export function showHelp(mode?: ICliMode) {
 
 // ==================== Global Command Handlers ====================
 
-async function handleGlobalCommand(command: string) {
+async function handleGlobalCommand(
+  command: string,
+  argvArg: any,
+  mode: ICliMode,
+) {
   const globalRegistry = GlobalRegistry.getInstance();
 
   switch (command) {
@@ -639,6 +1014,10 @@ async function handleGlobalCommand(command: string) {
       await handleGlobalStop(globalRegistry);
       break;
 
+    case "prune":
+      await handlePrune(argvArg, mode);
+      break;
+
     case "cleanup":
       await handleGlobalCleanup(globalRegistry);
       break;