@git.zone/cli 3.0.1 → 3.0.2

package/dist_ts/plugins.d.ts

@@ -3,6 +3,7 @@ import * as smartlogDestinationLocal from '@push.rocks/smartlog-destination-loca
 import * as smartconfig from '@push.rocks/smartconfig';
 import * as path from 'path';
 import * as fs from 'node:fs/promises';
+import * as crypto from 'node:crypto';
 import * as projectinfo from '@push.rocks/projectinfo';
 import * as smartcli from '@push.rocks/smartcli';
 import * as smartpath from '@push.rocks/smartpath';
@@ -15,4 +16,4 @@ import { SmartFs } from '@push.rocks/smartfs';
 import * as smartinteract from '@push.rocks/smartinteract';
 import * as smartdelay from '@push.rocks/smartdelay';
 export declare const smartfs: SmartFs;
-export { smartlog, smartlogDestinationLocal, smartconfig, path, fs, projectinfo, smartcli, smartpath, smartpromise, smartupdate, smartshell, smartnetwork, smartfile, smartinteract, smartdelay, };
+export { smartlog, smartlogDestinationLocal, smartconfig, path, fs, crypto, projectinfo, smartcli, smartpath, smartpromise, smartupdate, smartshell, smartnetwork, smartfile, smartinteract, smartdelay, };

package/dist_ts/plugins.js

@@ -3,6 +3,7 @@ import * as smartlogDestinationLocal from '@push.rocks/smartlog-destination-loca
 import * as smartconfig from '@push.rocks/smartconfig';
 import * as path from 'path';
 import * as fs from 'node:fs/promises';
+import * as crypto from 'node:crypto';
 import * as projectinfo from '@push.rocks/projectinfo';
 import * as smartcli from '@push.rocks/smartcli';
 import * as smartpath from '@push.rocks/smartpath';
@@ -16,5 +17,5 @@ import * as smartinteract from '@push.rocks/smartinteract';
 import * as smartdelay from '@push.rocks/smartdelay';
 // Create smartfs instance for filesystem operations
 export const smartfs = new SmartFs(new SmartFsProviderNode());
