@git.zone/cli 2.23.0 → 2.24.0

package/ts/mod_services/classes.servicepruner.ts

@@ -0,0 +1,532 @@
+import * as plugins from './mod.plugins.js';
+import * as helpers from './helpers.js';
+import { DockerContainer, type IContainerInspectInfo } from './classes.dockercontainer.js';
+import { GlobalRegistry, type IRegisteredProject } from './classes.globalregistry.js';
+import {
+  getServiceDataDirectory,
+  isSafeServiceDataPath,
+  isServiceOwnedByLabels,
+  readServiceDataMarker,
+  serviceImages,
+  serviceNames,
+  serviceToolLabel,
+  type TServiceName,
+} from './classes.servicedatamarker.js';
+import { logger } from '../gitzone.logging.js';
+
+/** Default inactivity threshold before a project is even considered stale. */
+export const defaultStaleDays = 30;
+
+/**
+ * How a project was classified.
+ *
+ * - `live`     — recent activity; never a reclamation candidate.
+ * - `stale`    — project still on disk but inactive past the threshold.
+ * - `orphaned` — project directory no longer exists.
+ * - `unknown`  — insufficient evidence to classify; never reclaimed.
+ */
+export type TServiceProjectState = 'live' | 'stale' | 'orphaned' | 'unknown';
+
+/** Why a candidate was left alone. */
+export interface IServiceSkipReason {
+  target: string;
+  reason: string;
+}
+
+export interface IServiceDataDirReport {
+  service: TServiceName;
+  path: string;
+  exists: boolean;
+  sizeBytes: number;
+  reclaimable: boolean;
+  reason: string;
+}
+
+export interface IServiceContainerReport {
+  id: string;
+  name: string;
+  state: string;
+  running: boolean;
+  reclaimable: boolean;
+  reason: string;
+}
+
+export interface IServiceProjectReport {
+  projectPath: string;
+  projectName: string;
+  state: TServiceProjectState;
+  stateReason: string;
+  lastActive: number | null;
+  inactiveDays: number | null;
+  projectDirExists: boolean;
+  registered: boolean;
+  markerPresent: boolean;
+  containers: IServiceContainerReport[];
+  dataDirectories: IServiceDataDirReport[];
+  totalDataBytes: number;
+  reclaimableDataBytes: number;
+}
+
+export interface IServicePrunePlan {
+  staleDays: number;
+  dockerAvailable: boolean;
+  projects: IServiceProjectReport[];
+  registryEntriesToRemove: string[];
+  containersToRemove: Array<{ id: string; name: string; projectPath: string }>;
+  dataDirsToRemove: Array<{ projectPath: string; service: TServiceName; path: string; sizeBytes: number }>;
+  skipped: IServiceSkipReason[];
+  totals: {
+    projects: number;
+    totalDataBytes: number;
+    reclaimableDataBytes: number;
+    /** Bytes that would be reclaimable if the holding containers were stopped first. */
+    blockedByRunningBytes: number;
+  };
+}
+
+export interface IServicePrunerOptions {
+  staleDays?: number;
+}
+
+interface IProjectCandidate {
+  projectPath: string;
+  projectName: string;
+  registryEntry?: IRegisteredProject;
+  containers: IContainerInspectInfo[];
+}
+
+const dayInMs = 24 * 60 * 60 * 1000;
+
+/**
+ * Plans and applies reclamation of resources created by `gitzone services`.
+ *
+ * Design mirrors `@git.zone/tsdocker`'s `TsDockerPruner`: build an explicit
+ * plan, print it, and only mutate on an explicit apply that re-verifies every
+ * single item. Nothing is ever matched by image or by bare name pattern, and
+ * every ambiguity resolves to "skip".
+ */
+export class ServicePruner {
+  private docker: DockerContainer;
+  private globalRegistry: GlobalRegistry;
+  private staleDays: number;
+
+  constructor(optionsArg: IServicePrunerOptions = {}) {
+    this.docker = new DockerContainer();
+    this.globalRegistry = GlobalRegistry.getInstance();
+    this.staleDays = optionsArg.staleDays ?? defaultStaleDays;
+  }
+
+  /**
+   * Build a reclamation plan. Read-only: touches nothing.
+   */
+  public async createPlan(): Promise<IServicePrunePlan> {
+    const skipped: IServiceSkipReason[] = [];
+    const registryProjects = await this.globalRegistry.getAllProjects();
+
+    // Collect tool-owned containers. A Docker failure must not be mistaken for
+    // "no containers exist", so we record availability and fail closed below.
+    let dockerAvailable = true;
+    let labeledContainers: IContainerInspectInfo[] = [];
+    let runningMountSources: string[] = [];
+    try {
+      const ids = await this.docker.listIds([`label=git.zone.tool=${serviceToolLabel}`]);
+      labeledContainers = await this.docker.inspectMany(ids);
+      runningMountSources = await this.docker.listRunningMountSources();
+    } catch (error) {
+      dockerAvailable = false;
+      const message = error instanceof Error ? error.message : String(error);
+      skipped.push({
+        target: 'docker',
+        reason: `docker unavailable (${message}); container and data reclamation disabled`,
+      });
+    }
+
+    // Containers recorded in the registry but not labeled (created by older
+    // versions). Their names are only trusted when exactly one registry entry
+    // claims them.
+    const nameClaims = new Map<string, string[]>();
+    for (const [projectPath, project] of Object.entries(registryProjects)) {
+      for (const containerName of Object.values(project.containers)) {
+        if (!containerName) {
+          continue;
+        }
+        const claims = nameClaims.get(containerName) || [];
+        claims.push(projectPath);
+        nameClaims.set(containerName, claims);
+      }
+    }
+
+    let legacyContainers: IContainerInspectInfo[] = [];
+    if (dockerAvailable && nameClaims.size > 0) {
+      try {
+        // One `docker ps -a` for all claimed names rather than one per name:
+        // each shell-out is a spawned child process, and this runs on every
+        // prune. Identity is established by the exact-name match below, so the
+        // listing only needs to be a superset.
+        const labeledIds = new Set(labeledContainers.map((container) => container.id));
+        const allIds = await this.docker.listIds([]);
+        const candidateIds = allIds.filter((id) => !labeledIds.has(id));
+        const inspected = await this.docker.inspectMany(candidateIds);
+        legacyContainers = inspected.filter((container) => nameClaims.has(container.name));
+      } catch (error) {
+        dockerAvailable = false;
+        const message = error instanceof Error ? error.message : String(error);
+        skipped.push({
+          target: 'docker',
+          reason: `docker unavailable (${message}); container and data reclamation disabled`,
+        });
+      }
+    }
+
+    // Group every known container and registry entry under a project path.
+    const candidates = new Map<string, IProjectCandidate>();
+    const ensureCandidate = (projectPathArg: string, projectNameArg: string): IProjectCandidate => {
+      const projectPath = plugins.path.resolve(projectPathArg);
+      const existing = candidates.get(projectPath);
+      if (existing) {
+        return existing;
+      }
+      const candidate: IProjectCandidate = {
+        projectPath,
+        projectName: projectNameArg,
+        containers: [],
+      };
+      candidates.set(projectPath, candidate);
+      return candidate;
+    };
+
+    for (const [projectPath, project] of Object.entries(registryProjects)) {
+      const candidate = ensureCandidate(projectPath, project.projectName);
+      candidate.registryEntry = project;
+    }
+
+    for (const container of labeledContainers) {
+      const projectPath = container.labels['git.zone.project-path'];
+      if (!projectPath) {
+        skipped.push({
+          target: container.name,
+          reason: 'labeled as tool-owned but carries no git.zone.project-path',
+        });
+        continue;
+      }
+      const candidate = ensureCandidate(projectPath, plugins.path.basename(projectPath));
+      candidate.containers.push(container);
+    }
+
+    // Projects whose container ownership cannot be resolved. Ambiguity must
+    // *tighten* the decision, never loosen it: if we cannot attribute a
+    // container, we also cannot claim that a project has no container running,
+    // so such projects are forced to `unknown` and nothing is reclaimed.
+    const ambiguousProjectPaths = new Set<string>();
+
+    for (const container of legacyContainers) {
+      const claims = nameClaims.get(container.name) || [];
+      if (claims.length !== 1) {
+        skipped.push({
+          target: container.name,
+          reason: `unlabeled container claimed by ${claims.length} registered projects; ownership ambiguous`,
+        });
+        for (const claim of claims) {
+          ambiguousProjectPaths.add(plugins.path.resolve(claim));
+          ensureCandidate(claim, plugins.path.basename(claim));
+        }
+        continue;
+      }
+      const projectPath = claims[0];
+      const candidate = ensureCandidate(projectPath, plugins.path.basename(projectPath));
+      candidate.containers.push(container);
+    }
+
+    // Classify and decide.
+    const projects: IServiceProjectReport[] = [];
+    const registryEntriesToRemove: string[] = [];
+    const containersToRemove: Array<{ id: string; name: string; projectPath: string }> = [];
+    const dataDirsToRemove: Array<{
+      projectPath: string;
+      service: TServiceName;
+      path: string;
+      sizeBytes: number;
+    }> = [];
+    let blockedByRunningBytes = 0;
+
+    for (const candidate of [...candidates.values()].sort((first, second) =>
+      first.projectPath.localeCompare(second.projectPath),
+    )) {
+      const projectDirExists = await plugins.smartfs.directory(candidate.projectPath).exists();
+      const marker = await readServiceDataMarker(candidate.projectPath);
+      const lastActive = candidate.registryEntry?.lastActive ?? null;
+      const inactiveDays =
+        lastActive === null ? null : Math.floor((Date.now() - lastActive) / dayInMs);
+
+      let state: TServiceProjectState;
+      let stateReason: string;
+      if (ambiguousProjectPaths.has(candidate.projectPath)) {
+        state = 'unknown';
+        stateReason =
+          'a container name for this project is claimed by more than one project; ownership ambiguous';
+      } else if (!projectDirExists) {
+        state = 'orphaned';
+        stateReason = 'project directory no longer exists';
+      } else if (lastActive === null) {
+        state = 'unknown';
+        stateReason = 'no lastActive timestamp recorded; cannot prove inactivity';
+      } else if ((inactiveDays as number) > this.staleDays) {
+        state = 'stale';
+        stateReason = `inactive for ${inactiveDays} days (threshold ${this.staleDays})`;
+      } else {
+        state = 'live';
+        stateReason = `active ${inactiveDays} day(s) ago`;
+      }
+
+      const anyContainerRunning = candidate.containers.some((container) => container.running);
+
+      // Containers
+      const containerReports: IServiceContainerReport[] = [];
+      for (const container of candidate.containers) {
+        let reclaimable = false;
+        let reason: string;
+        if (!dockerAvailable) {
+          reason = 'docker unavailable';
+        } else if (state === 'live') {
+          reason = 'project is live';
+        } else if (state === 'unknown') {
+          reason = 'project state unknown';
+        } else if (container.running) {
+          reason = 'container is running; stop it first';
+        } else {
+          reclaimable = true;
+          reason = `project ${state}, container stopped`;
+        }
+        containerReports.push({
+          id: container.id,
+          name: container.name,
+          state: container.state,
+          running: container.running,
+          reclaimable,
+          reason,
+        });
+        if (reclaimable) {
+          containersToRemove.push({
+            id: container.id,
+            name: container.name,
+            projectPath: candidate.projectPath,
+          });
+        }
+      }
+
+      // Data directories
+      const ownershipProven = !!marker || !!candidate.registryEntry;
+      const dataReports: IServiceDataDirReport[] = [];
+      let totalDataBytes = 0;
+      let reclaimableDataBytes = 0;
+
+      for (const service of serviceNames) {
+        const dataPath = getServiceDataDirectory(candidate.projectPath, service);
+        const exists = await plugins.smartfs.directory(dataPath).exists();
+        const sizeBytes = exists ? await helpers.getDirectorySize(dataPath) : 0;
+        totalDataBytes += sizeBytes;
+
+        let reclaimable = false;
+        let reason: string;
+        const mountConflict = runningMountSources.find((source) =>
+          helpers.pathsOverlap(dataPath, source),
+        );
+
+        if (!exists) {
+          reason = 'no data directory';
+        } else if (!dockerAvailable) {
+          reason = 'docker unavailable; cannot prove no container uses this data';
+        } else if (!isSafeServiceDataPath(candidate.projectPath, dataPath)) {
+          reason = 'path outside the allowed service data shape';
+        } else if (!ownershipProven) {
+          reason = 'no marker and no registry entry; ownership unproven';
+        } else if (state === 'live') {
+          reason = 'project is live';
+        } else if (state === 'unknown') {
+          reason = 'project state unknown';
+        } else if (state === 'orphaned') {
+          // Data lives inside the project directory, which is gone.
+          reason = 'project directory absent';
+        } else if (mountConflict) {
+          reason = `mounted by a running container (${mountConflict})`;
+          blockedByRunningBytes += sizeBytes;
+        } else if (anyContainerRunning) {
+          reason = 'a container for this project is still running';
+          blockedByRunningBytes += sizeBytes;
+        } else {
+          reclaimable = true;
+          reason = `project stale, no container running, ownership proven by ${marker ? 'marker' : 'registry'}`;
+        }
+
+        dataReports.push({ service, path: dataPath, exists, sizeBytes, reclaimable, reason });
+        if (reclaimable) {
+          reclaimableDataBytes += sizeBytes;
+          dataDirsToRemove.push({
+            projectPath: candidate.projectPath,
+            service,
+            path: dataPath,
+            sizeBytes,
+          });
+        }
+      }
+
+      // Registry entry: safe to drop only once no container remains. For
+      // containers created before labels existed, the registry claim is the only
+      // thing that can ever identify them again — dropping it while one still
+      // exists would make it invisible to prune, `stop -g` and `cleanup -g`,
+      // leaving it running forever under `restart: unless-stopped`.
+      if (state === 'orphaned' && candidate.registryEntry) {
+        if (candidate.containers.length === 0) {
+          registryEntriesToRemove.push(candidate.projectPath);
+        } else {
+          skipped.push({
+            target: candidate.projectPath,
+            reason: `project directory is gone but ${candidate.containers.length} container(s) remain; keeping the registry entry so they stay identifiable`,
+          });
+        }
+      }
+
+      projects.push({
+        projectPath: candidate.projectPath,
+        projectName: candidate.registryEntry?.projectName || candidate.projectName,
+        state,
+        stateReason,
+        lastActive,
+        inactiveDays,
+        projectDirExists,
+        registered: !!candidate.registryEntry,
+        markerPresent: !!marker,
+        containers: containerReports,
+        dataDirectories: dataReports,
+        totalDataBytes,
+        reclaimableDataBytes,
+      });
+    }
+
+    return {
+      staleDays: this.staleDays,
+      dockerAvailable,
+      projects,
+      registryEntriesToRemove,
+      containersToRemove,
+      dataDirsToRemove,
+      skipped,
+      totals: {
+        projects: projects.length,
+        totalDataBytes: projects.reduce((sum, project) => sum + project.totalDataBytes, 0),
+        reclaimableDataBytes: projects.reduce(
+          (sum, project) => sum + project.reclaimableDataBytes,
+          0,
+        ),
+        blockedByRunningBytes,
+      },
+    };
+  }
+
+  /**
+   * Apply a plan, re-verifying every item immediately before it is removed.
+   *
+   * Any drift between plan and current reality aborts with an error rather than
+   * removing something that may since have become live.
+   */
+  public async applyPlan(planArg: IServicePrunePlan): Promise<void> {
+    if (!planArg.dockerAvailable && (planArg.containersToRemove.length > 0 || planArg.dataDirsToRemove.length > 0)) {
+      throw new Error('Refusing to apply container or data removal without a reachable Docker daemon');
+    }
+
+    // Containers first, so their mounts stop protecting the data we then remove.
+    if (planArg.containersToRemove.length > 0) {
+      const current = await this.docker.inspectMany(
+        planArg.containersToRemove.map((container) => container.id),
+      );
+      for (const planned of planArg.containersToRemove) {
+        const container = current.find((candidate) => candidate.id === planned.id);
+        if (!container) {
+          throw new Error(`Refusing to remove vanished container: ${planned.name}`);
+        }
+        if (container.running) {
+          throw new Error(`Refusing to remove running container: ${container.name}`);
+        }
+        const labelOwned = isServiceOwnedByLabels(container.labels);
+        const registryOwned = await this.isClaimedByExactlyOneProject(container.name, planned.projectPath);
+        if (!labelOwned && !registryOwned) {
+          throw new Error(`Refusing to remove container with unproven ownership: ${container.name}`);
+        }
+        if (!(await this.docker.remove(container.name, false))) {
+          throw new Error(`Failed to remove container: ${container.name}`);
+        }
+        logger.log('ok', `Removed container ${container.name}`);
+      }
+    }
+
+    // Data directories. Cheap, local invariants are re-checked first so an
+    // invalid plan is rejected before any Docker call and before anything is
+    // deleted; only then is the live mount table consulted.
+    if (planArg.dataDirsToRemove.length > 0) {
+      const currentProjects = await this.globalRegistry.getAllProjects();
+      for (const planned of planArg.dataDirsToRemove) {
+        if (!isSafeServiceDataPath(planned.projectPath, planned.path)) {
+          throw new Error(`Refusing unsafe service data path: ${planned.path}`);
+        }
+        const marker = await readServiceDataMarker(planned.projectPath);
+        const registered = await this.globalRegistry.isRegistered(planned.projectPath);
+        if (!marker && !registered) {
+          throw new Error(`Refusing data path with unproven ownership: ${planned.path}`);
+        }
+        // Re-verify staleness: the project may have been started between
+        // planning and applying, which would make this live data.
+        const currentEntry = Object.entries(currentProjects).find(
+          ([projectPath]) => plugins.path.resolve(projectPath) === planned.projectPath,
+        )?.[1];
+        if (currentEntry) {
+          const inactiveDays = Math.floor((Date.now() - currentEntry.lastActive) / dayInMs);
+          if (inactiveDays <= this.staleDays) {
+            throw new Error(
+              `Refusing data path for a project that became active: ${planned.path} (${inactiveDays}d)`,
+            );
+          }
+        }
+      }
+
+      const runningMountSources = await this.docker.listRunningMountSources();
+      for (const planned of planArg.dataDirsToRemove) {
+        const conflict = runningMountSources.find((source) =>
+          helpers.pathsOverlap(planned.path, source),
+        );
+        if (conflict) {
+          throw new Error(`Refusing mounted data path: ${planned.path} is used by ${conflict}`);
+        }
+        if (!(await plugins.smartfs.directory(planned.path).exists())) {
+          continue;
+        }
+        // Escalates to a privileged one-off container when the contents belong to
+        // the container user; throws rather than deleting only part of the tree.
+        await this.docker.removeDataDirectory(planned.path, serviceImages[planned.service]);
+        logger.log('ok', `Removed data directory ${planned.path}`);
+      }
+    }
+
+    // Registry metadata last, so a failure above leaves the claim intact.
+    for (const projectPath of planArg.registryEntriesToRemove) {
+      if (await plugins.smartfs.directory(projectPath).exists()) {
+        throw new Error(`Refusing to unregister an existing project: ${projectPath}`);
+      }
+      await this.globalRegistry.unregisterProject(projectPath);
+      logger.log('ok', `Unregistered ${projectPath}`);
+    }
+  }
+
+  private async isClaimedByExactlyOneProject(
+    containerNameArg: string,
+    projectPathArg: string,
+  ): Promise<boolean> {
+    const projects = await this.globalRegistry.getAllProjects();
+    const claims: string[] = [];
+    for (const [projectPath, project] of Object.entries(projects)) {
+      if (Object.values(project.containers).includes(containerNameArg)) {
+        claims.push(plugins.path.resolve(projectPath));
+      }
+    }
+    return claims.length === 1 && claims[0] === plugins.path.resolve(projectPathArg);
+  }
+}

