v3.3.0

changelog.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 2026-02-06 - 3.3.0 - feat(mod_update)
+add self-update flow, package name parser, dynamic CLI version, and tests
+
+- Add a self-update check in mod_update to detect and optionally update @git.zone/tools (prompts the user or uses --yes).
+- Introduce PackageManagerUtil.parseYarnPackageName to correctly parse scoped and unscoped yarn package strings and use it when collecting installed packages.
+- Add comprehensive unit tests for PackageManagerUtil.isNewerVersion and parseYarnPackageName.
+- Use commitinfo.version for CLI reported version instead of a hardcoded value.
+- Remove automatic invocation of runCli() from ts/index.ts to avoid immediate execution on import.
+
+## 2026-02-05 - 3.2.0 - feat(update)
+enhance package manager detection, version reporting, and add verbose option
+
+- Add IPackageManagerInfo interface and detectPackageManager() to robustly detect npm/yarn/pnpm via 'which' and '--version' fallbacks
+- Make isAvailable() delegate to detectPackageManager() and return structured detection info
+- Add getPackageManagerVersion() to obtain current and latest versions (parses local --version and queries npm registry)
+- Update run() to support a verbose flag, show a package-manager status table, and collect detectedPMs with version/update status
+- Update CLI help and command handling to accept --verbose/-v and pass it through to mod_update.run()
+
 ## 2026-02-03 - 3.1.3 - fix(mod_update)
 try private registry (verdaccio.lossless.digital) first when fetching package versions; fall back to public npm; handle unknown latest versions gracefully in output
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git.zone/tools",
-  "version": "3.1.3",
+  "version": "3.3.0",
   "private": false,
   "type": "module",
   "description": "A CLI tool placeholder for development utilities.",

test/test.node.ts

@@ -1,9 +1,93 @@
 import { expect, tap } from '@git.zone/tstest/tapbundle';
 
 import * as tools from '../ts/index.js';
+import { PackageManagerUtil } from '../ts/mod_update/classes.packagemanager.js';
 
 tap.test('should export runCli function', async () => {
   expect(typeof tools.runCli).toEqual('function');
 });
 