-export { smartlog, smartlogDestinationLocal, smartconfig, path, fs, projectinfo, smartcli, smartpath, smartpromise, smartupdate, smartshell, smartnetwork, smartfile, smartinteract, smartdelay, };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLFFBQVEsTUFBTSxzQkFBc0IsQ0FBQztBQUNqRCxPQUFPLEtBQUssd0JBQXdCLE1BQU0sd0NBQXdDLENBQUM7QUFDbkYsT0FBTyxLQUFLLFdBQVcsTUFBTSx5QkFBeUIsQ0FBQztBQUN2RCxPQUFPLEtBQUssSUFBSSxNQUFNLE1BQU0sQ0FBQztBQUM3QixPQUFPLEtBQUssRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBQ3ZDLE9BQU8sS0FBSyxXQUFXLE1BQU0seUJBQXlCLENBQUM7QUFDdkQsT0FBTyxLQUFLLFFBQVEsTUFBTSxzQkFBc0IsQ0FBQztBQUNqRCxPQUFPLEtBQUssU0FBUyxNQUFNLHVCQUF1QixDQUFDO0FBQ25ELE9BQU8sS0FBSyxZQUFZLE1BQU0sMEJBQTBCLENBQUM7QUFDekQsT0FBTyxLQUFLLFdBQVcsTUFBTSx5QkFBeUIsQ0FBQztBQUN2RCxPQUFPLEtBQUssVUFBVSxNQUFNLHdCQUF3QixDQUFDO0FBQ3JELE9BQU8sS0FBSyxZQUFZLE1BQU0sMEJBQTBCLENBQUM7QUFDekQsT0FBTyxLQUFLLFNBQVMsTUFBTSx1QkFBdUIsQ0FBQztBQUNuRCxPQUFPLEVBQUUsT0FBTyxFQUFFLG1CQUFtQixFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFDbkUsT0FBTyxLQUFLLGFBQWEsTUFBTSwyQkFBMkIsQ0FBQztBQUMzRCxPQUFPLEtBQUssVUFBVSxNQUFNLHdCQUF3QixDQUFDO0FBRXJELG9EQUFvRDtBQUNwRCxNQUFNLENBQUMsTUFBTSxPQUFPLEdBQUcsSUFBSSxPQUFPLENBQUMsSUFBSSxtQkFBbUIsRUFBRSxDQUFDLENBQUM7QUFFOUQsT0FBTyxFQUNMLFFBQVEsRUFDUix3QkFBd0IsRUFDeEIsV0FBVyxFQUNYLElBQUksRUFDSixFQUFFLEVBQ0YsV0FBVyxFQUNYLFFBQVEsRUFDUixTQUFTLEVBQ1QsWUFBWSxFQUNaLFdBQVcsRUFDWCxVQUFVLEVBQ1YsWUFBWSxFQUNaLFNBQVMsRUFDVCxhQUFhLEVBQ2IsVUFBVSxHQUNYLENBQUMifQ==
+export { smartlog, smartlogDestinationLocal, smartconfig, path, fs, crypto, projectinfo, smartcli, smartpath, smartpromise, smartupdate, smartshell, smartnetwork, smartfile, smartinteract, smartdelay, };
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLFFBQVEsTUFBTSxzQkFBc0IsQ0FBQztBQUNqRCxPQUFPLEtBQUssd0JBQXdCLE1BQU0sd0NBQXdDLENBQUM7QUFDbkYsT0FBTyxLQUFLLFdBQVcsTUFBTSx5QkFBeUIsQ0FBQztBQUN2RCxPQUFPLEtBQUssSUFBSSxNQUFNLE1BQU0sQ0FBQztBQUM3QixPQUFPLEtBQUssRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBQ3ZDLE9BQU8sS0FBSyxNQUFNLE1BQU0sYUFBYSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxXQUFXLE1BQU0seUJBQXlCLENBQUM7QUFDdkQsT0FBTyxLQUFLLFFBQVEsTUFBTSxzQkFBc0IsQ0FBQztBQUNqRCxPQUFPLEtBQUssU0FBUyxNQUFNLHVCQUF1QixDQUFDO0FBQ25ELE9BQU8sS0FBSyxZQUFZLE1BQU0sMEJBQTBCLENBQUM7QUFDekQsT0FBTyxLQUFLLFdBQVcsTUFBTSx5QkFBeUIsQ0FBQztBQUN2RCxPQUFPLEtBQUssVUFBVSxNQUFNLHdCQUF3QixDQUFDO0FBQ3JELE9BQU8sS0FBSyxZQUFZLE1BQU0sMEJBQTBCLENBQUM7QUFDekQsT0FBTyxLQUFLLFNBQVMsTUFBTSx1QkFBdUIsQ0FBQztBQUNuRCxPQUFPLEVBQUUsT0FBTyxFQUFFLG1CQUFtQixFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFDbkUsT0FBTyxLQUFLLGFBQWEsTUFBTSwyQkFBMkIsQ0FBQztBQUMzRCxPQUFPLEtBQUssVUFBVSxNQUFNLHdCQUF3QixDQUFDO0FBRXJELG9EQUFvRDtBQUNwRCxNQUFNLENBQUMsTUFBTSxPQUFPLEdBQUcsSUFBSSxPQUFPLENBQUMsSUFBSSxtQkFBbUIsRUFBRSxDQUFDLENBQUM7QUFFOUQsT0FBTyxFQUNMLFFBQVEsRUFDUix3QkFBd0IsRUFDeEIsV0FBVyxFQUNYLElBQUksRUFDSixFQUFFLEVBQ0YsTUFBTSxFQUNOLFdBQVcsRUFDWCxRQUFRLEVBQ1IsU0FBUyxFQUNULFlBQVksRUFDWixXQUFXLEVBQ1gsVUFBVSxFQUNWLFlBQVksRUFDWixTQUFTLEVBQ1QsYUFBYSxFQUNiLFVBQVUsR0FDWCxDQUFDIn0=

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@git.zone/cli",
   "private": false,
-  "version": "3.0.1",
+  "version": "3.0.2",
   "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.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
