@git.zone/cli 2.24.0 → 2.25.1

package/readme.md

@@ -527,6 +527,58 @@ non-local `MONGODB_HOST` is refused outright. Transactions continue to work, and
 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
 
 Start new projects with built-in scaffolds:

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/cli',
-  version: '2.24.0',
+  version: '2.25.1',
   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.serviceconfiguration.ts

@@ -3,6 +3,12 @@ import * as helpers from './helpers.js';
 import { logger } from '../gitzone.logging.js';
 import { DockerContainer } from './classes.dockercontainer.js';
 import { getServiceDataDirectory } from './classes.servicedatamarker.js';
+import {
+  readServiceOptions,
+  resolveMongoAuth,
+  writeMongodbAuthOption,
+  type TServiceOptionSource,
+} from './classes.serviceoptions.js';
 
 /** Hosts that are considered local for the purposes of the no-auth guard. */
 const localMongoHosts = ['localhost', '127.0.0.1', '::1'];
@@ -44,30 +50,60 @@ export class ServiceConfiguration {
   private configPath: string;
   private config!: IServiceConfig;
   private docker: DockerContainer;
-  
+  /** Where the effective MongoDB auth mode came from. */
+  private mongoAuthSource: TServiceOptionSource = 'default';
+
   constructor() {
     this.configPath = plugins.path.join(process.cwd(), '.nogit', 'env.json');
     this.docker = new DockerContainer();
   }
-  
+
   /**
    * Load or create the configuration
    */
   public async loadOrCreate(): Promise<IServiceConfig> {
     await this.ensureNogitDirectory();
-    
+
     if (await this.configExists()) {
       await this.loadConfig();
       await this.updateMissingFields();
     } else {
       await this.createDefaultConfig();
     }
-    
+
+    // A committed declaration in .smartconfig.json overrides the local runtime
+    // value, so a fresh checkout reproduces the declared setup.
+    await this.applyDeclaredServiceOptions();
+
     // Sync ports from existing Docker containers if they exist
     await this.syncPortsFromDocker();
-    
+
     return this.config;
   }
+
+  /**
+   * Fold `@git.zone/cli.serviceOptions` into the runtime configuration.
+   */
+  private async applyDeclaredServiceOptions(): Promise<void> {
+    const declaredOptions = await readServiceOptions(process.cwd());
+    const resolved = resolveMongoAuth(declaredOptions, this.config.MONGODB_AUTH_ENABLED);
+    this.mongoAuthSource = resolved.source;
+
+    if (this.config.MONGODB_AUTH_ENABLED !== resolved.authEnabled) {
+      this.config.MONGODB_AUTH_ENABLED = resolved.authEnabled;
+      this.updateDerivedFields();
+      await this.saveConfig();
+      logger.log(
+        'note',
+        `📍 MongoDB auth ${resolved.authEnabled ? 'enabled' : 'disabled'} by .smartconfig.json declaration`,
+      );
+    }
+  }
+
+  /** Where the effective MongoDB auth mode came from. */
+  public getMongoAuthSource(): TServiceOptionSource {
+    return this.mongoAuthSource;
+  }
   
   /**
    * Get the current configuration
@@ -128,13 +164,19 @@ export class ServiceConfiguration {
   }
 
   /**
-   * Persist the MongoDB auth mode and recompute derived fields.
+   * Persist the MongoDB auth mode.
+   *
+   * Written to both `.smartconfig.json` (the committed declaration, so a fresh
+   * checkout or CI reproduces it) and `.nogit/env.json` (the resolved runtime
+   * value consumed by tooling). Writing both keeps them from drifting.
    */
   public async setMongoAuthEnabled(enabledArg: boolean): Promise<void> {
     this.config.MONGODB_AUTH_ENABLED = enabledArg;
     this.updateDerivedFields();
     this.assertMongoExposureIsSafe();
     await this.saveConfig();
+    await writeMongodbAuthOption(enabledArg, process.cwd());
+    this.mongoAuthSource = enabledArg ? 'default' : 'declared';
   }
   
   /**

package/ts/mod_services/classes.servicemanager.ts

@@ -11,6 +11,7 @@ import {
 } from './classes.servicedatamarker.js';
 import { logger } from '../gitzone.logging.js';
 import type { ContainerStatus } from './classes.dockercontainer.js';
+import type { TServiceOptionSource } from './classes.serviceoptions.js';
 
 export interface IServiceStatus {
   service: TServiceName;
@@ -25,6 +26,8 @@ export interface IServiceStatus {
   portAvailable: boolean | null;
   /** MongoDB only: whether the instance enforces authentication. */
   authEnabled?: boolean;
+  /** MongoDB only: whether the auth mode is declared in committed config. */
+  authSource?: TServiceOptionSource;
 }
 
 export interface IServicesStatus {
@@ -73,7 +76,10 @@ export class ServiceManager {
     // the misconfiguration. It is enforced where it matters, on the path that
     // actually starts an unauthenticated database.
     if (!this.config.isMongoAuthEnabled()) {
-      logger.log('note', '⚠️  MongoDB auth is disabled for this project (loopback only)');
+      logger.log(
+        'note',
+        `⚠️  MongoDB auth is disabled for this project (loopback only) — ${this.describeMongoAuthSource()}`,
+      );
     }
 
     // Load service selection from .smartconfig.json
@@ -88,6 +94,22 @@ export class ServiceManager {
     await this.globalRegistry.touchProject(process.cwd());
   }
 
+  /**
+   * Human phrasing for where the auth mode came from. A declared auth-off is
+   * committed to the repository and therefore affects everyone who clones it,
+   * so it must never read the same as a local-only choice.
+   */
+  private describeMongoAuthSource(): string {
+    switch (this.config.getMongoAuthSource()) {
+      case 'declared':
+        return 'declared in .smartconfig.json (applies to every checkout)';
+      case 'local':
+        return 'set locally in .nogit/env.json';
+      default:
+        return 'default';
+    }
+  }
+
   /**
    * Expose the resolved service configuration to the command layer.
    */
@@ -332,7 +354,10 @@ export class ServiceManager {
     logger.log('info', `  Container: ${containers.mongo}`);
     logger.log('info', `  Port: ${config.MONGODB_PORT}`);
     if (!this.config.isMongoAuthEnabled()) {
-      logger.log('note', '  ⚠️  Auth: DISABLED — published on loopback only (127.0.0.1)');
+      logger.log(
+        'note',
+        `  ⚠️  Auth: DISABLED — published on loopback only (127.0.0.1), ${this.describeMongoAuthSource()}`,
+      );
     }
     logger.log('info', `  Connection: ${this.config.getMongoConnectionString()}`);
 
@@ -866,6 +891,7 @@ export class ServiceManager {
       this.config.getMongoConnectionString(),
     );
     mongo.authEnabled = this.config.isMongoAuthEnabled();
+    mongo.authSource = this.config.getMongoAuthSource();
 
     const minio = await describe(
       'minio',
@@ -913,7 +939,10 @@ export class ServiceManager {
         logger.log('info', `   ├─ Container: ${containers.mongo}`);
         logger.log('info', `   ├─ Port: ${config.MONGODB_PORT}`);
         if (!this.config.isMongoAuthEnabled()) {
-          logger.log('note', '   ├─ ⚠️  Auth: DISABLED (loopback only)');
+          logger.log(
+            'note',
+            `   ├─ ⚠️  Auth: DISABLED (loopback only), ${this.describeMongoAuthSource()}`,
+          );
         }
         logger.log('info', `   ├─ Connection: ${this.config.getMongoConnectionString()}`);
 

package/ts/mod_services/classes.serviceoptions.ts

@@ -0,0 +1,135 @@
+import * as plugins from './mod.plugins.js';
+import {
+  getCliConfigValueFromData,
+  readSmartconfigFile,
+  setCliConfigValueInData,
+  writeSmartconfigFile,
+} from '../helpers.smartconfig.js';
+import type { TServiceName } from './classes.servicedatamarker.js';
+
+/**
+ * Committed, per-service configuration.
+ *
+ * Deliberately a SIBLING of `@git.zone/cli.services` rather than a richer
+ * `services` value. `@git.zone/tsdeploy` derives a workload's
+ * `requiredCapabilities` from that array and **throws** on any element that is
+ * not a canonical lowercase string, so an array of objects — or a mixed array —
+ * would hard-fail real deployments. `services` therefore stays exactly
+ * `string[]`, and configuration lives here where TsDeploy never looks.
+ *
+ * Config path: `@git.zone/cli.serviceOptions`.
+ */
+export const serviceOptionsConfigKey = 'serviceOptions';
+
+export interface IMongodbServiceOptions {
+  /**
+   * When false, mongod runs without authentication and is published on
+   * loopback only. Opt-in, for runtimes whose `node:crypto` cannot complete a
+   * SCRAM handshake (notably Deno). Absent means enabled.
+   */
+  auth?: boolean;
+}
+
+export interface IServiceOptions {
+  mongodb?: IMongodbServiceOptions;
+}
+
+const isPlainObject = (value: unknown): value is Record<string, any> => {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+
+/**
+ * Read declared service options from `.smartconfig.json`.
+ *
+ * Unknown or malformed values are ignored rather than throwing: this file is
+ * hand-edited, and a typo must not make every services command unusable. The
+ * effect of ignoring is always the safe default (auth enabled).
+ */
+export const readServiceOptions = async (
+  cwd: string = process.cwd(),
+): Promise<IServiceOptions> => {
+  const smartconfigData = await readSmartconfigFile(cwd);
+  const rawOptions = getCliConfigValueFromData(smartconfigData, serviceOptionsConfigKey);
+  if (!isPlainObject(rawOptions)) {
+    return {};
+  }
+
+  const options: IServiceOptions = {};
+  if (isPlainObject(rawOptions.mongodb) && typeof rawOptions.mongodb.auth === 'boolean') {
+    options.mongodb = { auth: rawOptions.mongodb.auth };
+  }
+  return options;
+};
+
+/**
+ * Declare whether MongoDB enforces authentication for this project.
+ *
+ * Writing `true` removes the declaration instead of recording it: the default
+ * is already "enabled", and an absent key keeps committed config free of noise
+ * while remaining unambiguous to an older CLI that ignores this key entirely.
+ */
+export const writeMongodbAuthOption = async (
+  authEnabledArg: boolean,
+  cwd: string = process.cwd(),
+): Promise<void> => {
+  const smartconfigData = await readSmartconfigFile(cwd);
+  const rawOptions = getCliConfigValueFromData(smartconfigData, serviceOptionsConfigKey);
+  const nextOptions: Record<string, any> = isPlainObject(rawOptions) ? { ...rawOptions } : {};
+
+  if (authEnabledArg) {
+    if (isPlainObject(nextOptions.mongodb)) {
+      const { auth, ...restOfMongodb } = nextOptions.mongodb;
+      if (Object.keys(restOfMongodb).length > 0) {
+        nextOptions.mongodb = restOfMongodb;
+      } else {
+        delete nextOptions.mongodb;
+      }
+    }
+  } else {
+    nextOptions.mongodb = { ...(isPlainObject(nextOptions.mongodb) ? nextOptions.mongodb : {}), auth: false };
+  }
+
+  if (Object.keys(nextOptions).length === 0) {
+    // Drop the key entirely rather than leaving an empty object behind.
+    const cliConfig = smartconfigData['@git.zone/cli'];
+    if (isPlainObject(cliConfig)) {
+      delete cliConfig[serviceOptionsConfigKey];
+    }
+  } else {
+    setCliConfigValueInData(smartconfigData, serviceOptionsConfigKey, nextOptions);
+  }
+
+  await writeSmartconfigFile(smartconfigData, cwd);
+};
+
+/**
+ * Where an effective setting came from, so the CLI can say so out loud.
+ */
+export type TServiceOptionSource = 'declared' | 'local' | 'default';
+
+export interface IResolvedMongoAuth {
+  authEnabled: boolean;
+  source: TServiceOptionSource;
+}
+
+/**
+ * Resolve the effective MongoDB auth mode.
+ *
+ * A committed declaration wins over `.nogit/env.json`. That ordering is what
+ * makes a fresh checkout reproducible: without it, a stale local env.json would
+ * silently diverge from what the repository declares. When nothing is declared,
+ * an existing local value is preserved so projects configured before
+ * `serviceOptions` existed keep working.
+ */
+export const resolveMongoAuth = (
+  declaredOptionsArg: IServiceOptions,
+  localValueArg: boolean | undefined,
+): IResolvedMongoAuth => {
+  if (typeof declaredOptionsArg.mongodb?.auth === 'boolean') {
+    return { authEnabled: declaredOptionsArg.mongodb.auth, source: 'declared' };
+  }
+  if (typeof localValueArg === 'boolean') {
+    return { authEnabled: localValueArg, source: 'local' };
+  }
+  return { authEnabled: true, source: 'default' };
+};

package/ts/mod_tools/classes.packagemanager.ts

@@ -35,6 +35,11 @@ export interface ILegacyCleanupResult {
   globalDir: string;
   deleted: boolean;
   reason?: string;
+  /**
+   * Managed packages removed from a legacy root that itself had to be kept.
+   * Each entry is `name@version` of an inert copy that nothing resolves to.
+   */
+  stalePackagesRemoved?: string[];
 }
 
 export interface IShimSyncResult {
@@ -179,9 +184,18 @@ export class PackageManagerUtil {
       }
 
       if (!legacyRoot.safeToDelete) {
+        // The root must stay, but the managed copies inside it are inert: the
+        // current global root already provides those packages and no shim
+        // resolves here. Leaving them behind makes the directory look like the
+        // installed version, which misleads anyone inspecting it.
+        const stalePackagesRemoved = await this.removeStaleManagedPackages(
+          legacyRoot,
+          currentPackageNames,
+        );
         cleanupResults.push({
           globalDir: legacyRoot.globalDir,
           deleted: false,
+          stalePackagesRemoved,
           reason:
             legacyRoot.unmanagedPackageNames.length > 0
               ? `kept because it also contains ${legacyRoot.unmanagedPackageNames.join(", ")}`
@@ -231,6 +245,46 @@ export class PackageManagerUtil {
     return cleanupResults;
   }
 
+  /**
+   * Remove managed package copies from a legacy global root that has to be kept.
+   *
+   * Only removes a package when the active global root already provides it and
+   * no command shim points into this legacy root, so nothing that currently
+   * resolves can be affected. Fails closed: any doubt leaves the copy in place.
+   */
+  private async removeStaleManagedPackages(
+    legacyRootArg: ILegacyGlobalRootInfo,
+    currentPackageNamesArg: Set<string>,
+  ): Promise<string[]> {
+    const shimReferences = await this.getShimReferences(legacyRootArg.globalDir);
+    if (shimReferences === null || shimReferences.length > 0) {
+      // PNPM_HOME unknown, or something still resolves here.
+      return [];
+    }
+
+    const removed: string[] = [];
+    for (const packageInfo of legacyRootArg.packages) {
+      if (!packageInfo.packagePath) {
+        continue;
+      }
+      if (!currentPackageNamesArg.has(packageInfo.name)) {
+        // Not provided by the active root — removing it would lose the package.
+        continue;
+      }
+      try {
+        await plugins.fs.rm(packageInfo.packagePath, {
+          recursive: true,
+          force: true,
+        });
+        removed.push(`${packageInfo.name}@${packageInfo.version}`);
+      } catch {
+        // Leave it rather than half-removing it.
+      }
+    }
+
+    return removed;
+  }
+
   public async syncCurrentGlobalShims(): Promise<IShimSyncResult[]> {
     const pnpmShimDirs = await this.getPnpmShimDirs();
     if (!pnpmShimDirs) {

package/ts/mod_tools/index.ts

@@ -95,7 +95,12 @@ async function runUpdate(argvArg: any, mode: ICliMode): Promise<void> {
   const legacyCleanupRoots = legacyRoots.filter(
     (legacyRoot) => legacyRoot.safeToDelete,
   );
-  const legacyCleanupNeeded = legacyCleanupRoots.length > 0;
+  // A root that must be kept can still hold inert copies of managed packages.
+  // Gating cleanup on wholesale deletability alone left those copies in place
+  // forever, so the directory kept advertising a stale version.
+  const legacyCleanupNeeded =
+    legacyCleanupRoots.length > 0 ||
+    legacyRoots.some((legacyRoot) => !legacyRoot.safeToDelete && legacyRoot.packages.length > 0);
 
   if (managedInstalledPackages.length === 0) {
     console.log("No managed @git.zone packages found installed globally.");
@@ -485,6 +490,11 @@ async function cleanupLegacyInstalls(
       console.log(
         `  ${cleanupResult.globalDir} kept (${cleanupResult.reason || "unknown reason"})`,
       );
+      for (const stalePackage of cleanupResult.stalePackagesRemoved || []) {
+        console.log(
+          `    removed stale inert copy ${stalePackage} (the active global root provides it)`,
+        );
+      }
     }
   }
   console.log("");