feat(package): refresh package metadata, update dependency versions, and document CLI update and install workflows

2026-03-24 18:12:02 +00:00
parent 8507e54a56
commit 393410a4b5
8 changed files with 1261 additions and 1290 deletions
--- a/readme.md
+++ b/readme.md
@@ -1,6 +1,6 @@
 # @git.zone/tools 🛠️

-A CLI tool placeholder for development utilities.
+A powerful CLI utility for managing your `@git.zone` development toolchain. Scan, update, and install all official `@git.zone` packages across multiple package managers — from a single command.

 ## Issue Reporting and Security

@@ -8,21 +8,138 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community

 ## Installation 📦

+Install globally with your preferred package manager:
+
 ```bash
+# npm
 npm install -g @git.zone/tools
+
+# pnpm (recommended)
+pnpm add -g @git.zone/tools
+
+# yarn
+yarn global add @git.zone/tools
 ```

+This gives you the `gtools` binary.
+
 ## Usage 🚀

+### Overview
+
 ```bash
-gtools
+gtools              # Show available commands
+gtools update       # Check & update installed @git.zone packages
+gtools install      # Interactively install missing @git.zone packages
 ```

-Currently a placeholder CLI with no commands implemented yet.
+### `gtools update` — Keep Everything Fresh ♻️
+
+Scans all available package managers (npm, pnpm, yarn) on your system, detects globally installed `@git.zone` packages, and checks them against the latest published versions.
+
+```bash
+gtools update             # Interactive — prompts before updating
+gtools update -y          # Auto-approve all updates (great for CI)
+gtools update --verbose   # Show package manager detection diagnostics
+```
+
+**What it does:**
+
+1. 🔍 Detects which package managers are available on your system
+2. 📊 Shows a version table for each detected package manager
+3. 🔄 Checks for a **self-update** of `gtools` itself first
+4. 📋 Lists all globally installed `@git.zone` packages with current vs. latest versions
+5. 🚀 Prompts you to update any outdated packages (or auto-updates with `-y`)
+
+**Example output:**
+
+```
+Package managers:
+
+  Name     Current     Latest      Status
+  ──────────────────────────────────────────────
+  pnpm     10.28.2     10.28.2     ✓ Up to date
+
+Installed @git.zone packages:
+
+  Package                      Current     Latest      PM      Status
+  ─────────────────────────────────────────────────────────────────────
+  @git.zone/cli                1.10.0      1.10.0      pnpm    ✓ Up to date
+  @git.zone/tsbuild            4.3.0       4.3.0       pnpm    ✓ Up to date
+  @git.zone/tstest             3.5.1       3.5.1       pnpm    ✓ Up to date
+
+All packages are up to date!
+```
+
+### `gtools install` — Bootstrap Your Toolchain 🧰
+
+Detects which official `@git.zone` packages are **not** installed and lets you pick which ones to add.
+
+```bash
+gtools install             # Interactive selection
+gtools install -y          # Install all missing packages automatically
+gtools install --verbose   # Show detection diagnostics
+```
+
+**Managed packages:**
+
+| Package | Description |
+|---------|-------------|
+| `@git.zone/cli` | The main gitzone CLI (`gitzone` command) |
+| `@git.zone/tsbuild` | TypeScript compiler wrapper |
+| `@git.zone/tstest` | Test runner for TypeScript projects |
+| `@git.zone/tsbundle` | Bundle TypeScript for browsers |
+| `@git.zone/tswatch` | File watcher with live reload |
+| `@git.zone/tspublish` | Publish packages to npm registries |
+| `@git.zone/tsdoc` | Documentation generator |
+| `@git.zone/tsdocker` | Docker integration for TS projects |
+| `@git.zone/tsview` | Component viewer |
+| `@git.zone/tsrust` | Rust cross-compilation support |
+
+### Smart Package Manager Detection 🔎
+
+`gtools` doesn't assume which package manager you use. It probes for `npm`, `pnpm`, and `yarn` using multiple detection strategies:
+
+1. **`which` command** — checks the system PATH
+2. **`--version` fallback** — directly invokes the PM if `which` fails
+
+When installing, it recommends the package manager that already has the most `@git.zone` packages, so your toolchain stays consistent.
+
+## Programmatic API 🔧
+
+You can also use `@git.zone/tools` as a library:
+
+```typescript
+import { runCli } from '@git.zone/tools';
+
+// Launch the CLI programmatically
+await runCli();
+```
+
+Or use the `PackageManagerUtil` class directly for custom tooling:
+
+```typescript
+import { PackageManagerUtil } from '@git.zone/tools/dist_ts/mod_update/classes.packagemanager.js';
+
+const pmUtil = new PackageManagerUtil();
+
+// Check if pnpm is available
+const pnpmInfo = await pmUtil.detectPackageManager('pnpm');
+console.log(pnpmInfo.available); // true/false
+
+// Get globally installed @git.zone packages
+const packages = await pmUtil.getInstalledPackages('pnpm');
+
+// Get latest version from registry (checks private registry first, then npm)
+const latest = await pmUtil.getLatestVersion('@git.zone/tsbuild');
+
+// Compare versions
+pmUtil.isNewerVersion('1.0.0', '2.0.0'); // true
+```

 ## License and Legal Information

-This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.

 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.