+// ============================================
+// isNewerVersion tests
+// ============================================
+
+tap.test('isNewerVersion: should detect newer major version', async () => {
+  const pmUtil = new PackageManagerUtil();
+  expect(pmUtil.isNewerVersion('1.0.0', '2.0.0')).toBeTrue();
+});
+
+tap.test('isNewerVersion: should detect newer minor version', async () => {
+  const pmUtil = new PackageManagerUtil();
+  expect(pmUtil.isNewerVersion('1.0.0', '1.1.0')).toBeTrue();
+});
+
+tap.test('isNewerVersion: should detect newer patch version', async () => {
+  const pmUtil = new PackageManagerUtil();
+  expect(pmUtil.isNewerVersion('1.0.0', '1.0.1')).toBeTrue();
+});
+
+tap.test('isNewerVersion: should return false for equal versions', async () => {
+  const pmUtil = new PackageManagerUtil();
+  expect(pmUtil.isNewerVersion('1.0.0', '1.0.0')).toBeFalse();
+});
+
+tap.test('isNewerVersion: should return false when current is newer', async () => {
+  const pmUtil = new PackageManagerUtil();
+  expect(pmUtil.isNewerVersion('2.0.0', '1.0.0')).toBeFalse();
+  expect(pmUtil.isNewerVersion('1.1.0', '1.0.0')).toBeFalse();
+  expect(pmUtil.isNewerVersion('1.0.1', '1.0.0')).toBeFalse();
+});
+
+tap.test('isNewerVersion: should handle v-prefixed versions', async () => {
+  const pmUtil = new PackageManagerUtil();
+  expect(pmUtil.isNewerVersion('v1.0.0', 'v2.0.0')).toBeTrue();
+  expect(pmUtil.isNewerVersion('v2.0.0', 'v1.0.0')).toBeFalse();
+});
+
+tap.test('isNewerVersion: should handle mixed prefixed and non-prefixed', async () => {
+  const pmUtil = new PackageManagerUtil();
+  expect(pmUtil.isNewerVersion('v1.0.0', '2.0.0')).toBeTrue();
+  expect(pmUtil.isNewerVersion('1.0.0', 'v2.0.0')).toBeTrue();
+});
+
+tap.test('isNewerVersion: should handle versions with different segment counts', async () => {
+  const pmUtil = new PackageManagerUtil();
+  expect(pmUtil.isNewerVersion('1.0', '1.0.1')).toBeTrue();
+  expect(pmUtil.isNewerVersion('1.0.1', '1.0')).toBeFalse();
+});
+
+// ============================================
+// parseYarnPackageName tests
+// ============================================
+
+tap.test('parseYarnPackageName: should parse scoped package correctly', async () => {
+  const result = PackageManagerUtil.parseYarnPackageName('@git.zone/cli@1.2.3');
+  expect(result.name).toEqual('@git.zone/cli');
+  expect(result.version).toEqual('1.2.3');
+});
+
+tap.test('parseYarnPackageName: should parse unscoped package correctly', async () => {
+  const result = PackageManagerUtil.parseYarnPackageName('typescript@5.3.2');
+  expect(result.name).toEqual('typescript');
+  expect(result.version).toEqual('5.3.2');
+});
+
+tap.test('parseYarnPackageName: should handle empty string', async () => {
+  const result = PackageManagerUtil.parseYarnPackageName('');
+  expect(result.name).toEqual('');
+  expect(result.version).toEqual('unknown');
+});
+
+tap.test('parseYarnPackageName: should handle name with no version', async () => {
+  const result = PackageManagerUtil.parseYarnPackageName('@git.zone/cli');
+  expect(result.name).toEqual('@git.zone/cli');
+  expect(result.version).toEqual('unknown');
+});
+
+tap.test('parseYarnPackageName: should handle unscoped name with no version', async () => {
+  const result = PackageManagerUtil.parseYarnPackageName('typescript');
+  expect(result.name).toEqual('typescript');
+  expect(result.version).toEqual('unknown');
+});
+
 export default tap.start();

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/tools',
-  version: '3.1.3',
+  version: '3.3.0',
   description: 'A CLI tool placeholder for development utilities.'
 }

ts/index.ts

@@ -3,5 +3,3 @@ import * as cli from './tools.cli.js';
 export const runCli = async () => {
   await cli.run();
 };
-
-runCli();

ts/mod_update/classes.packagemanager.ts

@@ -16,6 +16,16 @@ export interface IPackageUpdateInfo {
   needsUpdate: boolean;
 }
 
