@git.zone/cli 2.23.0 → 2.25.0

package/readme.md

@@ -446,20 +446,138 @@ gitzone services set mongodb,minio
 # Check status
 gitzone services status
 
+# Machine-readable status, including connection strings and data sizes
+gitzone services status --json
+
 # Print MongoDB Compass connection string
 gitzone services compass
 
 # Show logs
 gitzone services logs mongo 50
+```
+
+Service config is stored in `.nogit/env.json`. Data is stored below `.nogit/`, so it stays out of Git.
+
+### Consuming a service programmatically
 
-# Stop containers but keep data
-gitzone services stop
+`gitzone services status --json` emits only JSON on stdout, so a test suite or
+script can read a live connection string without parsing human output:
 
-# Remove containers and data
-gitzone services clean
+```bash
+gitzone services status --json | jq -r '.services.mongodb.connectionString'
 ```
 
-Service config is stored in `.nogit/env.json`. Data is stored below `.nogit/`, so it stays out of Git.
+### Cleanup levels
+
+Cleanup is tiered, from fully resumable to irreversible:
+
+| Command | Containers | Data | Notes |
+| --- | --- | --- | --- |
+| `gitzone services stop` | kept (stopped) | kept | fully resumable |
+| `gitzone services remove` | removed | kept | resumable; `--yes` to skip the prompt |
+| `gitzone services clean` | removed | **removed** | irreversible; needs a typed `yes` or `--yes` |
+| `gitzone services prune` | see below | see below | machine-wide; dry run unless `--apply` |
+
+`clean` and `prune` remove data written by the container user (mongod runs as
+uid 999, MinIO as root) by escalating to a short-lived privileged container
+scoped to that one directory. They either remove a directory completely or fail
+— a partial delete would leave a corrupt database behind.
+
+### Reclaiming space across projects
+
+Service data is per project and survives container removal, so it accumulates.
+`gitzone services prune` reports what every registered project holds and what
+can be reclaimed. It is read-only unless `--apply` is passed:
+
+```bash
+# Report only: what exists, what is reclaimable, and why
+gitzone services prune
+
+# Change the inactivity threshold (default 30 days)
+gitzone services prune --stale-days 90
+
+# Actually reclaim, non-interactively
+gitzone services prune --apply --yes
+```
+
+A project is only a candidate when there is positive evidence it is finished
+with: its directory is gone, or it has been inactive past the threshold with no
+container running. Anything ambiguous — an unlabeled container claimed by more
+than one project, an unreachable Docker daemon, a directory still mounted by a
+running container — is reported and skipped rather than reclaimed. Containers
+are identified by the `git.zone.tool=gitzone-services` label or by an
+unambiguous registry claim, never by image or name pattern, so pruning cannot
+touch containers created by anything else.
+
+### MongoDB authentication
+
+MongoDB runs as a single-node replica set with authentication enabled, so
+multi-document transactions work. Authentication can be disabled per project for
+runtimes whose `node:crypto` cannot complete a SCRAM handshake (notably Deno):
+
+```bash
+gitzone services auth mongodb off
+gitzone services start mongo
+```
+
+This is opt-in and never implicit. With authentication disabled the database is
+published on `127.0.0.1` only, and the combination of no authentication with a
+non-local `MONGODB_HOST` is refused outright. Transactions continue to work, and
+`gitzone services status` reports the mode. Re-enabling authentication over data
+created without it bootstraps the configured root user through MongoDB's
+localhost exception.
+
+The setting is recorded in `.smartconfig.json`, so it is committed and a fresh
+clone or CI run reproduces it without any manual step:
+
+```json
+{
+  "@git.zone/cli": {
+    "services": ["mongodb"],
+    "serviceOptions": {
+      "mongodb": { "auth": false }
+    }
+  }
+}
+```
+
+`serviceOptions` is a **sibling** of `services`, never a richer `services`
+value. `services` must stay a flat array of canonical lowercase strings because
+`@git.zone/tsdeploy` derives a workload's `requiredCapabilities` from it and
+rejects any other shape.
+
+A committed declaration takes precedence over `.nogit/env.json`, so a stale
+local file cannot silently diverge from what the repository declares. When
+nothing is declared, an existing local value is preserved. When neither exists,
+authentication is enabled. Because a declaration affects everyone who clones the
+repository, `services status` states where the setting came from:
+
+```text
+⚠️  Auth: DISABLED (loopback only), declared in .smartconfig.json (applies to every checkout)
+```
+
+An older CLI that predates `serviceOptions` ignores the key and starts MongoDB
+with authentication enabled — it degrades to the secure default, never the
+insecure one.
+
+### Checking which version is running
+
+`gitzone --version` prints the bare version on the first line, followed by the
+path it resolved from. A stale copy in a legacy pnpm global root can otherwise
+make it look like an older version is installed when it is not:
+
+```bash
+gitzone --version
+# 2.25.0
+# resolved from: /home/you/.local/share/pnpm/store/v11/links/@git.zone/cli/2.25.0/…
+
+gitzone --version --json
+# {"version":"2.25.0","resolvedFrom":"…"}
+```
+
+`gitzone tools update` also removes inert copies of managed packages left behind
+in legacy global roots, provided the active root already supplies them and no
+command shim still points there.
 
 ## Templates
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/cli',
-  version: '2.23.0',
+  version: '2.25.0',
   description: 'A comprehensive CLI tool for enhancing and managing local development workflows with gitzone utilities, focusing on project setup, version control, code formatting, and template management.'
 }

package/ts/gitzone.cli.ts

@@ -4,6 +4,7 @@ import {
   getProcessUserArgv,
   getRawCliMode,
   parseCliArgv,
+  printJson,
 } from "./helpers.climode.js";
 import { commitinfo } from "./00_commitinfo_data.js";
 
@@ -130,7 +131,16 @@ export let run = async () => {
   }
   const argvArg = parseCliArgv(getProcessUserArgv());
   if (argvArg.v || argvArg.version) {
+    if (rawCliMode.output === "json") {
+      printJson({ version: packageVersion, resolvedFrom: paths.packageDir });
+      return;
+    }
+    // The bare version stays on its own line so `gitzone --version` remains
+    // parseable by scripts. The resolved path is added underneath because a
+    // stale copy in a legacy pnpm global root can otherwise make people
+    // conclude they are running a version they are not.
     console.log(packageVersion);
+    console.log(`resolved from: ${paths.packageDir}`);
     return;
   }
   await runParsedCommand(argvArg);

package/ts/mod_services/classes.dockercontainer.ts

@@ -10,25 +10,57 @@ export interface IDockerRunOptions {
   ports?: { [key: string]: string };
   volumes?: { [key: string]: string };
   environment?: { [key: string]: string };
+  labels?: { [key: string]: string };
   restart?: string;
   command?: string;
 }
 
+/** Container facts needed to decide, safely, whether a container may be removed. */
+export interface IContainerInspectInfo {
+  id: string;
+  name: string;
+  state: string;
+  running: boolean;
+  labels: { [key: string]: string };
+  /** Resolved host-side sources of every bind mount. */
+  mountSources: string[];
+}
+
+/** Single-quote a value for safe interpolation into a bash command. */
+export const shellQuote = (valueArg: string): string => `'${valueArg.replace(/'/g, `'"'"'`)}'`;
+
 export class DockerContainer {
   private smartshell: plugins.smartshell.Smartshell;
-  
+  /**
+   * Wall-clock bound for docker queries and in-container commands.
+   *
+   * smartshell only arms a timeout when one is passed, so without this a wedged
+   * `docker exec` never settles and retry loops that look bounded ("30
+   * attempts") hang forever. Mirrors the `timeout Ns docker …` approach used by
+   * @git.zone/tsdocker.
+   */
+  private queryTimeoutSeconds = 60;
+  /** Longer bound for privileged cleanup, which may delete a large tree. */
+  private cleanupTimeoutSeconds = 600;
+
   constructor() {
     this.smartshell = new plugins.smartshell.Smartshell({
       executor: 'bash',
     });
   }
-  
+
+  /** `docker` prefixed with a hard wall-clock bound. */
+  private bounded(seconds: number): string {
+    return `timeout ${seconds}s docker`;
+  }
+
   /**
    * Check if Docker is installed and available
    */
   public async checkDocker(): Promise<boolean> {
     try {
-      const result = await this.smartshell.exec('docker --version');
+      // Silent: this must not print to stdout, which would corrupt --json output.
+      const result = await this.smartshell.execSilent('docker --version');
       return result.exitCode === 0;
     } catch (error) {
       return false;
@@ -120,17 +152,25 @@ export class DockerContainer {
     // Add volumes
     if (options.volumes) {
       for (const [hostPath, containerPath] of Object.entries(options.volumes)) {
-        command += ` -v "${hostPath}:${containerPath}"`;
+        command += ` -v ${shellQuote(`${hostPath}:${containerPath}`)}`;
       }
     }
-    
-    // Add environment variables
+
+    // Add environment variables. Values come from .nogit/env.json, which is
+    // user-editable, so they must not be interpolated unquoted.
     if (options.environment) {
       for (const [key, value] of Object.entries(options.environment)) {
-        command += ` -e ${key}="${value}"`;
+        command += ` -e ${shellQuote(`${key}=${value}`)}`;
       }
     }
-    
+
+    // Add labels (used to identify tool-owned containers during prune)
+    if (options.labels) {
+      for (const [key, value] of Object.entries(options.labels)) {
+        command += ` --label ${shellQuote(`${key}=${value}`)}`;
+      }
+    }
+
     // Add restart policy
     if (options.restart) {
       command += ` --restart ${options.restart}`;
@@ -162,17 +202,24 @@ export class DockerContainer {
     command: string;
     volumes?: { [key: string]: string };
     user?: string;
+    /** Shell used inside the container. `sh` is available in every service image. */
+    shell?: string;
   }): Promise<boolean> {
-    let command = 'docker run --rm';
+    let command = `${this.bounded(this.cleanupTimeoutSeconds)} run --rm`;
     if (options.user) {
-      command += ` --user ${options.user}`;
+      command += ` --user ${shellQuote(options.user)}`;
     }
     if (options.volumes) {
       for (const [hostPath, containerPath] of Object.entries(options.volumes)) {
-        command += ` -v "${hostPath}:${containerPath}"`;
+        // Quoted: this path reaches a root `rm -rf`, so a project directory
+        // containing `$(...)`, a backtick or a quote must not reach the shell
+        // unescaped. The path allowlist constrains shape, not metacharacters.
+        command += ` -v ${shellQuote(`${hostPath}:${containerPath}`)}`;
       }
     }
-    command += ` ${options.image} bash -c '${options.command}'`;
+    // The image entrypoint must be bypassed: service images start their daemon.
+    command += ` --entrypoint ${shellQuote(options.shell || 'bash')} ${shellQuote(options.image)}`;
+    command += ` -c ${shellQuote(options.command)}`;
     try {
       const result = await this.smartshell.exec(command);
       return result.exitCode === 0;
@@ -183,12 +230,88 @@ export class DockerContainer {
     }
   }
 
+  /**
+   * True when an image is already present locally.
+   */
+  public async imageExists(imageArg: string): Promise<boolean> {
+    try {
+      const result = await this.smartshell.execSilent(
+        `${this.bounded(this.queryTimeoutSeconds)} image inspect ${shellQuote(imageArg)}`,
+      );
+      return result.exitCode === 0;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Remove a service data directory, escalating to a root one-off container
+   * when the invoking user cannot delete the contents.
+   *
+   * Service containers write as their own uid (mongod as 999, MinIO as root)
+   * with restrictive modes, so a plain recursive delete only removes part of the
+   * tree. For MongoDB that left a half-deleted, corrupt WiredTiger dataset that
+   * crash-looped on the next start — so a partial delete is worse than none.
+   * This either fully removes the directory or throws.
+   *
+   * The one-off container mounts only the target directory, so `rm -rf` inside
+   * it cannot reach anything else on the host.
+   */
+  public async removeDataDirectory(hostPathArg: string, imageArg: string): Promise<void> {
+    const hostPath = plugins.path.resolve(hostPathArg);
+    if (!(await plugins.smartfs.directory(hostPath).exists())) {
+      return;
+    }
+
+    // Fast path: the current user may already own everything.
+    try {
+      await plugins.smartfs.directory(hostPath).recursive().delete();
+    } catch (error) {
+      // fall through to privileged removal
+    }
+    if (!(await plugins.smartfs.directory(hostPath).exists())) {
+      return;
+    }
+
+    if (!(await this.imageExists(imageArg))) {
+      throw new Error(
+        `Cannot remove ${hostPath}: its contents belong to the container user and image ` +
+          `${imageArg} is not available locally to perform a privileged cleanup. ` +
+          `Pull ${imageArg} and retry, or remove the directory manually as root.`,
+      );
+    }
+
+    // Empty the mounted directory from inside a root container, then remove the
+    // now-empty directory from the host.
+    const emptied = await this.runOneOff({
+      image: imageArg,
+      shell: 'sh',
+      command: 'rm -rf /gitzone-target/..?* /gitzone-target/.[!.]* /gitzone-target/*',
+      volumes: { [hostPath]: '/gitzone-target' },
+      user: '0',
+    });
+    if (!emptied) {
+      throw new Error(`Privileged cleanup of ${hostPath} failed`);
+    }
+
+    try {
+      await plugins.smartfs.directory(hostPath).recursive().delete();
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new Error(`Could not remove ${hostPath} after privileged cleanup: ${errorMessage}`);
+    }
+
+    if (await plugins.smartfs.directory(hostPath).exists()) {
+      throw new Error(`Refusing to report success: ${hostPath} still exists`);
+    }
+  }
+
   /**
    * Execute a command in a running container
    */
   public async exec(containerName: string, command: string): Promise<string> {
     try {
-      const result = await this.smartshell.exec(`docker exec ${containerName} ${command}`);
+      const result = await this.smartshell.exec(`${this.bounded(this.queryTimeoutSeconds)} exec ${containerName} ${command}`);
       if (result.exitCode === 0) {
         return result.stdout;
       }
@@ -198,6 +321,28 @@ export class DockerContainer {
     }
   }
   
+  /**
+   * Execute a command in a running container, returning stdout and stderr
+   * together along with the exit code.
+   *
+   * `exec` discards output on a non-zero exit and drops stderr entirely, which
+   * hides diagnostics that a caller may need to branch on.
+   */
+  public async execCombined(
+    containerName: string,
+    command: string,
+  ): Promise<{ exitCode: number; output: string }> {
+    try {
+      const result = await this.smartshell.execSilent(
+        `${this.bounded(this.queryTimeoutSeconds)} exec ${containerName} ${command} 2>&1`,
+      );
+      return { exitCode: result.exitCode, output: result.stdout || '' };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return { exitCode: -1, output: errorMessage };
+    }
+  }
+
   /**
    * Get container logs
    */
@@ -289,4 +434,90 @@ export class DockerContainer {
       return null;
     }
   }
+
+  /**
+   * Run a `docker ps` query and return matching container ids.
+   *
+   * Throws when Docker itself fails, so callers can fail closed instead of
+   * mistaking an unreachable daemon for "no containers exist".
+   */
+  public async listIds(filterArgs: string[], includeStopped: boolean = true): Promise<string[]> {
+    const filters = filterArgs.map((filter) => `--filter ${shellQuote(filter)}`).join(' ');
+    const allFlag = includeStopped ? '-a' : '';
+    const result = await this.smartshell.execSilent(
+      `${this.bounded(this.queryTimeoutSeconds)} ps ${allFlag} ${filters} --format '{{.ID}}'`,
+    );
+    if (result.exitCode !== 0) {
+      throw new Error(result.stderr || result.stdout || 'docker ps failed');
+    }
+    if (!result.stdout.trim()) {
+      return [];
+    }
+    return result.stdout
+      .trim()
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean);
+  }
+
+  /**
+   * Inspect many containers at once and normalise the parts prune relies on.
+   * Throws on Docker failure so ambiguity never reads as absence.
+   */
+  public async inspectMany(idsArg: string[]): Promise<IContainerInspectInfo[]> {
+    if (idsArg.length === 0) {
+      return [];
+    }
+    const result = await this.smartshell.execSilent(
+      `${this.bounded(this.queryTimeoutSeconds)} inspect ${idsArg.map((id) => shellQuote(id)).join(' ')}`,
+    );
+    if (result.exitCode !== 0) {
+      throw new Error(result.stderr || result.stdout || 'docker inspect failed');
+    }
+    let parsed: any;
+    try {
+      parsed = JSON.parse(result.stdout);
+    } catch (error) {
+      throw new Error('docker inspect returned unparseable output');
+    }
+    if (!Array.isArray(parsed)) {
+      throw new Error('docker inspect returned unexpected output');
+    }
+    return parsed.map((container: any) => {
+      const labels = (container?.Config?.Labels || {}) as { [key: string]: string };
+      const mountSources: string[] = [];
+      for (const mount of container?.Mounts || []) {
+        if (mount?.Source) {
+          mountSources.push(plugins.path.resolve(mount.Source));
+        }
+      }
+      return {
+        id: String(container?.Id || ''),
+        name: String(container?.Name || '').replace(/^\//, ''),
+        state: String(container?.State?.Status || 'unknown'),
+        running: container?.State?.Running === true,
+        labels,
+        mountSources,
+      };
+    });
+  }
+
+  /**
+   * Resolved host paths bind-mounted by every *currently running* container on
+   * the daemon, regardless of which tool created it.
+   *
+   * This is the primitive that makes data reclamation safe: a directory that is
+   * mounted by anything running is never a deletion candidate.
+   */
+  public async listRunningMountSources(): Promise<string[]> {
+    const ids = await this.listIds([], false);
+    const containers = await this.inspectMany(ids);
+    const sources = new Set<string>();
+    for (const container of containers) {
+      for (const source of container.mountSources) {
+        sources.add(source);
+      }
+    }
+    return [...sources];
+  }
 }

package/ts/mod_services/classes.globalregistry.ts

@@ -170,6 +170,33 @@ export class GlobalRegistry {
     return { stopped, failed };
   }
 
+  /**
+   * Cheap staleness summary for a non-blocking hint after ordinary commands.
+   *
+   * Deliberately filesystem-only: no Docker calls and no directory sizing, so
+   * it stays fast enough to run after every `start` or `status`.
+   */
+  public async getStaleSummary(
+    staleDaysArg: number,
+  ): Promise<{ orphaned: number; stale: number }> {
+    const projects = await this.getAllProjects();
+    const thresholdMs = staleDaysArg * 24 * 60 * 60 * 1000;
+    let orphaned = 0;
+    let stale = 0;
+
+    for (const [projectPath, project] of Object.entries(projects)) {
+      if (!(await plugins.smartfs.directory(projectPath).exists())) {
+        orphaned++;
+        continue;
+      }
+      if (Date.now() - project.lastActive > thresholdMs) {
+        stale++;
+      }
+    }
+
+    return { orphaned, stale };
+  }
+
   /**
    * Remove stale registry entries (projects that no longer exist on disk)
    */