@@ -40,9 +40,9 @@
   "homepage": "https://code.foss.global/git.zone/cli#README",
   "devDependencies": {
     "@git.zone/tsbuild": "^4.4.2",
-    "@git.zone/tsrun": "^2.0.5",
-    "@git.zone/tstest": "^3.6.6",
-    "@types/node": "^25.9.3"
+    "@git.zone/tsrun": "^2.0.6",
+    "@git.zone/tstest": "^3.6.7",
+    "@types/node": "^26.1.1"
   },
   "dependencies": {
     "@git.zone/tsdoc": "^2.1.1",
@@ -69,7 +69,7 @@
     "@push.rocks/smartpath": "^6.0.0",
     "@push.rocks/smartpromise": "^4.2.3",
     "@push.rocks/smartscaf": "^4.0.22",
-    "@push.rocks/smartshell": "^3.5.0",
+    "@push.rocks/smartshell": "^4.0.0",
     "@push.rocks/smartunique": "^3.0.9",
     "@push.rocks/smartupdate": "^2.0.7",
     "prettier": "^3.8.1"

package/readme.md

@@ -458,6 +458,20 @@ gitzone services logs mongo 50
 
 Service config is stored in `.nogit/env.json`. Data is stored below `.nogit/`, so it stays out of Git.
 
+GitZone derives new MinIO bucket names from the project name using S3 naming
+rules. When loading older configuration it repairs only the exact generated
+`<project>-documents` value if that value is invalid; custom bucket names are
+never rewritten. `services start minio` validates custom names, recreates a
+container whose configured credentials or ports drifted, authenticates the
+configured alias, creates the bucket idempotently, and verifies it before
+reporting success. Before GitZone starts, recreates, or executes inside an
+existing MinIO container, current-project ownership must be proven by exact
+GitZone labels or one unambiguous legacy registry claim. Every lifecycle
+operation after discovery uses the container's immutable id. If startup fails,
+GitZone stops only containers that this invocation started; it never stops a
+container that was already running. Invalid custom names do not block read-only
+or recovery commands such as `status`, `logs`, `stop`, `remove`, and `clean`.
+
 ### Consuming a service programmatically
 
 `gitzone services status --json` emits only JSON on stdout, so a test suite or

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/cli',
-  version: '3.0.1',
+  version: '3.0.2',
   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/mod_docker/classes.dockerpruner.ts

@@ -71,15 +71,14 @@ const dockerCommand = `timeout ${dockerTimeoutSeconds}s docker`;
 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 run(commandArg: string): Promise<plugins.smartshell.IExecResult> {
+    return this.smartshell.execSilent(commandArg);
   }
 
   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}`);
+      throw new Error(result.combinedOutput);
     }
     if (!result.stdout.trim()) {
       return [];
@@ -99,7 +98,7 @@ export class DockerPruner {
       `${dockerCommand} inspect ${idsArg.map((id) => shellQuote(id)).join(' ')}`,
     );
     if (result.exitCode !== 0) {
-      throw new Error(result.stdout || 'docker inspect failed');
+      throw new Error(result.combinedOutput);
     }
     try {
       const parsed = JSON.parse(result.stdout);
@@ -287,7 +286,7 @@ export class DockerPruner {
         }
         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}`);
+          throw new Error(`Failed to remove container ${planned.name}: ${result.combinedOutput}`);
         }
         removedContainers.push(planned.name);
         logger.log('ok', `Removed container ${planned.name}`);