+export interface IPackageManagerInfo {
+  name: TPackageManager;
+  available: boolean;
+  detectionMethod?: 'which' | 'version-command';
+  path?: string;
+  currentVersion?: string;
+  latestVersion?: string | null;
+  needsUpdate?: boolean;
+}
+
 export class PackageManagerUtil {
   private shell = new plugins.smartshell.Smartshell({
     executor: 'bash',
@@ -23,14 +33,92 @@ export class PackageManagerUtil {
 
   /**
    * Check if a package manager is available on the system
+   * Uses multiple detection methods for robustness across different shell contexts
    */
-  public async isAvailable(pm: TPackageManager): Promise<boolean> {
+  public async isAvailable(pm: TPackageManager, verbose = false): Promise<boolean> {
-    try {
+    const info = await this.detectPackageManager(pm, verbose);
-      const result = await this.shell.execSilent(`which ${pm} >/dev/null 2>&1 && echo "found"`);
+    return info.available;
-      return result.exitCode === 0 && result.stdout.includes('found');
-    } catch {
-      return false;
   }
+
+  /**
+   * Detect a package manager and return detailed info
+   */
+  public async detectPackageManager(pm: TPackageManager, verbose = false): Promise<IPackageManagerInfo> {
+    const info: IPackageManagerInfo = { name: pm, available: false };
+
+    // Primary method: try 'which' command
+    try {
+      const whichResult = await this.shell.execSilent(`which ${pm} 2>/dev/null`);
+      if (whichResult.exitCode === 0 && whichResult.stdout.trim()) {
+        info.available = true;
+        info.detectionMethod = 'which';
+        info.path = whichResult.stdout.trim();
+        if (verbose) {
+          console.log(`  Checking ${pm}... found via 'which' at ${info.path}`);
+        }
+        return info;
+      }
+    } catch {
+      // Continue to fallback
+    }
+
+    // Fallback method: try running pm --version directly
+    // This can find PMs that are available but not in PATH for 'which'
+    try {
+      const versionResult = await this.shell.execSilent(`${pm} --version 2>/dev/null`);
+      if (versionResult.exitCode === 0 && versionResult.stdout.trim()) {
+        info.available = true;
+        info.detectionMethod = 'version-command';
+        if (verbose) {
+          console.log(`  Checking ${pm}... found via '--version' (which failed)`);
+        }
+        return info;
+      }
+    } catch {
+      // Not available
+    }
+
+    if (verbose) {
+      console.log(`  Checking ${pm}... not found`);
+    }
+    return info;
+  }
+
+  /**
+   * Get the current and latest version of a package manager
+   */
+  public async getPackageManagerVersion(pm: TPackageManager): Promise<{ current: string; latest: string | null }> {
+    let current = 'unknown';
+    let latest: string | null = null;
+
+    // Get current version
+    try {
+      const result = await this.shell.execSilent(`${pm} --version 2>/dev/null`);
+      if (result.exitCode === 0 && result.stdout.trim()) {
+        // Parse version from output - handle different formats
+        const output = result.stdout.trim();
+        // npm: "10.2.0", pnpm: "8.15.0", yarn: "1.22.19"
+        // Some may include prefix like "v1.22.19"
+        const versionMatch = output.match(/(\d+\.\d+\.\d+)/);
+        if (versionMatch) {
+          current = versionMatch[1];
+        }
+      }
+    } catch {
+      // Keep as unknown
+    }
+
+    // Get latest version from npm registry
+    try {
+      const result = await this.shell.execSilent(`npm view ${pm} version 2>/dev/null`);
+      if (result.exitCode === 0 && result.stdout.trim()) {
+        latest = result.stdout.trim();
+      }
+    } catch {
+      // Keep as null
+    }
+
+    return { current, latest };
   }
 
   /**
@@ -103,12 +191,11 @@ export class PackageManagerUtil {
             const data = JSON.parse(line);
             if (data.type === 'tree' && data.data && data.data.trees) {
               for (const tree of data.data.trees) {
-                const name = tree.name?.split('@')[0] || '';
+                const parsed = PackageManagerUtil.parseYarnPackageName(tree.name || '');
-                if (name.startsWith('@git.zone/')) {
+                if (parsed.name.startsWith('@git.zone/')) {
-                  const version = tree.name?.split('@').pop() || 'unknown';
                   packages.push({
-                    name,
+                    name: parsed.name,
-                    version,
+                    version: parsed.version,
                     packageManager: pm,
                   });
                 }
@@ -189,6 +276,26 @@ export class PackageManagerUtil {
     }
   }
 
+  /**
+   * Parse a yarn package name string like "@git.zone/cli@1.0.0" into name and version.
+   * Handles scoped packages correctly by splitting on the last '@' (version separator).
+   */
+  public static parseYarnPackageName(fullName: string): { name: string; version: string } {
+    if (!fullName) {
+      return { name: '', version: 'unknown' };
+    }
+    const lastAtIndex = fullName.lastIndexOf('@');
+    // If lastAtIndex is 0, the string is just "@something" with no version
+    // If lastAtIndex is -1, there's no '@' at all
+    if (lastAtIndex <= 0) {
+      return { name: fullName, version: 'unknown' };
+    }
+    return {
+      name: fullName.substring(0, lastAtIndex),
+      version: fullName.substring(lastAtIndex + 1) || 'unknown',
+    };
+  }
+
   /**
    * Compare two semver versions
    * Returns true if latest > current

ts/mod_update/index.ts

@@ -1,6 +1,10 @@
 import * as plugins from './mod.plugins.js';
-import { PackageManagerUtil, type TPackageManager, type IPackageUpdateInfo } from './classes.packagemanager.js';
+import { PackageManagerUtil, type TPackageManager, type IPackageUpdateInfo, type IPackageManagerInfo } from './classes.packagemanager.js';
+import { commitinfo } from '../00_commitinfo_data.js';
 
+// Curated list of known @git.zone CLI tools to track for updates.
+// This list is intentionally hardcoded to only track official tools.
+// Add new entries here when new @git.zone packages are published.
 const GITZONE_PACKAGES = [
   '@git.zone/cli',
   '@git.zone/tsdoc',
@@ -15,33 +19,117 @@ const GITZONE_PACKAGES = [
 
 export interface IUpdateOptions {
   yes?: boolean;
+  verbose?: boolean;
 }
 
 export const run = async (options: IUpdateOptions = {}): Promise<void> => {
   const pmUtil = new PackageManagerUtil();
+  const verbose = options.verbose === true;
 
   console.log('Scanning for installed @git.zone packages...\n');
 
   // Check which package managers are available
-  const availablePMs: TPackageManager[] = [];
+  if (verbose) {
+    console.log('Detecting package managers:');
+  }
+
+  const detectedPMs: IPackageManagerInfo[] = [];
   for (const pm of ['npm', 'yarn', 'pnpm'] as TPackageManager[]) {
-    if (await pmUtil.isAvailable(pm)) {
+    const info = await pmUtil.detectPackageManager(pm, verbose);
-      availablePMs.push(pm);
+    if (info.available) {
+      detectedPMs.push(info);
     }
   }
 
-  if (availablePMs.length === 0) {
+  if (verbose) {
+    console.log('');
+  }
+
+  if (detectedPMs.length === 0) {
     console.log('No package managers found (npm, yarn, pnpm).');
+    console.log('Tried detection via \'which\' command and direct version check.');
     return;
   }
 
-  console.log(`Found package managers: ${availablePMs.join(', ')}\n`);
+  // Get version info for each PM and display status table
+  console.log('Package managers:\n');
+  console.log('  Name     Current     Latest      Status');
+  console.log('  ──────────────────────────────────────────────');
+
+  for (const pmInfo of detectedPMs) {
+    const versionInfo = await pmUtil.getPackageManagerVersion(pmInfo.name);
+    pmInfo.currentVersion = versionInfo.current;
+    pmInfo.latestVersion = versionInfo.latest;
+    pmInfo.needsUpdate = versionInfo.latest
+      ? pmUtil.isNewerVersion(versionInfo.current, versionInfo.latest)
+      : false;
+
+    const name = pmInfo.name.padEnd(9);
+    const current = versionInfo.current.padEnd(12);
+    const latest = (versionInfo.latest || 'unknown').padEnd(12);
+    const status = versionInfo.latest === null
+      ? '? Version unknown'
+      : pmInfo.needsUpdate
+        ? '⬆️  Update available'
+        : '✓ Up to date';
+    console.log(`  ${name}${current}${latest}${status}`);
+  }
+
+  console.log('');
+
+  // === Self-update check ===
+  console.log('Checking for gtools self-update...\n');
+  const selfVersion = commitinfo.version;
+  const selfLatest = await pmUtil.getLatestVersion('@git.zone/tools');
+
+  if (selfLatest && pmUtil.isNewerVersion(selfVersion, selfLatest)) {
+    console.log(`  @git.zone/tools  ${selfVersion} → ${selfLatest}  ⬆️  Update available\n`);
+
+    // Find which PM has it installed globally
+    let selfPm: TPackageManager | null = null;
+    for (const pmInfo of detectedPMs) {
+      const installed = await pmUtil.getInstalledPackages(pmInfo.name);
+      if (installed.some(p => p.name === '@git.zone/tools')) {
+        selfPm = pmInfo.name;
+        break;
+      }
+    }
+
+    if (!selfPm) {
+      // Fallback: use first available PM
+      selfPm = detectedPMs[0].name;
+    }
+
+    let shouldSelfUpdate = options.yes === true;
+    if (!shouldSelfUpdate) {
+      const smartinteractInstance = new plugins.smartinteract.SmartInteract();
+      const answer = await smartinteractInstance.askQuestion({
+        type: 'confirm',
+        name: 'confirmSelfUpdate',
+        message: 'Do you want to update gtools itself first?',
+        default: true,
+      });
+      shouldSelfUpdate = answer.value === true;
+    }
+
+    if (shouldSelfUpdate) {
+      const success = await pmUtil.executeUpdate(selfPm, '@git.zone/tools');
+      if (success) {
+        console.log('\ngtools has been updated. Please re-run "gtools update" to check remaining packages.');
+        process.exit(0);
+      } else {
+        console.log('\ngtools self-update failed. Continuing with current version...\n');
+      }
+    }
+  } else {
+    console.log(`  @git.zone/tools  ${selfVersion}  ✓ Up to date\n`);
+  }
 
   // Collect all installed @git.zone packages from all package managers
   const allPackages: IPackageUpdateInfo[] = [];
 
-  for (const pm of availablePMs) {
+  for (const pmInfo of detectedPMs) {
-    const installed = await pmUtil.getInstalledPackages(pm);
+    const installed = await pmUtil.getInstalledPackages(pmInfo.name);
     for (const pkg of installed) {
       // Only include packages from our predefined list
       if (GITZONE_PACKAGES.includes(pkg.name)) {
@@ -50,7 +138,7 @@ export const run = async (options: IUpdateOptions = {}): Promise<void> => {
           name: pkg.name,
           currentVersion: pkg.version,
           latestVersion: latestVersion || 'unknown',
-          packageManager: pm,
+          packageManager: pmInfo.name,
           needsUpdate: latestVersion ? pmUtil.isNewerVersion(pkg.version, latestVersion) : false,
         });
       }

ts/tools.cli.ts

@@ -1,5 +1,6 @@
 import * as plugins from './tools.plugins.js';
 import * as modUpdate from './mod_update/index.js';
+import { commitinfo } from './00_commitinfo_data.js';
 
 export const run = async () => {
   const toolsCli = new plugins.smartcli.Smartcli();
@@ -9,15 +10,17 @@ export const run = async () => {
     console.log('Commands:');
     console.log('  update            Check and update globally installed @git.zone packages');
     console.log('  update -y         Update without confirmation prompt');
+    console.log('  update --verbose  Show detection diagnostics');
     console.log('');
     console.log('Use "gtools <command> --help" for more information about a command.');
   });
 
   toolsCli.addCommand('update').subscribe(async (argvArg) => {
     const yesFlag = argvArg.y === true || argvArg.yes === true;
-    await modUpdate.run({ yes: yesFlag });
+    const verboseFlag = argvArg.v === true || argvArg.verbose === true;
+    await modUpdate.run({ yes: yesFlag, verbose: verboseFlag });
   });
 
-  toolsCli.addVersion('3.0.0');
+  toolsCli.addVersion(commitinfo.version);
   toolsCli.startParse();
 };