@git.zone/cli 2.25.2 → 3.0.1

package/ts/mod_docker/classes.dockerpruner.ts

@@ -0,0 +1,334 @@
+import * as plugins from './mod.plugins.js';
+import { logger } from '../gitzone.logging.js';
+
+/**
+ * Label that marks a Docker resource as created by git.zone tooling.
+ * Established by @git.zone/tsdocker and reused by `gitzone services`.
+ */
+export const toolLabelKey = 'git.zone.tool';
+
+/**
+ * Label by which a resource's creator grants permission to reclaim it.
+ * Consent is opt-in and per-resource; absence always means "do not touch".
+ */
+export const pruneConsentLabelKey = 'git.zone.safe-to-prune';
+
+/** Single-quote a value for safe interpolation into a bash command. */
+export const shellQuote = (valueArg: string): string => `'${valueArg.replace(/'/g, `'"'"'`)}'`;
+
+export interface IPrunableContainer {
+  id: string;
+  name: string;
+  state: string;
+  running: boolean;
+  tool: string;
+  reclaimable: boolean;
+  reason: string;
+}
+
+export interface IPrunableVolume {
+  name: string;
+  tool: string;
+  attachedTo: string[];
+  reclaimable: boolean;
+  reason: string;
+}
+
+export interface IDockerInventory {
+  totalContainers: number;
+  runningContainers: number;
+  totalImages: number;
+  totalVolumes: number;
+}
+
+export interface IDockerPrunePlan {
+  dockerAvailable: boolean;
+  containers: IPrunableContainer[];
+  volumes: IPrunableVolume[];
+  inventory: IDockerInventory | null;
+  skipped: Array<{ target: string; reason: string }>;
+  /** Volumes are only ever candidates when the caller opted in. */
+  includeVolumes: boolean;
+}
+
+const dockerTimeoutSeconds = 60;
+const dockerCommand = `timeout ${dockerTimeoutSeconds}s docker`;
+
+/**
+ * Reclaims Docker resources that git.zone tooling created, and nothing else.
+ *
+ * This class exists because `gitzone docker prune` previously ran
+ * `docker system prune -a -f --volumes` — machine-wide, forced, and including
+ * volumes. On a host that also runs unrelated workloads that is unrecoverable
+ * data loss, and the command name gave no hint of it.
+ *
+ * The replacement never enumerates "everything unused". It starts from an
+ * explicit allowlist — resources carrying `git.zone.tool` *and*
+ * `git.zone.safe-to-prune=true` — and removes only members of that set which
+ * are additionally proven idle. Anything unlabeled is invisible to it by
+ * construction, so no other tool's resources can be caught up in it.
+ */
+export class DockerPruner {
+  private smartshell = new plugins.smartshell.Smartshell({ executor: 'bash' });
+
+  private async run(commandArg: string): Promise<{ exitCode: number; stdout: string }> {
+    const result = await this.smartshell.execSilent(commandArg);
+    return { exitCode: result.exitCode, stdout: result.stdout || '' };
+  }
+
+  private async listLines(commandArg: string): Promise<string[]> {
+    const result = await this.run(commandArg);
+    if (result.exitCode !== 0) {
+      throw new Error(result.stdout || `docker command failed: ${commandArg}`);
+    }
+    if (!result.stdout.trim()) {
+      return [];
+    }
+    return result.stdout
+      .trim()
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean);
+  }
+
+  private async inspectMany(idsArg: string[]): Promise<any[]> {
+    if (idsArg.length === 0) {
+      return [];
+    }
+    const result = await this.run(
+      `${dockerCommand} inspect ${idsArg.map((id) => shellQuote(id)).join(' ')}`,
+    );
+    if (result.exitCode !== 0) {
+      throw new Error(result.stdout || 'docker inspect failed');
+    }
+    try {
+      const parsed = JSON.parse(result.stdout);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch {
+      throw new Error('docker inspect returned unparseable output');
+    }
+  }
+
+  /**
+   * True only when a resource's own labels grant permission to reclaim it.
+   * Both labels are required: `git.zone.tool` proves provenance,
+   * `git.zone.safe-to-prune=true` is the explicit consent.
+   */
+  private isToolOwned(labelsArg: { [key: string]: string } | null): boolean {
+    if (!labelsArg) {
+      return false;
+    }
+    return (
+      typeof labelsArg[toolLabelKey] === 'string' &&
+      !!labelsArg[toolLabelKey] &&
+      labelsArg[pruneConsentLabelKey] === 'true'
+    );
+  }
+
+  /**
+   * Build a plan. Read-only.
+   */
+  public async createPlan(optionsArg: { includeVolumes: boolean }): Promise<IDockerPrunePlan> {
+    const skipped: Array<{ target: string; reason: string }> = [];
+    const containers: IPrunableContainer[] = [];
+    const volumes: IPrunableVolume[] = [];
+    let inventory: IDockerInventory | null = null;
+
+    try {
+      // Containers: start from the label filter, never from "all containers".
+      const containerIds = await this.listLines(
+        `${dockerCommand} ps -a --filter ${shellQuote(`label=${pruneConsentLabelKey}=true`)} --format '{{.ID}}'`,
+      );
+      const inspectedContainers = await this.inspectMany(containerIds);
+
+      for (const container of inspectedContainers) {
+        const labels = (container?.Config?.Labels || {}) as { [key: string]: string };
+        const name = String(container?.Name || '').replace(/^\//, '');
+        const running = container?.State?.Running === true;
+        const state = String(container?.State?.Status || 'unknown');
+
+        if (!this.isToolOwned(labels)) {
+          // The filter matched the consent label but provenance is missing.
+          skipped.push({
+            target: name,
+            reason: `carries ${pruneConsentLabelKey} but no ${toolLabelKey}; provenance unproven`,
+          });
+          continue;
+        }
+
+        containers.push({
+          id: String(container?.Id || ''),
+          name,
+          state,
+          running,
+          tool: labels[toolLabelKey],
+          reclaimable: !running,
+          reason: running ? 'container is running' : 'tool-owned and not running',
+        });
+      }
+
+      // Volumes: only considered when explicitly requested.
+      if (optionsArg.includeVolumes) {
+        const volumeNames = await this.listLines(
+          `${dockerCommand} volume ls --filter ${shellQuote(`label=${pruneConsentLabelKey}=true`)} --format '{{.Name}}'`,
+        );
+
+        // Attachment must be checked against every container, not just running
+        // ones: a stopped container still owns its data.
+        const allContainerIds = await this.listLines(
+          `${dockerCommand} ps -a --format '{{.ID}}'`,
+        );
+        const allContainers = await this.inspectMany(allContainerIds);
+        const volumeAttachments = new Map<string, string[]>();
+        for (const container of allContainers) {
+          const containerName = String(container?.Name || '').replace(/^\//, '');
+          for (const mount of container?.Mounts || []) {
+            if (mount?.Type === 'volume' && mount?.Name) {
+              const attached = volumeAttachments.get(mount.Name) || [];
+              attached.push(containerName);
+              volumeAttachments.set(mount.Name, attached);
+            }
+          }
+        }
+
+        const inspectedVolumes =
+          volumeNames.length > 0
+            ? await this.inspectMany(volumeNames.map((name) => `${name}`))
+            : [];
+
+        for (const volume of inspectedVolumes) {
+          const labels = (volume?.Labels || {}) as { [key: string]: string };
+          const name = String(volume?.Name || '');
+          const attachedTo = volumeAttachments.get(name) || [];
+
+          if (!this.isToolOwned(labels)) {
+            skipped.push({
+              target: `volume ${name}`,
+              reason: `carries ${pruneConsentLabelKey} but no ${toolLabelKey}; provenance unproven`,
+            });
+            continue;
+          }
+
+          volumes.push({
+            name,
+            tool: labels[toolLabelKey],
+            attachedTo,
+            reclaimable: attachedTo.length === 0,
+            reason:
+              attachedTo.length > 0
+                ? `attached to ${attachedTo.join(', ')}`
+                : 'tool-owned and not attached to any container',
+          });
+        }
+      }
+
+      // Cheap machine-wide counts for context. Deliberately counts only — sizing
+      // via `docker system df` walks every layer and volume and can take minutes
+      // on a large host, which is too slow for a default report.
+      const allContainerIds = await this.listLines(`${dockerCommand} ps -a --format '{{.ID}}'`);
+      const runningIds = await this.listLines(`${dockerCommand} ps --format '{{.ID}}'`);
+      const imageIds = await this.listLines(`${dockerCommand} images -q`);
+      const volumeIds = await this.listLines(`${dockerCommand} volume ls -q`);
+      inventory = {
+        totalContainers: allContainerIds.length,
+        runningContainers: runningIds.length,
+        totalImages: new Set(imageIds).size,
+        totalVolumes: volumeIds.length,
+      };
+
+      return {
+        dockerAvailable: true,
+        containers,
+        volumes,
+        inventory,
+        skipped,
+        includeVolumes: optionsArg.includeVolumes,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        dockerAvailable: false,
+        containers: [],
+        volumes: [],
+        inventory: null,
+        skipped: [{ target: 'docker', reason: `docker unavailable (${message})` }],
+        includeVolumes: optionsArg.includeVolumes,
+      };
+    }
+  }
+
+  /**
+   * Apply a plan, re-verifying each resource immediately before removing it.
+   * Any drift between plan and reality aborts rather than removing something
+   * that has since become active.
+   */
+  public async applyPlan(planArg: IDockerPrunePlan): Promise<{ containers: string[]; volumes: string[] }> {
+    if (!planArg.dockerAvailable) {
+      throw new Error('Refusing to prune without a reachable Docker daemon');
+    }
+
+    const removedContainers: string[] = [];
+    const removedVolumes: string[] = [];
+
+    const plannedContainers = planArg.containers.filter((container) => container.reclaimable);
+    if (plannedContainers.length > 0) {
+      const current = await this.inspectMany(plannedContainers.map((container) => container.id));
+      for (const planned of plannedContainers) {
+        const container = current.find((candidate) => String(candidate?.Id || '') === planned.id);
+        if (!container) {
+          throw new Error(`Refusing to remove vanished container: ${planned.name}`);
+        }
+        const labels = (container?.Config?.Labels || {}) as { [key: string]: string };
+        if (!this.isToolOwned(labels)) {
+          throw new Error(`Refusing to remove container with unproven ownership: ${planned.name}`);
+        }
+        if (container?.State?.Running === true) {
+          throw new Error(`Refusing to remove running container: ${planned.name}`);
+        }
+        const result = await this.run(`${dockerCommand} rm ${shellQuote(planned.id)}`);
+        if (result.exitCode !== 0) {
+          throw new Error(`Failed to remove container ${planned.name}: ${result.stdout}`);
+        }
+        removedContainers.push(planned.name);
+        logger.log('ok', `Removed container ${planned.name}`);
+      }
+    }
+
+    const plannedVolumes = planArg.volumes.filter((volume) => volume.reclaimable);
+    if (plannedVolumes.length > 0) {
+      if (!planArg.includeVolumes) {
+        throw new Error('Refusing to remove volumes without an explicit --volumes request');
+      }
+      // Re-derive attachments from scratch; a container may have started since.
+      const allContainerIds = await this.listLines(`${dockerCommand} ps -a --format '{{.ID}}'`);
+      const allContainers = await this.inspectMany(allContainerIds);
+      const attachedNames = new Set<string>();
+      for (const container of allContainers) {
+        for (const mount of container?.Mounts || []) {
+          if (mount?.Type === 'volume' && mount?.Name) {
+            attachedNames.add(mount.Name);
+          }
+        }
+      }
+
+      for (const planned of plannedVolumes) {
+        if (attachedNames.has(planned.name)) {
+          throw new Error(`Refusing to remove attached volume: ${planned.name}`);
+        }
+        const inspected = await this.inspectMany([planned.name]);
+        const labels = (inspected[0]?.Labels || {}) as { [key: string]: string };
+        if (!this.isToolOwned(labels)) {
+          throw new Error(`Refusing to remove volume with unproven ownership: ${planned.name}`);
+        }
+        const result = await this.run(`${dockerCommand} volume rm ${shellQuote(planned.name)}`);
+        if (result.exitCode !== 0) {
+          throw new Error(`Failed to remove volume ${planned.name}: ${result.stdout}`);
+        }
+        removedVolumes.push(planned.name);
+        logger.log('ok', `Removed volume ${planned.name}`);
+      }
+    }
+
+    return { containers: removedContainers, volumes: removedVolumes };
+  }
+}

package/ts/mod_docker/index.ts

@@ -1,12 +1,237 @@
 import * as plugins from './mod.plugins.js';
+import { logger } from '../gitzone.logging.js';
+import type { ICliMode } from '../helpers.climode.js';
+import { getCliMode, printJson } from '../helpers.climode.js';
+import {
+  DockerPruner,
+  pruneConsentLabelKey,
+  toolLabelKey,
+  type IDockerPrunePlan,
+} from './classes.dockerpruner.js';
 
-export const run = async (argvArg) => {
-  const smartshellInstance = new plugins.smartshell.Smartshell({
-    executor: 'bash',
-  });
-  switch (argvArg._[1]) {
+export const run = async (argvArg: any) => {
+  const mode = await getCliMode(argvArg);
+  const command = argvArg._[1] || 'help';
+
+  switch (command) {
     case 'prune':
-      await smartshellInstance.exec(`docker system prune -a -f --volumes`);
+      await handlePrune(argvArg, mode);
+      break;
+
+    case 'help':
+      showHelp(mode);
+      break;
+
+    default:
+      logger.log('error', `Unknown docker command: ${command}`);
+      showHelp(mode);
       break;
   }
 };
+
+async function handlePrune(argvArg: any, mode: ICliMode) {
+  const apply = Boolean(argvArg.apply);
+  const includeVolumes = Boolean(argvArg.volumes);
+
+  const pruner = new DockerPruner();
+  const plan = await pruner.createPlan({ includeVolumes });
+
+  const reclaimableContainers = plan.containers.filter((container) => container.reclaimable);
+  const reclaimableVolumes = plan.volumes.filter((volume) => volume.reclaimable);
+  const nothingToDo = reclaimableContainers.length === 0 && reclaimableVolumes.length === 0;
+
+  // Removing a volume destroys persisted application data, so it always needs
+  // intent beyond --apply, in every output mode.
+  const confirmVolumeRemoval = async (): Promise<boolean> => {
+    if (!apply || reclaimableVolumes.length === 0 || mode.yes) {
+      return true;
+    }
+    if (!mode.interactive) {
+      throw new Error(
+        '`docker prune --volumes --apply` destroys persisted data. 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 ${reclaimableVolumes.length} volume(s) and their data:`,
+      default: 'no',
+    });
+    return confirmAnswer.value === 'yes';
+  };
+
+  if (mode.json) {
+    let applied: { containers: string[]; volumes: string[] } | null = null;
+    if (apply && !nothingToDo) {
+      await confirmVolumeRemoval();
+      applied = await pruner.applyPlan(plan);
+    }
+    printJson({ applied, ...plan });
+    return;
+  }
+
+  printPlan(plan, apply);
+
+  if (!apply || nothingToDo) {
+    return;
+  }
+
+  if (!(await confirmVolumeRemoval())) {
+    logger.log('note', 'Cancelled');
+    return;
+  }
+
+  const applied = await pruner.applyPlan(plan);
+  logger.log(
+    'ok',
+    `Reclaimed ${applied.containers.length} container(s) and ${applied.volumes.length} volume(s) ✓`,
+  );
+}
+
+function printPlan(plan: IDockerPrunePlan, applyArg: boolean) {
+  console.log();
+  logger.log('info', '═══════════════════════════════════════════════════════════════');
+  logger.log(
+    'info',
+    applyArg
+      ? '  Prune git.zone Docker resources (apply)'
+      : '  Prune git.zone Docker resources (dry run)',
+  );
+  logger.log('info', '═══════════════════════════════════════════════════════════════');
+  console.log();
+
+  if (!plan.dockerAvailable) {
+    logger.log('error', 'Docker is not reachable — nothing can be inspected or reclaimed.');
+    for (const skipped of plan.skipped) {
+      logger.log('note', `  ${skipped.target}: ${skipped.reason}`);
+    }
+    return;
+  }
+
+  logger.log(
+    'note',
+    `Scope: only resources labeled ${toolLabelKey}=<tool> and ${pruneConsentLabelKey}=true.`,
+  );
+  console.log();
+
+  logger.log('note', 'Containers:');
+  if (plan.containers.length === 0) {
+    logger.log('info', '  No git.zone-owned containers found');
+  }
+  for (const container of plan.containers) {
+    const marker = container.reclaimable ? '🗑  REMOVE' : '   keep  ';
+    logger.log(
+      'info',
+      `  ${marker} ${container.name} [${container.tool}] (${container.state}) — ${container.reason}`,
+    );
+  }
+
+  console.log();
+  logger.log('note', 'Volumes:');
+  if (!plan.includeVolumes) {
+    logger.log(
+      'info',
+      '  Not inspected. Volumes hold persisted data and are only considered with --volumes.',
+    );
+  } else if (plan.volumes.length === 0) {
+    logger.log('info', '  No git.zone-owned volumes found');
+  } else {
+    for (const volume of plan.volumes) {
+      const marker = volume.reclaimable ? '🗑  REMOVE' : '   keep  ';
+      logger.log('info', `  ${marker} ${volume.name} [${volume.tool}] — ${volume.reason}`);
+    }
+  }
+
+  for (const skipped of plan.skipped) {
+    logger.log('note', `skipped ${skipped.target}: ${skipped.reason}`);
+  }
+
+  if (plan.inventory) {
+    console.log();
+    logger.log('note', 'This host, for context — NOT reclaimed by this command:');
+    logger.log(
+      'info',
+      `  ${plan.inventory.totalContainers} containers (${plan.inventory.runningContainers} running), ${plan.inventory.totalImages} images, ${plan.inventory.totalVolumes} volumes`,
+    );
+    logger.log(
+      'info',
+      '  Reclaiming unlabeled resources is deliberately not offered. Run docker directly so the blast radius is explicit.',
+    );
+  }
+
+  if (!applyArg) {
+    console.log();
+    logger.log('note', 'Dry run only. Re-run with --apply to remove the items marked REMOVE.');
+  }
+}
+
+export function showHelp(mode?: ICliMode) {
+  if (mode?.json) {
+    printJson({
+      command: 'docker',
+      usage: 'gitzone docker <command> [options]',
+      commands: [
+        {
+          name: 'prune',
+          description:
+            'Report and reclaim stopped containers created by git.zone tooling. Dry run unless --apply.',
+          options: [
+            { name: '--apply', description: 'Actually remove the reported resources' },
+            {
+              name: '--volumes',
+              description: 'Also consider git.zone-owned volumes attached to no container',
+            },
+            { name: '--yes', description: 'Confirm volume deletion non-interactively' },
+          ],
+        },
+      ],
+      scope: `Only resources labeled ${toolLabelKey}=<tool> and ${pruneConsentLabelKey}=true are ever considered. Images are never removed.`,
+    });
+    return;
+  }
+
+  console.log();
+  logger.log('info', '═══════════════════════════════════════════════════════════════');
+  logger.log('info', '  GitZone Docker Resources');
+  logger.log('info', '═══════════════════════════════════════════════════════════════');
+  console.log();
+
+  logger.log('ok', 'Usage: gitzone docker <command> [options]');
+  console.log();
+
+  logger.log('note', 'Commands:');
+  logger.log(
+    'info',
+    '  prune             Report git.zone-owned Docker resources; reclaim with --apply',
+  );
+  console.log();
+
+  logger.log('note', 'Options:');
+  logger.log(
+    'info',
+    '  --apply           Remove the resources marked REMOVE (default is report only)',
+  );
+  logger.log('info', '  --volumes         Also consider git.zone-owned, unattached volumes ⚠️');
+  logger.log('info', '  --yes             Confirm volume deletion without a prompt');
+  console.log();
+
+  logger.log('note', 'Scope:');
+  logger.log('info', `  Only containers and volumes labeled ${toolLabelKey}=<tool> and`);
+  logger.log('info', `  ${pruneConsentLabelKey}=true are ever considered.`);
+  logger.log('info', '  Running containers and attached volumes are never removed.');
+  logger.log('info', '  Images are never removed.');
+  console.log();
+  logger.log(
+    'note',
+    '  This command deliberately cannot prune the whole machine. For that, run',
+  );
+  logger.log('note', '  docker directly so the blast radius is explicit and yours.');
+  console.log();
+
+  logger.log('note', 'Examples:');
+  logger.log('info', '  gitzone docker prune                      # report only');
+  logger.log('info', '  gitzone docker prune --apply              # remove stopped tool containers');
+  logger.log('info', '  gitzone docker prune --volumes            # include volumes in the report');
+  logger.log('info', '  gitzone docker prune --volumes --apply --yes');
+}

package/ts/mod_format/index.ts

@@ -335,6 +335,12 @@ const handleFormatFix = async (
     process.cwd(),
   ];
   if (autoApprove) {
+    // -y does more here than skip a prompt: it hands opencode unrestricted
+    // shell access in this directory. That must never be silent.
+    logger.log(
+      "error",
+      "⚠️  --yes runs opencode with --dangerously-skip-permissions: it may run any command in this directory without asking.",
+    );
     opencodeArgs.push("--dangerously-skip-permissions");
   }
   opencodeArgs.push(buildFormatFixPrompt(plan, extraInstructions));
@@ -635,7 +641,8 @@ export function showHelp(mode?: ICliMode): void {
         { flag: "--write, -w", description: "Apply planned changes" },
         {
           flag: "--yes",
-          description: "Skip the interactive confirmation before writing",
+          description:
+            "Skip the interactive confirmation before writing. With `format fix` this additionally runs opencode with --dangerously-skip-permissions, allowing it to run any command in the project.",
         },
         {
           flag: "--plan-only",
@@ -693,7 +700,15 @@ export function showHelp(mode?: ICliMode): void {
   console.log("Flags:");
   console.log("  --write, -w          Apply planned changes");
   console.log(
-    "  --yes                Skip the interactive confirmation before writing",
+    "  --yes                Skip the interactive confirmation before writing.",
+  );
+  logger.log(
+    "info",
+    "                       With `format fix` this also runs opencode with",
+  );
+  logger.log(
+    "info",
+    "                       --dangerously-skip-permissions ⚠️",
   );
   console.log("  --plan-only          Show the plan without applying changes");
   console.log("  --save-plan <file>   Write the format plan to a file");