@@ -322,7 +321,7 @@ export class DockerPruner {
         }
         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}`);
+          throw new Error(`Failed to remove volume ${planned.name}: ${result.combinedOutput}`);
         }
         removedVolumes.push(planned.name);
         logger.log('ok', `Removed volume ${planned.name}`);

package/ts/mod_release/index.ts

@@ -247,7 +247,7 @@ async function runNpmTarget(
   for (const registry of workflow.npmRegistries) {
     const command = `pnpm publish --registry=${registry} --access=${workflow.npmAccessLevel}`;
     const result = await smartshellInstance.exec(command);
-    const output = `${result.stdout || ""}\n${(result as any).stderr || ""}\n${(result as any).combinedOutput || ""}`;
+    const output = result.combinedOutput;
     if (result.exitCode === 0) {
       results.push({ target: registry, status: "success" });
     } else if (isAlreadyPublishedOutput(output) && workflow.npmAlreadyPublished === "success") {
@@ -269,7 +269,7 @@ async function runDockerTarget(
 
   const command = buildTsdockerPushCommand(workflow);
   const result = await smartshellInstance.exec(command);
-  const output = `${result.stdout || ""}\n${(result as any).stderr || ""}\n${(result as any).combinedOutput || ""}`;
+  const output = result.combinedOutput;
   return [{
     target: workflow.dockerPatterns.length > 0
       ? `tsdocker:${workflow.dockerPatterns.join(",")}`

package/ts/mod_services/classes.dockercontainer.ts

@@ -25,6 +25,48 @@ export interface IDockerRunOptions {
   command?: string;
 }
 
+export interface IDockerCreateArgvOptions extends Omit<IDockerRunOptions, 'command'> {
+  /** Container command passed as exact argv entries. */
+  command?: readonly string[];
+}
+
+export interface IDockerExecArgvOptions {
+  /** Hard per-process wall-clock bound. */
+  timeoutMs: number;
+}
+
+export interface IDockerExecArgvResult {
+  stdout: string;
+  stderr: string;
+}
+
+export interface IDockerArgvExecutionErrorOptions {
+  timeoutMs: number;
+  timedOut: boolean;
+  exitCode?: number;
+  signal?: NodeJS.Signals;
+}
+
+/** Sanitised failure from the shell-free Docker execution path. */
+export class DockerArgvExecutionError extends Error {
+  public readonly exitCode?: number;
+  public readonly signal?: NodeJS.Signals;
+
+  constructor(optionsArg: IDockerArgvExecutionErrorOptions) {
+    const detail = optionsArg.timedOut
+      ? `timed out after ${optionsArg.timeoutMs}ms`
+      : optionsArg.signal
+        ? `terminated by signal ${optionsArg.signal}`
+        : optionsArg.exitCode === undefined
+          ? 'could not be started'
+          : `exited with code ${optionsArg.exitCode}`;
+    super(`Docker command ${detail}`);
+    this.name = 'DockerArgvExecutionError';
+    this.exitCode = optionsArg.exitCode;
+    this.signal = optionsArg.signal;
+  }
+}
+
 /** Container facts needed to decide, safely, whether a container may be removed. */
 export interface IContainerInspectInfo {
   id: string;
@@ -124,6 +166,108 @@ export class DockerContainer {
     return `timeout ${seconds}s docker`;
   }
 
+  /**
+   * Execute Docker directly with exact argv boundaries and strict failures.
+   * Arguments and output are not retained in errors, keeping this safe for
+   * credential-boundary operations.
+   */
+  public async execArgv(
+    argvArg: readonly string[],
+    optionsArg: IDockerExecArgvOptions,
+  ): Promise<IDockerExecArgvResult> {
+    return this.execArgvInternal(argvArg, optionsArg, process.env);
+  }
+
+  private async execArgvInternal(
+    argvArg: readonly string[],
+    optionsArg: IDockerExecArgvOptions,
+    environmentArg: NodeJS.ProcessEnv,
+  ): Promise<IDockerExecArgvResult> {
+    if (!Array.isArray(argvArg) || argvArg.length === 0) {
+      throw new Error('Docker argv must contain at least one argument');
+    }
+    if (argvArg.some((argumentArg) => typeof argumentArg !== 'string' || argumentArg.includes('\0'))) {
+      throw new Error('Docker argv must contain only NUL-free strings');
+    }
+    if (!Number.isSafeInteger(optionsArg?.timeoutMs) || optionsArg.timeoutMs <= 0) {
+      throw new Error('Docker argv timeoutMs must be a positive safe integer');
+    }
+
+    try {
+      const result = await this.smartshell.execSpawn('docker', [...argvArg], {
+        silent: true,
+        strict: true,
+        timeout: optionsArg.timeoutMs,
+        timeoutKillGraceMs: 0,
+        maxBuffer: 1024 * 1024,
+        env: environmentArg,
+      });
+      return {
+        stdout: result.stdout,
+        stderr: result.stderr,
+      };
+    } catch (error) {
+      if (error instanceof plugins.smartshell.SmartshellError) {
+        throw new DockerArgvExecutionError({
+          timeoutMs: optionsArg.timeoutMs,
+          timedOut: error.timedOut,
+          exitCode: error.exitCode,
+          signal: error.signal,
+        });
+      }
+      throw new DockerArgvExecutionError({
+        timeoutMs: optionsArg.timeoutMs,
+        timedOut: false,
+      });
+    }
+  }
+
+  /**
+   * Create, but do not start, a container without a host shell. Environment
+   * values are inherited by name so credentials do not enter Docker's argv or
+   * command errors. The returned stdout contains Docker's immutable id.
+   */
+  public async createArgv(
+    optionsArg: IDockerCreateArgvOptions,
+    executionOptionsArg: IDockerExecArgvOptions,
+  ): Promise<IDockerExecArgvResult> {
+    const argv: string[] = ['create', '--name', optionsArg.name];
+
+    for (const [hostPort, containerPort] of Object.entries(optionsArg.ports || {})) {
+      argv.push('-p', `${hostPort}:${containerPort}`);
+    }
+    for (const [hostPath, containerPath] of Object.entries(optionsArg.volumes || {})) {
+      argv.push('-v', `${hostPath}:${containerPath}`);
+    }
+
+    const childEnvironment: NodeJS.ProcessEnv = { ...process.env };
+    for (const [key, value] of Object.entries(optionsArg.environment || {})) {
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(key)) {
+        throw new Error(`Invalid Docker environment variable name: ${key}`);
+      }
+      childEnvironment[key] = value;
+      argv.push('--env', key);
+    }
+
+    for (const [key, value] of Object.entries(optionsArg.labels || {})) {
+      argv.push('--label', `${key}=${value}`);
+    }
+    for (const [name, limit] of Object.entries(optionsArg.ulimits || {})) {
+      assertDockerUlimit(name, limit);
+      argv.push('--ulimit', `${name}=${limit.soft}:${limit.hard}`);
+    }
+    if (optionsArg.restart) {
+      argv.push('--restart', optionsArg.restart);
+    }
+
+    argv.push(optionsArg.image);
+    if (optionsArg.command) {
+      argv.push(...optionsArg.command);
+    }
+
+    return this.execArgvInternal(argv, executionOptionsArg, childEnvironment);
+  }
+
   /**
    * Check if Docker is installed and available
    */
@@ -406,9 +550,9 @@ export class DockerContainer {
   ): Promise<{ exitCode: number; output: string }> {
     try {
       const result = await this.smartshell.execSilent(
-        `${this.bounded(this.queryTimeoutSeconds)} exec ${containerName} ${command} 2>&1`,
+        `${this.bounded(this.queryTimeoutSeconds)} exec ${containerName} ${command}`,
       );
-      return { exitCode: result.exitCode, output: result.stdout || '' };
+      return { exitCode: result.exitCode, output: result.combinedOutput };
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       return { exitCode: -1, output: errorMessage };
@@ -422,7 +566,7 @@ export class DockerContainer {
     try {
       const tailFlag = lines ? `--tail ${lines}` : '';
       const result = await this.smartshell.exec(`docker logs ${tailFlag} ${containerName}`);
-      return result.stdout;
+      return result.combinedOutput;
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       return `Error getting logs: ${errorMessage}`;
@@ -520,7 +664,7 @@ export class DockerContainer {
       `${this.bounded(this.queryTimeoutSeconds)} ps ${allFlag} ${filters} --format '{{.ID}}'`,
     );
     if (result.exitCode !== 0) {
-      throw new Error(result.stderr || result.stdout || 'docker ps failed');
+      throw new Error(result.combinedOutput);
     }
     if (!result.stdout.trim()) {
       return [];
@@ -544,7 +688,7 @@ export class DockerContainer {
       `${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');
+      throw new Error(result.combinedOutput);
     }
     let parsed: any;
     try {

package/ts/mod_services/classes.serviceconfiguration.ts

@@ -17,6 +17,104 @@ export const isLocalMongoHost = (hostArg: string): boolean => {
   return localMongoHosts.includes(hostArg.trim().toLowerCase());
 };
 
+const s3ReservedPrefixes = ['xn--', 'sthree-', 'amzn-s3-demo-'];
+const s3ReservedSuffixes = ['-s3alias', '--ol-s3', '.mrap', '--x-s3', '--table-s3'];
+const s3BucketPattern = /^[a-z0-9][a-z0-9.-]*[a-z0-9]$/u;
+const ipv4AddressPattern = /^(?:\d{1,3}\.){3}\d{1,3}$/u;
+
+const isIpv4Address = (valueArg: string): boolean => {
+  if (!ipv4AddressPattern.test(valueArg)) {
+    return false;
+  }
+  return valueArg.split('.').every((octetArg) => Number(octetArg) <= 255);
+};
+
+/** Validate a bucket against the current S3 general-purpose naming rules. */
+export const getS3BucketNameValidationError = (bucketArg: unknown): string | undefined => {
+  if (typeof bucketArg !== 'string') {
+    return 'must be a string';
+  }
+  if (bucketArg.length < 3 || bucketArg.length > 63) {
+    return 'must contain between 3 and 63 characters';
+  }
+  if (!s3BucketPattern.test(bucketArg)) {
+    return 'must use only lowercase letters, numbers, periods, and hyphens, with an alphanumeric first and last character';
+  }
+  if (bucketArg.includes('..')) {
+    return 'must not contain adjacent periods';
+  }
+  const reservedPrefix = s3ReservedPrefixes.find((prefixArg) => bucketArg.startsWith(prefixArg));
+  if (reservedPrefix) {
+    return `must not start with the reserved prefix "${reservedPrefix}"`;
+  }
+  const reservedSuffix = s3ReservedSuffixes.find((suffixArg) => bucketArg.endsWith(suffixArg));
+  if (reservedSuffix) {
+    return `must not end with the reserved suffix "${reservedSuffix}"`;
+  }
+  if (isIpv4Address(bucketArg)) {
+    return 'must not be formatted as an IPv4 address';
+  }
+  return undefined;
+};
+
+export const isValidS3BucketName = (bucketArg: unknown): bucketArg is string => {
+  return getS3BucketNameValidationError(bucketArg) === undefined;
+};
+
+/**
+ * Derive GitZone's bucket from a project name using a deliberately smaller
+ * alphabet than custom S3 names. Long names retain a stable hash suffix.
+ */
+export const deriveS3BucketName = (projectNameArg: string): string => {
+  const source = `${projectNameArg}-documents`;
+  let canonical = source
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, '-')
+    .replace(/^-+|-+$/gu, '');
+
+  if (!canonical) {
+    canonical = 'project-documents';
+  }
+
+  if (
+    s3ReservedPrefixes.some((prefixArg) => canonical.startsWith(prefixArg)) ||
+    s3ReservedSuffixes.some((suffixArg) => canonical.endsWith(suffixArg)) ||
+    isIpv4Address(canonical)
+  ) {
+    canonical = `gitzone-${canonical}`;
+  }
+
+  if (canonical.length > 63) {
+    const stableHash = plugins.crypto.createHash('sha256').update(source).digest('hex').slice(0, 12);
+    const prefixLength = 63 - stableHash.length - 1;
+    const prefix = canonical.slice(0, prefixLength).replace(/-+$/u, '');
+    canonical = `${prefix}-${stableHash}`;
+  }
+
+  const validationError = getS3BucketNameValidationError(canonical);
+  if (validationError) {
+    throw new Error(`Could not derive a valid S3 bucket name: ${validationError}`);
+  }
+  return canonical;
+};
+
+export type TLegacyS3BucketRepair =
+  | { bucket: unknown; repaired: false }
+  | { bucket: string; repaired: true };
+
+/** Repair only the exact invalid value emitted by older GitZone releases. */
+export const repairLegacyGeneratedS3Bucket = (
+  projectNameArg: string,
+  bucketArg: unknown,
+): TLegacyS3BucketRepair => {
+  const legacyGeneratedBucket = `${projectNameArg}-documents`;
+  if (bucketArg !== legacyGeneratedBucket || isValidS3BucketName(bucketArg)) {
+    return { bucket: bucketArg, repaired: false };
+  }
+  return { bucket: deriveS3BucketName(projectNameArg), repaired: true };
+};
+
 export interface IServiceConfig {
   PROJECT_NAME: string;
   MONGODB_HOST: string;
@@ -255,7 +353,7 @@ export class ServiceConfiguration {
       S3_CONSOLE_PORT: s3ConsolePort.toString(),
       S3_ACCESSKEY: 'defaultadmin',
       S3_SECRETKEY: 'defaultpass',
-      S3_BUCKET: `${projectName}-documents`,
+      S3_BUCKET: deriveS3BucketName(projectName),
       S3_ENDPOINT: s3Host,
       S3_USESSL: false,
       ELASTICSEARCH_HOST: esHost,
@@ -373,9 +471,19 @@ export class ServiceConfiguration {
     }
     
     if (!this.config.S3_BUCKET) {
-      this.config.S3_BUCKET = `${projectName}-documents`;
+      this.config.S3_BUCKET = deriveS3BucketName(this.config.PROJECT_NAME);
       fieldsAdded.push('S3_BUCKET');
       updated = true;
+    } else {
+      const repair = repairLegacyGeneratedS3Bucket(
+        this.config.PROJECT_NAME,
+        this.config.S3_BUCKET,
+      );
+      if (repair.repaired) {
+        this.config.S3_BUCKET = repair.bucket;
+        fieldsAdded.push('S3_BUCKET(repaired legacy generated name)');
+        updated = true;
+      }
     }
     
     // `undefined`, not falsy: a stored `false` is a valid value, and treating it