@git.zone/cli 3.0.1 → 3.1.0

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