package/ts/mod_services/helpers.ts

@@ -90,6 +90,66 @@ export const formatBytes = (bytes: number): string => {
   return `${size.toFixed(2)} ${units[unitIndex]}`;
 };
 
+/**
+ * True when either path contains the other, or they are the same path.
+ *
+ * Used to decide whether a deletion candidate collides with a directory a
+ * running container has mounted. Containment in *either* direction counts: a
+ * parent mount protects its children, and a child mount protects its parent.
+ */
+export const pathsOverlap = (firstPathArg: string, secondPathArg: string): boolean => {
+  const firstPath = plugins.path.resolve(firstPathArg);
+  const secondPath = plugins.path.resolve(secondPathArg);
+  const contains = (containerPath: string, candidatePath: string): boolean => {
+    const relative = plugins.path.relative(containerPath, candidatePath);
+    if (relative === '') {
+      return true;
+    }
+    return !!relative && !relative.startsWith('..') && !plugins.path.isAbsolute(relative);
+  };
+  return contains(firstPath, secondPath) || contains(secondPath, firstPath);
+};
+
+/**
+ * Total size in bytes of a directory tree.
+ *
+ * Symlinks are counted by their own size and never followed, so a symlink
+ * inside a data directory can neither inflate the report nor walk out of it.
+ */
+export const getDirectorySize = async (
+  directoryPathArg: string,
+  maxDepthArg: number = 64,
+): Promise<number> => {
+  let total = 0;
+  const walk = async (currentPath: string, depth: number): Promise<void> => {
+    // Bind mounts inside a data directory are user-controlled and can form a
+    // cycle; a depth cap keeps this from recursing until it exhausts memory.
+    if (depth > maxDepthArg) {
+      return;
+    }
+    const entries = await plugins.fs
+      .readdir(currentPath, { withFileTypes: true })
+      .catch(() => []);
+    for (const entry of entries) {
+      const entryPath = plugins.path.join(currentPath, entry.name);
+      // isDirectory() here is lstat-based, so symlinks are counted by their own
+      // size and never followed.
+      if (entry.isDirectory()) {
+        await walk(entryPath, depth + 1);
+        continue;
+      }
+      try {
+        const stats = await plugins.fs.lstat(entryPath);
+        total += stats.size;
+      } catch {
+        // entry disappeared between readdir and lstat; ignore
+      }
+    }
+  };
+  await walk(plugins.path.resolve(directoryPathArg), 0);
+  return total;
+};
+
 /**
  * Get the local network IP address
  */