v2.19.5

.smartconfig.json

@@ -9,11 +9,11 @@
     "schemaVersion": 2,
     "projectType": "npm",
     "module": {
-      "githost": "gitlab.com",
+      "githost": "code.foss.global",
-      "gitscope": "gitzone/private",
+      "gitscope": "git.zone",
-      "gitrepo": "gitzone",
+      "gitrepo": "cli",
       "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.",
-      "npmPackagename": "@gitzone_private/gitzone",
+      "npmPackagename": "@git.zone/cli",
       "license": "MIT",
       "keywords": [
         "CLI",

changelog.md

@@ -1,7 +1,51 @@
 # Changelog
 
-## Pending
+## 2026-06-03 - 2.19.5
 
+### Fixes
+
+- improve changelog release handling and TypeScript compatibility (cli)
+  - Avoid mutating changelog files when only reading pending entries
+  - Remove the consumed Pending section when moving entries to a versioned release
+  - Use async project metadata creation and safer unknown error handling for updated dependencies
+  - Add changelog helper tests for missing, consumed, and recreated Pending sections
+- update project metadata for code.foss.global repository (metadata)
+  - Updated repository, issue tracker, and homepage URLs to code.foss.global/git.zone/cli
+  - Aligned smartconfig module metadata with the @git.zone/cli package and git.zone scope
+
+## 2026-05-24 - 2.19.4
+
+### Fixes
+
+- refresh dependency resolution for global installs to pick up the fixed `@push.rocks/smartgit` release
+  - Refreshes the lockfile so `@git.zone/tsdoc` resolves `@push.rocks/smartgit@3.3.3`.
+
+## 2026-05-24 - 2.19.3
+
+### Fixes
+
+- handle empty commit analysis as a clean no-op
+  - Uses `@git.zone/tsdoc`'s explicit `NoChangesError` signal.
+  - Makes `gitzone commit` and `gitzone commit recommend --json` return cleanly when no uncommitted changes exist.
+
+## 2026-05-23 - 2.19.2
+
+### Fixes
+
+- repair `gitzone tools update` for pnpm 11 global installs
+  - Detects and migrates legacy pnpm global roots such as `PNPM_HOME/global/5`.
+  - Runs global pnpm maintenance with project package-manager switching disabled.
+  - Refreshes pnpm v10 and v11 command shims before deleting stale managed global roots.
+
+## 2026-05-14 - 2.19.1
+
+### Fixes
+
+- migrate legacy release arrays during config fixes and validate release config shape (config)
+  - Automatically converts legacy release registry arrays into release.targets.npm.registries during smartconfig migration and config fix runs.
+  - Re-runs doctor checks after applying known migrations so resolved issues do not require the external fixer.
+  - Reports an explicit validation error when release config is not an object.
+  - Updates config fix prompts and help text to use generic configuration repair wording.
 
 ## 2026-05-13 - 2.19.0
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@git.zone/cli",
   "private": false,
-  "version": "2.19.0",
+  "version": "2.19.5",
   "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",
@@ -30,7 +30,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://gitlab.com/gitzone/private/gitzone.git"
+    "url": "https://code.foss.global/git.zone/cli.git"
   },
   "keywords": [
     "CLI",
@@ -53,21 +53,21 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "bugs": {
-    "url": "https://gitlab.com/gitzone/private/gitzone/issues"
+    "url": "https://code.foss.global/git.zone/cli/issues"
   },
-  "homepage": "https://gitlab.com/gitzone/private/gitzone#readme",
+  "homepage": "https://code.foss.global/git.zone/cli#README",
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.3.0",
+    "@git.zone/tsbuild": "^4.4.2",
     "@git.zone/tsrun": "^2.0.1",
-    "@git.zone/tstest": "^3.3.2",
+    "@git.zone/tstest": "^3.6.6",
-    "@types/node": "^25.4.0"
+    "@types/node": "^25.9.1"
   },
   "dependencies": {
-    "@git.zone/tsdoc": "^2.0.0",
+    "@git.zone/tsdoc": "^2.0.6",
     "@git.zone/tspublish": "^1.11.2",
-    "@push.rocks/commitinfo": "^1.0.12",
+    "@push.rocks/commitinfo": "^1.0.13",
     "@push.rocks/early": "^4.0.4",
-    "@push.rocks/projectinfo": "^5.0.2",
+    "@push.rocks/projectinfo": "^5.1.0",
     "@push.rocks/smartcli": "^4.0.20",
     "@push.rocks/smartconfig": "^6.0.1",
     "@push.rocks/smartdelay": "^3.0.5",
@@ -86,10 +86,10 @@
     "@push.rocks/smartopen": "^2.0.0",
     "@push.rocks/smartpath": "^6.0.0",
     "@push.rocks/smartpromise": "^4.2.3",
-    "@push.rocks/smartscaf": "^4.0.21",
+    "@push.rocks/smartscaf": "^4.0.22",
     "@push.rocks/smartshell": "^3.5.0",
     "@push.rocks/smartunique": "^3.0.9",
-    "@push.rocks/smartupdate": "^2.0.6",
+    "@push.rocks/smartupdate": "^2.0.7",
     "prettier": "^3.8.1"
   },
   "files": [

readme.hints.md

@@ -193,12 +193,22 @@ gitzone format
 # Read-only JSON plan
 gitzone format plan --json
 
+# CI-friendly check, exits non-zero when changes or validator errors remain
+gitzone format check
+
 # Dry run to preview changes
 gitzone format --dry-run
 
+# Limit formatter modules
+gitzone format --only prettier,packagejson
+gitzone format --skip license
+
 # Non-interactive apply
 gitzone format --write --yes
 
+# Deterministic format first, opencode for remaining issues
+gitzone format fix
+
 # Plan only (no execution)
 gitzone format --plan-only
 

readme.md

@@ -309,15 +309,26 @@ gitzone format
 # Emit a machine-readable plan
 gitzone format plan --json
 
+# Fail when formatting changes or validator errors remain
+gitzone format check
+
+# Run a subset of formatters
+gitzone format --only prettier,packagejson
+
 # Apply changes
 gitzone format --write
 
 # Apply without prompt
 gitzone format --write --yes
+
+# Apply deterministic fixes, then use opencode for remaining issues
+gitzone format fix
 ```
 
 Formatters include cleanup, smartconfig normalization, dependency license checks, package metadata normalization, template updates, `.gitignore`, TypeScript config, Prettier, README existence checks, and configured copy operations.
 
+`gitzone format fix` intentionally lives outside the default format path. Normal format runs stay deterministic; the fix command uses opencode only after deterministic formatters have done what they can.
+
 ## Development Services
 
 `gitzone services` manages local Docker-backed services for development projects.

test.changelog.node.ts

@@ -0,0 +1,79 @@
+import { rm, writeFile, readFile, mkdtemp } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+
+import {
+  appendPendingChangelogEntry,
+  movePendingToVersion,
+  readPendingChangelog,
+} from './ts/helpers.changelog.js';
+
+const withChangelogFile = async (
+  initialContent: string,
+  testFunction: (filePath: string) => Promise<void>,
+) => {
+  const testDir = await mkdtemp(join(tmpdir(), 'gitzone-changelog-'));
+  const changelogPath = join(testDir, 'changelog.md');
+  try {
+    await writeFile(changelogPath, initialContent);
+    await testFunction(changelogPath);
+  } finally {
+    await rm(testDir, { recursive: true, force: true });
+  }
+};
+
+tap.test('readPendingChangelog should not create a missing Pending section', async () => {
+  await withChangelogFile('# Changelog\n\n## 2026-01-01 - 1.0.0\n\n### Fixes\n\n- existing\n', async (filePath) => {
+    const pending = await readPendingChangelog(filePath, 'Pending');
+    const changelogContent = await readFile(filePath, 'utf8');
+
+    expect(pending.isEmpty).toBeTrue();
+    expect(pending.block).toEqual('');
+    expect(changelogContent).not.toInclude('## Pending');
+  });
+});
+
+tap.test('movePendingToVersion should fail when Pending is missing', async () => {
+  await withChangelogFile('# Changelog\n\n## 2026-01-01 - 1.0.0\n\n### Fixes\n\n- existing\n', async (filePath) => {
+    let errorMessage = '';
+    try {
+      await movePendingToVersion(filePath, 'Pending', '## {{date}} - {{version}}', '1.0.1', '2026-01-02');
+    } catch (error) {
+      errorMessage = error instanceof Error ? error.message : String(error);
+    }
+
+    expect(errorMessage).toEqual('No pending changelog entries. Nothing to release.');
+
+    const changelogContent = await readFile(filePath, 'utf8');
+    expect(changelogContent).not.toInclude('## Pending');
+  });
+});
+
+tap.test('movePendingToVersion should remove the consumed Pending section', async () => {
+  await withChangelogFile('# Changelog\n\n## Pending\n\n### Fixes\n\n- pending fix\n\n## 2026-01-01 - 1.0.0\n\n### Fixes\n\n- existing\n', async (filePath) => {
+    await movePendingToVersion(filePath, 'Pending', '## {{date}} - {{version}}', '1.0.1', '2026-01-02');
+
+    const changelogContent = await readFile(filePath, 'utf8');
+    expect(changelogContent).not.toInclude('## Pending');
+    expect(changelogContent).toInclude('## 2026-01-02 - 1.0.1\n\n### Fixes\n\n- pending fix');
+    expect(changelogContent).toInclude('## 2026-01-01 - 1.0.0\n\n### Fixes\n\n- existing');
+  });
+});
+
+tap.test('appendPendingChangelogEntry should recreate Pending when needed', async () => {
+  await withChangelogFile('# Changelog\n\n## 2026-01-01 - 1.0.0\n\n### Fixes\n\n- existing\n', async (filePath) => {
+    await appendPendingChangelogEntry(filePath, 'Pending', {
+      type: 'fix',
+      scope: 'changelog',
+      message: 'record pending changes',
+    });
+
+    const changelogContent = await readFile(filePath, 'utf8');
+    expect(changelogContent).toInclude('## Pending\n\n### Fixes\n\n- record pending changes (changelog)');
+    expect(changelogContent).toInclude('## 2026-01-01 - 1.0.0');
+  });
+});
+
+export default tap.start();

ts/00_commitinfo_data.ts

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

ts/classes.gitzoneconfig.ts

@@ -35,7 +35,7 @@ export class GitzoneConfig {
     return gitzoneConfig;
   }
 
-  public data: IGitzoneConfigData;
+  public data!: IGitzoneConfigData;
 
   public async readConfigFromCwd() {
     const smartconfigInstance = new plugins.smartconfig.Smartconfig(paths.cwd);

ts/gitzone.cli.ts

@@ -1,17 +1,111 @@
 import * as plugins from "./plugins.js";
 import * as paths from "./paths.js";
-import { GitzoneConfig } from "./classes.gitzoneconfig.js";
+import {
-import { getRawCliMode } from "./helpers.climode.js";
+  getProcessUserArgv,
+  getRawCliMode,
+  parseCliArgv,
+} from "./helpers.climode.js";
 import { commitinfo } from "./00_commitinfo_data.js";
 
-const gitzoneSmartcli = new plugins.smartcli.Smartcli();
+const runParsedCommand = async (argvArg: any): Promise<void> => {
+  const command = argvArg._?.[0];
+
+  switch (command) {
+    case undefined:
+    case "help": {
+      const modStandard = await import("./mod_standard/index.js");
+      await modStandard.run(argvArg);
+      break;
+    }
+    case "commit": {
+      const modCommit = await import("./mod_commit/index.js");
+      await modCommit.run(argvArg);
+      break;
+    }
+    case "release": {
+      const modRelease = await import("./mod_release/index.js");
+      await modRelease.run(argvArg);
+      break;
+    }
+    case "deprecate": {
+      const modDeprecate = await import("./mod_deprecate/index.js");
+      await modDeprecate.run();
+      break;
+    }
+    case "docker": {
+      const modDocker = await import("./mod_docker/index.js");
+      await modDocker.run(argvArg);
+      break;
+    }
+    case "format": {
+      const modFormat = await import("./mod_format/index.js");
+      await modFormat.run({
+        ...argvArg,
+        write: argvArg.write || argvArg.w,
+        dryRun: argvArg["dry-run"],
+        yes: argvArg.yes || argvArg.y,
+        planOnly: argvArg["plan-only"] || argvArg.planOnly,
+        savePlan: argvArg["save-plan"] || argvArg.savePlan,
+        fromPlan: argvArg["from-plan"] || argvArg.fromPlan,
+        detailed: argvArg.detailed,
+        interactive: argvArg.interactive !== false,
+        verbose: argvArg.verbose,
+        diff: argvArg.diff,
+      });
+      break;
+    }
+    case "meta": {
+      const modMeta = await import("./mod_meta/index.js");
+      await modMeta.run(argvArg);
+      break;
+    }
+    case "open": {
+      const modOpen = await import("./mod_open/index.js");
+      await modOpen.run(argvArg);
+      break;
+    }
+    case "template": {
+      const modTemplate = await import("./mod_template/index.js");
+      await modTemplate.run(argvArg);
+      break;
+    }
+    case "start": {
+      const modStart = await import("./mod_start/index.js");
+      await modStart.run(argvArg);
+      break;
+    }
+    case "helpers": {
+      const modHelpers = await import("./mod_helpers/index.js");
+      await modHelpers.run(argvArg);
+      break;
+    }
+    case "tools": {
+      const modTools = await import("./mod_tools/index.js");
+      await modTools.run(argvArg);
+      break;
+    }
+    case "config": {
+      const modConfig = await import("./mod_config/index.js");
+      await modConfig.run(argvArg);
+      break;
+    }
+    case "services": {
+      const modServices = await import("./mod_services/index.js");
+      await modServices.run(argvArg);
+      break;
+    }
+    default: {
+      const modStandard = await import("./mod_standard/index.js");
+      await modStandard.run(argvArg);
+    }
+  }
+};
 
 export let run = async () => {
-  const done = plugins.smartpromise.defer();
   const rawCliMode = await getRawCliMode();
 
   // get packageInfo
-  const projectInfo = new plugins.projectinfo.ProjectInfo(paths.packageDir);
+  const projectInfo = await plugins.projectinfo.ProjectInfo.create(paths.packageDir);
   const projectInfoVersion = (projectInfo.npm as any)?.version;
   const packageVersion =
     typeof projectInfoVersion === "string" && projectInfoVersion.length > 0
@@ -34,144 +128,10 @@ export let run = async () => {
   if (rawCliMode.output === "human") {
     console.log("---------------------------------------------");
   }
-  gitzoneSmartcli.addVersion(packageVersion);
+  const argvArg = parseCliArgv(getProcessUserArgv());
-
+  if (argvArg.v || argvArg.version) {
-  // ======> Standard task <======
+    console.log(packageVersion);
-
+    return;
-  /**
+  }
-   * standard task
+  await runParsedCommand(argvArg);
-   */
-  gitzoneSmartcli.standardCommand().subscribe(async (argvArg) => {
-    const modStandard = await import("./mod_standard/index.js");
-    await modStandard.run(argvArg);
-  });
-
-  gitzoneSmartcli.addCommand("help").subscribe(async (argvArg) => {
-    const modStandard = await import("./mod_standard/index.js");
-    await modStandard.run(argvArg);
-  });
-
-  // ======> Specific tasks <======
-
-  /**
-   * commit something
-   */
-  gitzoneSmartcli.addCommand("commit").subscribe(async (argvArg) => {
-    const modCommit = await import("./mod_commit/index.js");
-    await modCommit.run(argvArg);
-  });
-
-  /**
-   * create a release from pending changelog entries
-   */
-  gitzoneSmartcli.addCommand("release").subscribe(async (argvArg) => {
-    const modRelease = await import("./mod_release/index.js");
-    await modRelease.run(argvArg);
-  });
-
-  /**
-   * deprecate a package on npm
-   */
-  gitzoneSmartcli.addCommand("deprecate").subscribe(async (argvArg) => {
-    const modDeprecate = await import("./mod_deprecate/index.js");
-    await modDeprecate.run();
-  });
-
-  /**
-   * docker
-   */
-  gitzoneSmartcli.addCommand("docker").subscribe(async (argvArg) => {
-    const modDocker = await import("./mod_docker/index.js");
-    await modDocker.run(argvArg);
-  });
-
-  /**
-   * Update all files that comply with the gitzone standard
-   */
-  gitzoneSmartcli.addCommand("format").subscribe(async (argvArg) => {
-    const config = GitzoneConfig.fromCwd();
-    const modFormat = await import("./mod_format/index.js");
-
-    // Handle format with options
-    // Default is dry-mode, use --write/-w to apply changes
-    await modFormat.run({
-      ...argvArg,
-      write: argvArg.write || argvArg.w,
-      dryRun: argvArg["dry-run"],
-      yes: argvArg.yes,
-      planOnly: argvArg["plan-only"],
-      savePlan: argvArg["save-plan"],
-      fromPlan: argvArg["from-plan"],
-      detailed: argvArg.detailed,
-      interactive: argvArg.interactive !== false,
-      verbose: argvArg.verbose,
-      diff: argvArg.diff,
-    });
-  });
-
-  /**
-   * run meta commands
-   */
-  gitzoneSmartcli.addCommand("meta").subscribe(async (argvArg) => {
-    const config = GitzoneConfig.fromCwd();
-    const modMeta = await import("./mod_meta/index.js");
-    modMeta.run(argvArg);
-  });
-
-  /**
-   * open assets
-   */
-  gitzoneSmartcli.addCommand("open").subscribe(async (argvArg) => {
-    const modOpen = await import("./mod_open/index.js");
-    modOpen.run(argvArg);
-  });
-
-  /**
-   * add a readme to a project
-   */
-  gitzoneSmartcli.addCommand("template").subscribe(async (argvArg) => {
-    const modTemplate = await import("./mod_template/index.js");
-    modTemplate.run(argvArg);
-  });
-
-  /**
-   * start working on a project
-   */
-  gitzoneSmartcli.addCommand("start").subscribe(async (argvArg) => {
-    const modTemplate = await import("./mod_start/index.js");
-    modTemplate.run(argvArg);
-  });
-
-  gitzoneSmartcli.addCommand("helpers").subscribe(async (argvArg) => {
-    const modHelpers = await import("./mod_helpers/index.js");
-    modHelpers.run(argvArg);
-  });
-
-  /**
-   * manage the global @git.zone toolchain
-   */
-  gitzoneSmartcli.addCommand("tools").subscribe(async (argvArg) => {
-    const modTools = await import("./mod_tools/index.js");
-    await modTools.run(argvArg);
-  });
-
-  /**
-   * manage release configuration
-   */
-  gitzoneSmartcli.addCommand("config").subscribe(async (argvArg) => {
-    const modConfig = await import("./mod_config/index.js");
-    await modConfig.run(argvArg);
-  });
-
-  /**
-   * manage development services (MongoDB, S3/MinIO)
-   */
-  gitzoneSmartcli.addCommand("services").subscribe(async (argvArg) => {
-    const modServices = await import("./mod_services/index.js");
-    await modServices.run(argvArg);
-  });
-
-  // start parsing of the cli
-  gitzoneSmartcli.startParse();
-  return await done.promise;
 };

ts/helpers.changelog.ts

@@ -19,6 +19,12 @@ export interface IPendingChangelog {
   isEmpty: boolean;
 }
 
+interface IChangelogSection {
+  start: number;
+  bodyStart: number;
+  end: number;
+}
+
 const bucketForCommitType = (commitType: string): TChangelogBucket => {
   switch (commitType) {
     case "BREAKING CHANGE":
@@ -48,7 +54,7 @@ const writeChangelog = async (filePath: string, content: string): Promise<void>
 const findPendingSection = (
   content: string,
   sectionName: string,
-): { start: number; bodyStart: number; end: number } | null => {
+): IChangelogSection | null => {
   const headingRegex = new RegExp(`^##\\s+${sectionName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*$`, "m");
   const match = headingRegex.exec(content);
   if (!match || match.index === undefined) {
@@ -123,9 +129,11 @@ export const readPendingChangelog = async (
   filePath: string,
   sectionName = "Pending",
 ): Promise<IPendingChangelog> => {
-  const content = await ensurePendingSection(filePath, sectionName);
+  const content = await readChangelog(filePath);
-  const pendingSection = findPendingSection(content, sectionName)!;
+  const pendingSection = findPendingSection(content, sectionName);
-  const block = content.slice(pendingSection.bodyStart, pendingSection.end).trim();
+  const block = pendingSection
+    ? content.slice(pendingSection.bodyStart, pendingSection.end).trim()
+    : "";
   return {
     block,
     isEmpty: block.length === 0,
@@ -149,8 +157,11 @@ export const movePendingToVersion = async (
   version: string,
   dateString: string,
 ): Promise<void> => {
-  let content = await ensurePendingSection(filePath, sectionName);
+  let content = await readChangelog(filePath);
-  const pendingSection = findPendingSection(content, sectionName)!;
+  const pendingSection = findPendingSection(content, sectionName);
+  if (!pendingSection) {
+    throw new Error("No pending changelog entries. Nothing to release.");
+  }
   const pendingBlock = content.slice(pendingSection.bodyStart, pendingSection.end).trim();
   if (!pendingBlock) {
     throw new Error("No pending changelog entries. Nothing to release.");
@@ -159,7 +170,10 @@ export const movePendingToVersion = async (
   const renderedHeading = versionHeading
     .replaceAll("{{version}}", version)
     .replaceAll("{{date}}", dateString);
-  const nextContent = content.slice(pendingSection.end).replace(/^\n+/, "");
+  const beforePending = content.slice(0, pendingSection.start).trimEnd();
-  content = `${content.slice(0, pendingSection.bodyStart)}\n\n${renderedHeading}\n\n${pendingBlock}\n\n${nextContent}`;
+  const afterPending = content.slice(pendingSection.end).replace(/^\n+/, "").trimEnd();
+  content = [beforePending, renderedHeading, pendingBlock, afterPending]
+    .filter((block) => block.length > 0)
+    .join("\n\n");
   await writeChangelog(filePath, content);
 };

ts/helpers.climode.ts

@@ -88,6 +88,41 @@ const parseRawArgv = (argv: string[]): TArgSource => {
   return parsedArgv;
 };
 
+export const parseCliArgv = parseRawArgv;
+
+export const getProcessUserArgv = (): string[] => {
+  const rawArgv = process.argv;
+  const argv0Base = (rawArgv[0] || "").split(/[\\/]/).pop()?.toLowerCase();
+  const runtimeNames = new Set([
+    "node",
+    "node.exe",
+    "nodejs",
+    "nodejs.exe",
+    "bun",
+    "bun.exe",
+    "deno",
+    "deno.exe",
+    "tsx",
+    "tsx.exe",
+    "ts-node",
+    "ts-node.exe",
+  ]);
+
+  if (!runtimeNames.has(argv0Base || "")) {
+    return rawArgv.slice();
+  }
+
+  const firstUserArg = rawArgv[1] || "";
+  const firstUserArgLooksLikeScript =
+    firstUserArg.includes("/") ||
+    firstUserArg.endsWith(".js") ||
+    firstUserArg.endsWith(".ts") ||
+    firstUserArg.endsWith(".mjs") ||
+    firstUserArg.endsWith(".cjs");
+
+  return rawArgv.slice(firstUserArgLooksLikeScript ? 2 : 1);
+};
+
 const normalizeOutputMode = (value: unknown): TCliOutputMode | undefined => {
   if (value === "human" || value === "plain" || value === "json") {
     return value;
@@ -171,7 +206,7 @@ export const getCliMode = async (
 
 export const getRawCliMode = async (): Promise<ICliMode> => {
   const cliConfig = await getCliModeConfig();
-  const rawArgv = parseRawArgv(process.argv.slice(2));
+  const rawArgv = parseRawArgv(getProcessUserArgv());
   return resolveCliMode(rawArgv, cliConfig);
 };
 

ts/helpers.smartconfigmigrations.ts

@@ -19,6 +19,38 @@ const ensureObject = (parent: Record<string, any>, key: string): Record<string,
   return parent[key];
 };
 
+const normalizeRegistryList = (registries: unknown[]): string[] => {
+  const result: string[] = [];
+  for (const registry of registries) {
+    if (typeof registry !== "string" || !registry.trim()) {
+      continue;
+    }
+    const normalizedRegistry = normalizeRegistryUrl(registry);
+    if (!result.includes(normalizedRegistry)) {
+      result.push(normalizedRegistry);
+    }
+  }
+  return result;
+};
+
+const migrateLegacyReleaseArray = (smartconfigJson: Record<string, any>): boolean => {
+  const cliConfig = ensureObject(smartconfigJson, CLI_NAMESPACE);
+  if (!Array.isArray(cliConfig.release)) {
+    return false;
+  }
+
+  const registries = normalizeRegistryList(cliConfig.release);
+  cliConfig.release = {
+    targets: {
+      npm: {
+        enabled: registries.length > 0,
+        registries,
+      },
+    },
+  };
+  return true;
+};
+
 const migrateNamespaceKeys = (smartconfigJson: Record<string, any>): boolean => {
   let migrated = false;
   const migrations = [
@@ -50,9 +82,9 @@ const migrateNamespaceKeys = (smartconfigJson: Record<string, any>): boolean =>
 
 const migrateToV2 = (smartconfigJson: Record<string, any>): boolean => {
   const cliConfig = ensureObject(smartconfigJson, CLI_NAMESPACE);
+  let migrated = migrateLegacyReleaseArray(smartconfigJson);
   const releaseConfig = ensureObject(cliConfig, "release");
 
-  let migrated = false;
   const targets = ensureObject(releaseConfig, "targets");
   const shipzoneConfig = smartconfigJson["@ship.zone/szci"];
 
@@ -192,6 +224,10 @@ export const migrateSmartconfigData = (
   const fromVersion = typeof cliConfig.schemaVersion === "number" ? cliConfig.schemaVersion : 1;
   let currentVersion = fromVersion;
 
+  if (targetVersion >= 2) {
+    migrated = migrateLegacyReleaseArray(smartconfigJson) || migrated;
+  }
+
   if (currentVersion < 2 && targetVersion >= 2) {
     migrated = migrateToV2(smartconfigJson) || migrated;
     currentVersion = 2;

ts/mod_commit/index.ts

@@ -9,6 +9,13 @@ import { getCliMode, printJson, runWithSuppressedOutput } from "../helpers.climo
 import { appendPendingChangelogEntry } from "../helpers.changelog.js";
 import { resolveCommitWorkflow, type IResolvedCommitWorkflow } from "../helpers.workflow.js";
 
+const isNoChangesError = (error: unknown): boolean => {
+  return (
+    error instanceof plugins.tsdoc.NoChangesError ||
+    (error instanceof Error && error.name === "NoChangesError")
+  );
+};
+
 export const run = async (argvArg: any) => {
   const mode = await getCliMode(argvArg);
   const subcommand = argvArg._?.[1];
@@ -65,7 +72,15 @@ export const run = async (argvArg: any) => {
         await runCommandStep(smartshellInstance, "Running build", workflow.buildCommand);
         break;
       case "analyze":
-        nextCommitObject = await runAnalyzeStep();
+        try {
+          nextCommitObject = await runAnalyzeStep();
+        } catch (error) {
+          if (isNoChangesError(error)) {
+            logger.log("info", "No uncommitted changes found. Nothing to commit.");
+            return;
+          }
+          throw error;
+        }
         answerBucket = await buildAnswerBucket(nextCommitObject, workflow, mode, argvArg);
         break;
       case "changelog":
@@ -284,9 +299,22 @@ async function handleRecommend(mode: ICliMode): Promise<void> {
     }
   };
 
-  const recommendation = mode.json
+  let recommendation: any;
-    ? await runWithSuppressedOutput(recommendationBuilder)
+  try {
-    : await recommendationBuilder();
+    recommendation = mode.json
+      ? await runWithSuppressedOutput(recommendationBuilder)
+      : await recommendationBuilder();
+  } catch (error) {
+    if (isNoChangesError(error)) {
+      if (mode.json) {
+        printJson({ ok: true, noChanges: true });
+      } else {
+        logger.log("info", "No uncommitted changes found.");
+      }
+      return;
+    }
+    throw error;
+  }
 
   if (mode.json) {
     printJson(recommendation);

ts/mod_commit/mod.helpers.ts

@@ -27,7 +27,8 @@ export async function detectCurrentBranch(): Promise<string> {
     logger.log('info', `Detected current branch: ${branchName}`);
     return branchName;
   } catch (error) {
-    logger.log('warn', `Failed to detect branch: ${error.message}, falling back to "master"`);
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    logger.log('warn', `Failed to detect branch: ${errorMessage}, falling back to "master"`);
     return 'master';
   }
 }
@@ -225,6 +226,7 @@ export async function bumpProjectVersion(
 
     return newVersion;
   } catch (error) {
-    throw new Error(`Failed to bump project version: ${error.message}`);
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to bump project version: ${errorMessage}`);
   }
 }

ts/mod_config/index.ts

@@ -168,7 +168,7 @@ async function handleInteractiveMenu(): Promise<void> {
       { name: "Configure release workflow", value: "release" },
       { name: "Configure services", value: "services" },
       { name: "Validate configuration (doctor)", value: "doctor" },
-      { name: "Fix configuration with opencode", value: "fix" },
+      { name: "Fix configuration", value: "fix" },
       { name: "Add an npm target registry", value: "add" },
       { name: "Remove an npm target registry", value: "remove" },
       { name: "Clear npm target registries", value: "clear" },
@@ -939,8 +939,8 @@ async function handleFix(argvArg: any, mode: ICliMode): Promise<void> {
     return;
   }
 
-  const findings = await collectDoctorFindings();
+  let findings = await collectDoctorFindings();
-  const counts = countDoctorFindings(findings);
+  let counts = countDoctorFindings(findings);
   const extraInstructions = (argvArg._?.slice(2).join(" ") || "").trim();
   const force = Boolean(argvArg.force);
 
@@ -954,10 +954,10 @@ async function handleFix(argvArg: any, mode: ICliMode): Promise<void> {
 
   if (!mode.yes) {
     if (!mode.interactive) {
-      throw new Error("Config fix requires an interactive terminal or `-y` to run opencode non-interactively.");
+      throw new Error("Config fix requires an interactive terminal or `-y` to run non-interactively.");
     }
     const confirmed = await plugins.smartinteract.SmartInteract.getCliConfirmation(
-      `Run opencode to fix .smartconfig.json? (${counts.error} error, ${counts.warn} warning)`,
+      `Run configuration fixes for .smartconfig.json? (${counts.error} error, ${counts.warn} warning)`,
       true,
     );
     if (!confirmed) {
@@ -966,6 +966,16 @@ async function handleFix(argvArg: any, mode: ICliMode): Promise<void> {
     }
   }
 
+  const appliedKnownFixes = await applyKnownConfigFixes(mode);
+  if (appliedKnownFixes) {
+    findings = await collectDoctorFindings();
+    counts = countDoctorFindings(findings);
+    if (counts.error === 0 && counts.warn === 0 && !extraInstructions && !force) {
+      printDoctorResult(findings, mode);
+      return;
+    }
+  }
+
   const opencodeArgs = [
     "run",
     "--title",
@@ -1004,6 +1014,33 @@ async function handleFix(argvArg: any, mode: ICliMode): Promise<void> {
   printDoctorResult(finalFindings, mode);
 }
 
+async function applyKnownConfigFixes(mode: ICliMode): Promise<boolean> {
+  const smartconfigPath = getSmartconfigPath();
+  if (!(await plugins.smartfs.file(smartconfigPath).exists())) {
+    return false;
+  }
+
+  let smartconfigData: Record<string, any>;
+  try {
+    smartconfigData = await readSmartconfigFile();
+  } catch {
+    return false;
+  }
+
+  const result = migrateSmartconfigData(smartconfigData);
+  if (!result.migrated) {
+    return false;
+  }
+
+  await writeSmartconfigFile(smartconfigData);
+  plugins.logger.log(
+    "success",
+    `Applied known .smartconfig.json migrations to schema v${result.toVersion}`,
+  );
+  await formatSmartconfigWithDiff(mode);
+  return true;
+}
+
 async function collectDoctorFindings(): Promise<IDoctorFinding[]> {
   const findings: IDoctorFinding[] = [];
   const smartconfigPath = getSmartconfigPath();
@@ -1071,7 +1108,7 @@ async function collectDoctorFindings(): Promise<IDoctorFinding[]> {
   await validateDetectedProjectType(cliConfig, findings);
 
   validateCommitConfig(cliConfig.commit || {}, findings);
-  await validateReleaseConfig(cliConfig.release || {}, smartconfigData, findings);
+  await validateReleaseConfig(cliConfig.release, smartconfigData, findings);
 
   return findings;
 }
@@ -1570,10 +1607,24 @@ function validateCommitConfig(
 }
 
 async function validateReleaseConfig(
-  releaseConfig: Record<string, any>,
+  rawReleaseConfig: unknown,
   smartconfigData: Record<string, any>,
   findings: IDoctorFinding[],
 ): Promise<void> {
+  const releaseConfig = rawReleaseConfig === undefined ? {} : rawReleaseConfig;
+  if (!isPlainObject(releaseConfig)) {
+    findings.push({
+      level: "error",
+      message: `Release config must be an object, found ${
+        Array.isArray(releaseConfig) ? "array" : typeof releaseConfig
+      }`,
+      fix: Array.isArray(releaseConfig)
+        ? "Run `gitzone config migrate` to move legacy registry arrays into release.targets.npm.registries."
+        : "Set @git.zone/cli.release to an object or remove it.",
+    });
+    return;
+  }
+
   const confirmation = releaseConfig.confirmation;
   if (confirmation === undefined || validConfirmationModes.includes(confirmation)) {
     findings.push({ level: "ok", message: "Release confirmation mode is valid" });
@@ -1993,7 +2044,7 @@ export function showHelp(mode?: ICliMode): void {
         { name: "cli", description: "Configure CLI behavior interactively" },
         { name: "release", description: "Configure release workflow interactively" },
         { name: "doctor", description: "Validate .smartconfig.json" },
-        { name: "fix [instructions]", description: "Use opencode to repair .smartconfig.json" },
+        { name: "fix [instructions]", description: "Repair .smartconfig.json" },
         { name: "get <path>", description: "Read a single config value" },
         { name: "set <path> <value>", description: "Write a config value" },
         { name: "unset <path>", description: "Delete a config value" },
@@ -2038,7 +2089,7 @@ export function showHelp(mode?: ICliMode): void {
   console.log("  cli                         Configure CLI behavior interactively");
   console.log("  release                     Configure release workflow interactively");
   console.log("  doctor                      Validate .smartconfig.json");
-  console.log("  fix [instructions]          Use opencode to repair .smartconfig.json");
+  console.log("  fix [instructions]          Repair .smartconfig.json");
   console.log("  get <path>                  Read a single config value");
   console.log("  set <path> <value>          Write a config value");
   console.log("  unset <path>                Delete a config value");

ts/mod_format/classes.baseformatter.ts

@@ -1,6 +1,10 @@
 import * as plugins from './mod.plugins.js';
 import { FormatContext } from './classes.formatcontext.js';
-import type { IPlannedChange, ICheckResult } from './interfaces.format.js';
+import type {
+  IPlannedChange,
+  ICheckResult,
+  IFormatWarning,
+} from './interfaces.format.js';
 import { Project } from '../classes.project.js';
 import { FormatStats } from './classes.formatstats.js';
 
@@ -19,6 +23,14 @@ export abstract class BaseFormatter {
   abstract analyze(): Promise<IPlannedChange[]>;
   abstract applyChange(change: IPlannedChange): Promise<void>;
 
+  get runsWithoutChanges(): boolean {
+    return false;
+  }
+
+  async validate(): Promise<IFormatWarning[]> {
+    return [];
+  }
+
   async execute(changes: IPlannedChange[]): Promise<void> {
     const startTime = this.stats.moduleStartTime(this.name);
     this.stats.startModule(this.name);

ts/mod_format/classes.diffreporter.ts

@@ -42,9 +42,10 @@ export class DiffReporter {
         change.content,
       );
     } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
       logger.log(
         'error',
-        `Failed to generate diff for ${change.path}: ${error.message}`,
+        `Failed to generate diff for ${change.path}: ${errorMessage}`,
       );
       return null;
     }

ts/mod_format/classes.formatplanner.ts

@@ -1,7 +1,11 @@
 import * as plugins from './mod.plugins.js';
 import { FormatContext } from './classes.formatcontext.js';
 import { BaseFormatter } from './classes.baseformatter.js';
-import type { IFormatPlan, IPlannedChange } from './interfaces.format.js';
+import type {
+  IFormatPlan,
+  IPlannedChange,
+  IFormatWarning,
+} from './interfaces.format.js';
 import { getModuleIcon } from './interfaces.format.js';
 import { logger } from '../gitzone.logging.js';
 import { DiffReporter } from './classes.diffreporter.js';
@@ -42,15 +46,21 @@ export class FormatPlanner {
               break;
           }
         }
+
+        const warnings = await module.validate();
+        plan.warnings.push(...warnings);
       } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
         plan.warnings.push({
           level: 'error',
-          message: `Failed to analyze module ${module.name}: ${error.message}`,
+          message: `Failed to analyze module ${module.name}: ${errorMessage}`,
           module: module.name,
         });
       }
     }
 
+    plan.warnings.push(...this.detectConflictingChanges(plan.changes));
+
     plan.summary.totalFiles =
       plan.summary.filesAdded +
       plan.summary.filesModified +
@@ -65,11 +75,12 @@ export class FormatPlanner {
     context: FormatContext,
   ): Promise<void> {
     const startTime = Date.now();
+    const changesByModule = this.groupChangesByModule(plan.changes);
 
     for (const module of modules) {
-      const changes = this.plannedChanges.get(module.name) || [];
+      const changes = changesByModule.get(module.name) || [];
 
-      if (changes.length > 0) {
+      if (changes.length > 0 || module.runsWithoutChanges) {
         logger.log('info', `Executing ${module.name} formatter...`);
         await module.execute(changes);
       }
@@ -138,4 +149,55 @@ export class FormatPlanner {
         return '❌';
     }
   }
+
+  private groupChangesByModule(
+    changes: IPlannedChange[],
+  ): Map<string, IPlannedChange[]> {
+    const changesByModule = new Map<string, IPlannedChange[]>();
+    for (const change of changes) {
+      const moduleChanges = changesByModule.get(change.module) || [];
+      moduleChanges.push(change);
+      changesByModule.set(change.module, moduleChanges);
+    }
+    return changesByModule;
+  }
+
+  private detectConflictingChanges(
+    changes: IPlannedChange[],
+  ): IFormatWarning[] {
+    const warnings: IFormatWarning[] = [];
+    const changesByPath = new Map<string, IPlannedChange[]>();
+
+    for (const change of changes) {
+      if (!change.path || change.path === '<various files>') {
+        continue;
+      }
+
+      const pathChanges = changesByPath.get(change.path) || [];
+      pathChanges.push(change);
+      changesByPath.set(change.path, pathChanges);
+    }
+
+    for (const [path, pathChanges] of changesByPath) {
+      const modules = [...new Set(pathChanges.map((change) => change.module))];
+      if (modules.length < 2) {
+        continue;
+      }
+
+      const hasDelete = pathChanges.some((change) => change.type === 'delete');
+      const plannedContents = pathChanges
+        .map((change) => change.content)
+        .filter((content): content is string => content !== undefined);
+      const uniqueContents = new Set(plannedContents);
+      const level = hasDelete || uniqueContents.size > 1 ? 'warning' : 'info';
+
+      warnings.push({
+        level,
+        module: 'planner',
+        message: `Multiple formatters plan changes for ${path}: ${modules.join(', ')}. They will run in formatter order.`,
+      });
+    }
+
+    return warnings;
+  }
 }

ts/mod_format/formatters/copy.formatter.ts

@@ -93,7 +93,8 @@ export class CopyFormatter extends BaseFormatter {
           }
         }
       } catch (error) {
-        logVerbose(`Failed to process pattern ${pattern.from}: ${error.message}`);
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logVerbose(`Failed to process pattern ${pattern.from}: ${errorMessage}`);
       }
     }
 

ts/mod_format/formatters/license.formatter.ts

@@ -1,5 +1,5 @@
 import { BaseFormatter } from '../classes.baseformatter.js';
-import type { IPlannedChange } from '../interfaces.format.js';
+import type { IFormatWarning, IPlannedChange } from '../interfaces.format.js';
 import * as plugins from '../mod.plugins.js';
 import * as paths from '../../paths.js';
 import { logger } from '../../gitzone.logging.js';
@@ -11,6 +11,10 @@ export class LicenseFormatter extends BaseFormatter {
     return 'license';
   }
 
+  get runsWithoutChanges(): boolean {
+    return true;
+  }
+
   async analyze(): Promise<IPlannedChange[]> {
     // License formatter only checks for incompatible licenses
     // It does not modify any files, so return empty array
@@ -18,29 +22,34 @@ export class LicenseFormatter extends BaseFormatter {
     return [];
   }
 
+  async validate(): Promise<IFormatWarning[]> {
+    const result = await this.checkLicenses();
+    if (!result || result.failingModules.length === 0) {
+      return [];
+    }
+
+    return [
+      {
+        level: 'error',
+        module: this.name,
+        message: `License check failed for ${result.failingModules.length} module(s): ${result.failingModules
+          .map((failedModule) => `${failedModule.name} (${failedModule.license})`)
+          .join(', ')}`,
+      },
+    ];
+  }
+
   async execute(changes: IPlannedChange[]): Promise<void> {
     const startTime = this.stats.moduleStartTime(this.name);
     this.stats.startModule(this.name);
 
     try {
-      // Check if node_modules exists
+      const licenseCheckResult = await this.checkLicenses();
-      const nodeModulesPath = plugins.path.join(paths.cwd, 'node_modules');
+      if (!licenseCheckResult) {
-      const nodeModulesExists = await plugins.smartfs
-        .directory(nodeModulesPath)
-        .exists();
-
-      if (!nodeModulesExists) {
         logger.log('warn', 'No node_modules found. Skipping license check');
         return;
       }
 
-      // Run license check
-      const licenseChecker = await plugins.smartlegal.createLicenseChecker();
-      const licenseCheckResult = await licenseChecker.excludeLicenseWithinPath(
-        paths.cwd,
-        INCOMPATIBLE_LICENSES,
-      );
-
       if (licenseCheckResult.failingModules.length === 0) {
         logger.log('info', 'License check passed - no incompatible licenses found');
       } else {
@@ -59,4 +68,23 @@ export class LicenseFormatter extends BaseFormatter {
   async applyChange(change: IPlannedChange): Promise<void> {
     // No file changes for license formatter
   }
+
+  private async checkLicenses(): Promise<{
+    failingModules: Array<{ name: string; license: string }>;
+  } | undefined> {
+    const nodeModulesPath = plugins.path.join(paths.cwd, 'node_modules');
+    const nodeModulesExists = await plugins.smartfs
+      .directory(nodeModulesPath)
+      .exists();
+
+    if (!nodeModulesExists) {
+      return undefined;
+    }
+
+    const licenseChecker = await plugins.smartlegal.createLicenseChecker();
+    return await licenseChecker.excludeLicenseWithinPath(
+      paths.cwd,
+      INCOMPATIBLE_LICENSES,
+    );
+  }
 }

ts/mod_format/formatters/packagejson.formatter.ts

@@ -94,7 +94,8 @@ export class PackageJsonFormatter extends BaseFormatter {
       packageJson.pnpm = packageJson.pnpm || {};
       packageJson.pnpm.overrides = overrides;
     } catch (error) {
-      logVerbose(`Could not read overrides.json: ${error.message}`);
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      logVerbose(`Could not read overrides.json: ${errorMessage}`);
     }
 
     const newContent = JSON.stringify(packageJson, null, 2);

ts/mod_format/formatters/prettier.formatter.ts

@@ -56,7 +56,8 @@ export class PrettierFormatter extends BaseFormatter {
         );
         allFiles.push(...filteredFiles);
       } catch (error) {
-        logVerbose(`Skipping directory ${dir}: ${error.message}`);
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logVerbose(`Skipping directory ${dir}: ${errorMessage}`);
       }
     }
 
@@ -72,7 +73,8 @@ export class PrettierFormatter extends BaseFormatter {
         const rootLevelFiles = rootFiles.filter((f) => !f.includes('/'));
         allFiles.push(...rootLevelFiles);
       } catch (error) {
-        logVerbose(`Skipping pattern ${pattern}: ${error.message}`);
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logVerbose(`Skipping pattern ${pattern}: ${errorMessage}`);
       }
     }
 
@@ -89,20 +91,46 @@ export class PrettierFormatter extends BaseFormatter {
         }
       } catch (error) {
         // Skip files that can't be accessed
-        logVerbose(`Skipping ${file} - cannot access: ${error.message}`);
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logVerbose(`Skipping ${file} - cannot access: ${errorMessage}`);
       }
     }
 
+    const prettier = await import('prettier');
+    const prettierConfig = await this.getPrettierConfig();
+
     for (const file of validFiles) {
-      changes.push({
+      try {
-        type: 'modify',
+        const fileExt = plugins.path.extname(file).toLowerCase();
-        path: file,
+        if (!fileExt) {
-        module: this.name,
+          continue;
-        description: 'Format with Prettier',
+        }
-      });
+
+        const content = (await plugins.smartfs
+          .file(file)
+          .encoding('utf8')
+          .read()) as string;
+        const formatted = await prettier.format(content, {
+          filepath: file,
+          ...prettierConfig,
+        });
+
+        if (formatted !== content) {
+          changes.push({
+            type: 'modify',
+            path: file,
+            module: this.name,
+            description: 'Format with Prettier',
+            content: formatted,
+          });
+        }
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logVerbose(`Skipping Prettier analysis for ${file}: ${errorMessage}`);
+      }
     }
 
-    logger.log('info', `Found ${changes.length} files to format with Prettier`);
+    logger.log('info', `Found ${changes.length} files needing Prettier`);
     return changes;
   }
 
@@ -127,9 +155,10 @@ export class PrettierFormatter extends BaseFormatter {
           this.stats.recordFileOperation(this.name, change.type, true);
         } catch (error) {
           this.stats.recordFileOperation(this.name, change.type, false);
+          const errorMessage = error instanceof Error ? error.message : String(error);
           logger.log(
             'error',
-            `Failed to format ${change.path}: ${error.message}`,
+            `Failed to format ${change.path}: ${errorMessage}`,
           );
           // Don't throw - continue with other files
         }
@@ -192,28 +221,32 @@ export class PrettierFormatter extends BaseFormatter {
           logVerbose(`No formatting changes for ${change.path}`);
         }
       } catch (prettierError) {
+        const prettierErrorMessage = prettierError instanceof Error
+          ? prettierError.message
+          : String(prettierError);
         // Check if it's a parser error
-        if (
+        if (prettierErrorMessage.includes('No parser could be inferred')) {
-          prettierError.message &&
+          logVerbose(`Skipping ${change.path} - ${prettierErrorMessage}`);
-          prettierError.message.includes('No parser could be inferred')
-        ) {
-          logVerbose(`Skipping ${change.path} - ${prettierError.message}`);
           return; // Skip this file silently
         }
         throw prettierError;
       }
     } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const errorStack = error instanceof Error ? error.stack : undefined;
       // Log the full error stack for debugging mkdir issues
-      if (error.message && error.message.includes('mkdir')) {
+      if (errorMessage.includes('mkdir')) {
         logger.log(
           'error',
-          `Failed to format ${change.path}: ${error.message}`,
+          `Failed to format ${change.path}: ${errorMessage}`,
         );
-        logger.log('error', `Error stack: ${error.stack}`);
+        if (errorStack) {
+          logger.log('error', `Error stack: ${errorStack}`);
+        }
       } else {
         logger.log(
           'error',
-          `Failed to format ${change.path}: ${error.message}`,
+          `Failed to format ${change.path}: ${errorMessage}`,
         );
       }
       throw error;
@@ -234,52 +267,7 @@ export class PrettierFormatter extends BaseFormatter {
     });
   }
 
-  /**
-   * Override check() to compute diffs on-the-fly by running prettier
-   */
   async check(): Promise<ICheckResult> {
-    const changes = await this.analyze();
+    return await super.check();
-    const diffs: ICheckResult['diffs'] = [];
-
-    for (const change of changes) {
-      if (change.type !== 'modify') continue;
-
-      try {
-        // Read current content
-        const currentContent = (await plugins.smartfs
-          .file(change.path)
-          .encoding('utf8')
-          .read()) as string;
-
-        // Skip files without extension (prettier can't infer parser)
-        const fileExt = plugins.path.extname(change.path).toLowerCase();
-        if (!fileExt) continue;
-
-        // Format with prettier to get what it would produce
-        const prettier = await import('prettier');
-        const formatted = await prettier.format(currentContent, {
-          filepath: change.path,
-          ...(await this.getPrettierConfig()),
-        });
-
-        // Only add to diffs if content differs
-        if (formatted !== currentContent) {
-          diffs.push({
-            path: change.path,
-            type: 'modify',
-            before: currentContent,
-            after: formatted,
-          });
-        }
-      } catch (error) {
-        // Skip files that can't be processed
-        logVerbose(`Skipping diff for ${change.path}: ${error.message}`);
-      }
-    }
-
-    return {
-      hasDiff: diffs.length > 0,
-      diffs,
-    };
   }
 }

ts/mod_format/formatters/templates.formatter.ts

@@ -117,7 +117,8 @@ export class TemplatesFormatter extends BaseFormatter {
     try {
       renderedFiles = await this.renderTemplate(templateName);
     } catch (error) {
-      logVerbose(`Failed to render template ${templateName}: ${error.message}`);
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      logVerbose(`Failed to render template ${templateName}: ${errorMessage}`);
       return changes;
     }
 

ts/mod_format/formatters/tsconfig.formatter.ts

@@ -46,7 +46,8 @@ export class TsconfigFormatter extends BaseFormatter {
         ];
       }
     } catch (error) {
-      logVerbose(`Could not get tspublish modules: ${error.message}`);
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      logVerbose(`Could not get tspublish modules: ${errorMessage}`);
     }
 
     tsconfigObject.compilerOptions.paths = { ...existingPaths, ...tspublishPaths };

ts/mod_format/index.ts

@@ -22,6 +22,7 @@ import { TsconfigFormatter } from "./formatters/tsconfig.formatter.js";
 import { PrettierFormatter } from "./formatters/prettier.formatter.js";
 import { ReadmeFormatter } from "./formatters/readme.formatter.js";
 import { CopyFormatter } from "./formatters/copy.formatter.js";
+import type { ICheckResult, IFormatPlan } from "./interfaces.format.js";
 
 /**
  * Rename npmextra.json or smartconfig.json to .smartconfig.json
@@ -94,9 +95,39 @@ const getFormatConfig = async () => {
   };
 };
 
+const normalizeModuleList = (value: unknown): string[] => {
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => normalizeModuleList(item));
+  }
+  if (typeof value !== "string") {
+    return [];
+  }
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+};
+
+const getPlanStatus = (plan: IFormatPlan) => {
+  const errorWarnings = plan.warnings.filter(
+    (warning) => warning.level === "error",
+  );
+  const hasChanges = plan.summary.totalFiles > 0;
+  const hasErrors = errorWarnings.length > 0;
+
+  return {
+    ok: !hasChanges && !hasErrors,
+    hasChanges,
+    hasErrors,
+    errorCount: errorWarnings.length,
+  };
+};
+
 const createActiveFormatters = async (options: {
   interactive: boolean;
   jsonOutput: boolean;
+  only?: string[];
+  skip?: string[];
 }) => {
   const project = await Project.fromCwd({ requireProjectType: false });
   const context = new FormatContext(options);
@@ -107,11 +138,19 @@ const createActiveFormatters = async (options: {
     ([, FormatterClass]) => new FormatterClass(context, project),
   );
 
+  const onlyModules = options.only?.length
+    ? options.only
+    : formatConfig.modules.only;
+  const skipModules = [
+    ...formatConfig.modules.skip,
+    ...(options.skip || []),
+  ];
+
   const activeFormatters = formatters.filter((formatter) => {
-    if (formatConfig.modules.only.length > 0) {
+    if (onlyModules.length > 0) {
-      return formatConfig.modules.only.includes(formatter.name);
+      return onlyModules.includes(formatter.name);
     }
-    if (formatConfig.modules.skip.includes(formatter.name)) {
+    if (skipModules.includes(formatter.name)) {
       return false;
     }
     return true;
@@ -129,11 +168,15 @@ const buildFormatPlan = async (options: {
   fromPlan?: string;
   interactive: boolean;
   jsonOutput: boolean;
+  only?: string[];
+  skip?: string[];
 }) => {
   const { context, planner, formatConfig, activeFormatters } =
     await createActiveFormatters({
       interactive: options.interactive,
       jsonOutput: options.jsonOutput,
+      only: options.only,
+      skip: options.skip,
     });
 
   const plan = options.fromPlan
@@ -167,6 +210,182 @@ const serializePlan = (plan: any) => {
   };
 };
 
+const buildFormatFixPrompt = (
+  plan: IFormatPlan,
+  extraInstructions: string,
+): string => {
+  const promptParts = [
+    "Other /c-* commands can be found at ~/.config/opencode/commands/*",
+    "# gitzone format fix",
+    "",
+    `Working directory: ${process.cwd()}`,
+    "",
+    "Repair project formatting so `gitzone format check --json` passes.",
+    "",
+    "Rules:",
+    "- Read `.smartconfig.json`, `package.json`, `tsconfig.json`, and the current format plan before editing.",
+    "- Prefer deterministic gitzone standards, bundled assets, and existing project conventions.",
+    "- Keep changes focused on formatting, metadata normalization, templates, and config consistency.",
+    "- Do not commit, release, install dependencies, or modify unrelated files.",
+    "- Use pnpm commands only if commands are needed.",
+    "- Run `gitzone format --write --yes` after changes.",
+    "- Run `gitzone format check --json` after changes and keep fixing until it passes.",
+    "- Run `git diff --check` after changes to catch whitespace problems.",
+    "",
+    "Current format plan:",
+    JSON.stringify(serializePlan(plan), null, 2),
+  ];
+
+  if (extraInstructions) {
+    promptParts.push("", "Additional user instructions:", extraInstructions);
+  }
+
+  return promptParts.join("\n");
+};
+
+const handleFormatFix = async (
+  options: Record<string, any>,
+  mode: ICliMode,
+): Promise<void> => {
+  if (mode.json) {
+    printJson({
+      ok: false,
+      error:
+        "JSON output is not supported for `gitzone format fix`. Use `gitzone format check --json` for machine-readable diagnostics.",
+    });
+    process.exitCode = 1;
+    return;
+  }
+
+  const extraInstructions = (options._?.slice(2).join(" ") || "").trim();
+  const force = Boolean(options.force);
+  const autoApprove = Boolean(options.yes || mode.yes);
+  const formatConfig = await getFormatConfig();
+  const interactive =
+    options.interactive ?? (mode.interactive && formatConfig.interactive);
+  const only = normalizeModuleList(options.only);
+  const skip = normalizeModuleList(options.skip);
+
+  const buildCurrentPlan = async () => {
+    return await buildFormatPlan({
+      interactive,
+      jsonOutput: false,
+      only,
+      skip,
+    });
+  };
+
+  logger.log("info", "Analyzing project for format fixes...");
+  let { plan } = await buildCurrentPlan();
+  let status = getPlanStatus(plan);
+
+  if (status.ok && !extraInstructions && !force) {
+    logger.log(
+      "success",
+      "Format check found no issues. Use `gitzone format fix --force` to run opencode anyway.",
+    );
+    return;
+  }
+
+  if (!autoApprove) {
+    if (!mode.interactive) {
+      throw new Error(
+        "Format fix requires an interactive terminal or `-y` to run non-interactively.",
+      );
+    }
+    const confirmed = await plugins.smartinteract.SmartInteract.getCliConfirmation(
+      `Run format fixes? (${plan.summary.totalFiles} planned change(s), ${status.errorCount} error warning(s))`,
+      true,
+    );
+    if (!confirmed) {
+      logger.log("info", "Format fix cancelled.");
+      return;
+    }
+  }
+
+  if (status.hasChanges) {
+    logger.log("info", "Applying deterministic format changes first...");
+    await run({
+      _: ["format"],
+      write: true,
+      yes: true,
+      interactive: false,
+      verbose: options.verbose,
+      detailed: options.detailed,
+      only: options.only,
+      skip: options.skip,
+    });
+
+    ({ plan } = await buildCurrentPlan());
+    status = getPlanStatus(plan);
+    if (status.ok && !extraInstructions && !force) {
+      logger.log("success", "Format fix completed successfully.");
+      return;
+    }
+  }
+
+  const opencodeArgs = [
+    "run",
+    "--title",
+    "gitzone format fix",
+    "--dir",
+    process.cwd(),
+  ];
+  if (autoApprove) {
+    opencodeArgs.push("--dangerously-skip-permissions");
+  }
+  opencodeArgs.push(buildFormatFixPrompt(plan, extraInstructions));
+
+  logger.log("info", "Starting opencode format fix...");
+  const smartshellInstance = new plugins.smartshell.Smartshell({
+    executor: "bash",
+    sourceFilePaths: [],
+  });
+
+  let result: plugins.smartshell.IExecResult;
+  try {
+    result = await smartshellInstance.execSpawn("opencode", opencodeArgs, {
+      stdio: "inherit",
+    });
+  } catch (error) {
+    throw new Error(
+      `Failed to run opencode: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  if (result.exitCode !== 0) {
+    logger.log("error", `opencode exited with code ${result.exitCode}`);
+    process.exitCode = result.exitCode || 1;
+    return;
+  }
+
+  logger.log("info", "Running deterministic format pass after opencode...");
+  await run({
+    _: ["format"],
+    write: true,
+    yes: true,
+    interactive: false,
+    verbose: options.verbose,
+    detailed: options.detailed,
+    only: options.only,
+    skip: options.skip,
+  });
+
+  const { planner: finalPlanner, plan: finalPlan } = await buildCurrentPlan();
+  await finalPlanner.displayPlan(finalPlan, options.detailed);
+  const finalStatus = getPlanStatus(finalPlan);
+  if (finalStatus.ok) {
+    logger.log("success", "Format fix completed successfully.");
+    return;
+  }
+
+  logger.log(
+    "error",
+    `Format fix left ${finalPlan.summary.totalFiles} planned change(s) and ${finalStatus.errorCount} error warning(s).`,
+  );
+  process.exitCode = 1;
+};
+
 export let run = async (
   options: {
     write?: boolean;
@@ -194,8 +413,25 @@ export let run = async (
     setVerboseMode(true);
   }
 
+  if (subcommand === "fix") {
+    await handleFormatFix(options, mode);
+    return;
+  }
+
   const shouldWrite = options.write ?? options.dryRun === false;
   const treatAsPlan = subcommand === "plan";
+  const treatAsCheck = subcommand === "check" || Boolean(options.check);
+
+  if (treatAsCheck && shouldWrite) {
+    const error = "`gitzone format check` is read-only and cannot be combined with --write.";
+    if (mode.json) {
+      printJson({ ok: false, error });
+    } else {
+      logger.log("error", error);
+    }
+    process.exitCode = 1;
+    return;
+  }
 
   if (mode.json && shouldWrite) {
     printJson({
@@ -212,7 +448,9 @@ export let run = async (
   const formatConfig = await getFormatConfig();
   const interactive =
     options.interactive ?? (mode.interactive && formatConfig.interactive);
-  const autoApprove = options.yes ?? formatConfig.autoApprove;
+  const autoApprove = options.yes ?? (mode.yes || formatConfig.autoApprove);
+  const only = normalizeModuleList(options.only);
+  const skip = normalizeModuleList(options.skip);
 
   try {
     const planBuilder = async () => {
@@ -220,6 +458,8 @@ export let run = async (
         fromPlan: options.fromPlan,
         interactive,
         jsonOutput: mode.json,
+        only,
+        skip,
       });
     };
 
@@ -231,7 +471,16 @@ export let run = async (
       : await planBuilder();
 
     if (mode.json) {
-      printJson(serializePlan(plan));
+      const serializedPlan = serializePlan(plan);
+      if (treatAsCheck) {
+        const status = getPlanStatus(plan);
+        printJson({ ok: status.ok, ...serializedPlan });
+        if (!status.ok) {
+          process.exitCode = 1;
+        }
+        return;
+      }
+      printJson(serializedPlan);
       return;
     }
 
@@ -251,6 +500,20 @@ export let run = async (
       return;
     }
 
+    if (treatAsCheck) {
+      const status = getPlanStatus(plan);
+      if (status.ok) {
+        logger.log("success", "Format check passed");
+      } else {
+        logger.log(
+          "error",
+          `Format check failed: ${plan.summary.totalFiles} planned change(s), ${status.errorCount} error warning(s)`,
+        );
+        process.exitCode = 1;
+      }
+      return;
+    }
+
     // Show diffs if explicitly requested or before interactive write confirmation
     const showDiffs =
       options.diff || (shouldWrite && interactive && !autoApprove);
@@ -314,7 +577,6 @@ export let run = async (
   }
 };
 
-import type { ICheckResult } from "./interfaces.format.js";
 export type { ICheckResult };
 
 /**
@@ -363,7 +625,7 @@ export function showHelp(mode?: ICliMode): void {
   if (mode?.json) {
     printJson({
       command: "format",
-      usage: "gitzone format [plan] [options]",
+      usage: "gitzone format [plan|check|fix] [options]",
       description:
         "Plans formatting changes by default and applies them only with --write.",
       flags: [
@@ -393,19 +655,33 @@ export function showHelp(mode?: ICliMode): void {
           flag: "--diff",
           description: "Show per-file diffs before applying changes",
         },
+        {
+          flag: "--only <modules>",
+          description: "Run only the comma-separated formatter modules",
+        },
+        {
+          flag: "--skip <modules>",
+          description: "Skip the comma-separated formatter modules",
+        },
+        {
+          flag: "--force",
+          description: "Run `format fix` even when the deterministic plan is clean",
+        },
         { flag: "--json", description: "Emit a read-only format plan as JSON" },
       ],
       examples: [
         "gitzone format",
         "gitzone format plan --json",
+        "gitzone format check",
         "gitzone format --write --yes",
+        "gitzone format fix",
       ],
     });
     return;
   }
 
   console.log("");
-  console.log("Usage: gitzone format [plan] [options]");
+  console.log("Usage: gitzone format [plan|check|fix] [options]");
   console.log("");
   console.log(
     "Plans formatting changes by default and applies them only with --write.",
@@ -424,11 +700,16 @@ export function showHelp(mode?: ICliMode): void {
   console.log(
     "  --diff               Show per-file diffs before applying changes",
   );
+  console.log("  --only <modules>     Run only comma-separated formatter modules");
+  console.log("  --skip <modules>     Skip comma-separated formatter modules");
+  console.log("  --force              Run format fix even when the plan is clean");
   console.log("  --json               Emit a read-only format plan as JSON");
   console.log("");
   console.log("Examples:");
   console.log("  gitzone format");
   console.log("  gitzone format plan --json");
+  console.log("  gitzone format check");
   console.log("  gitzone format --write --yes");
+  console.log("  gitzone format fix");
   console.log("");
 }

ts/mod_format/interfaces.format.ts

@@ -1,3 +1,9 @@
+export type IFormatWarning = {
+  level: 'info' | 'warning' | 'error';
+  message: string;
+  module: string;
+};
+
 export type IFormatPlan = {
   summary: {
     totalFiles: number;
@@ -5,17 +11,8 @@ export type IFormatPlan = {
     filesModified: number;
     filesRemoved: number;
   };
-  changes: Array<{
+  changes: IPlannedChange[];
-    type: 'create' | 'modify' | 'delete';
+  warnings: IFormatWarning[];
-    path: string;
-    module: string;
-    description: string;
-  }>;
-  warnings: Array<{
-    level: 'info' | 'warning' | 'error';
-    message: string;
-    module: string;
-  }>;
 };
 
 export type IPlannedChange = {

ts/mod_meta/meta.classes.meta.ts

@@ -26,7 +26,7 @@ export class Meta {
   /**
    * the meta repo data
    */
-  public metaRepoData: interfaces.IMetaRepoData;
+  public metaRepoData!: interfaces.IMetaRepoData;
   public smartshellInstance = new plugins.smartshell.Smartshell({
     executor: 'bash',
   });

ts/mod_open/index.ts

@@ -1,8 +1,8 @@
 import * as plugins from './mod.plugins.js';
 import * as paths from '../paths.js';
 
-export let run = (argvArg) => {
+export let run = async (argvArg) => {
-  let projectInfo = new plugins.projectinfo.ProjectInfo(paths.cwd);
+  let projectInfo = await plugins.projectinfo.ProjectInfo.create(paths.cwd);
   if (argvArg._[1] === 'ci') {
     plugins.smartopen.openUrl(
       `https://gitlab.com/${projectInfo.git.gituser}/${projectInfo.git.gitrepo}/settings/ci_cd`,

ts/mod_services/classes.dockercontainer.ts

@@ -148,7 +148,8 @@ export class DockerContainer {
       const result = await this.smartshell.exec(command);
       return result.exitCode === 0;
     } catch (error) {
-      logger.log('error', `Failed to run container: ${error.message}`);
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      logger.log('error', `Failed to run container: ${errorMessage}`);
       return false;
     }
   }
@@ -177,7 +178,8 @@ export class DockerContainer {
       const result = await this.smartshell.exec(`docker logs ${tailFlag} ${containerName}`);
       return result.stdout;
     } catch (error) {
-      return `Error getting logs: ${error.message}`;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return `Error getting logs: ${errorMessage}`;
     }
   }
   

ts/mod_services/classes.serviceconfiguration.ts

@@ -28,7 +28,7 @@ export interface IServiceConfig {
 
 export class ServiceConfiguration {
   private configPath: string;
-  private config: IServiceConfig;
+  private config!: IServiceConfig;
   private docker: DockerContainer;
   
   constructor() {

ts/mod_services/classes.servicemanager.ts

@@ -61,13 +61,15 @@ export class ServiceManager {
         default: ['mongodb', 'minio', 'elasticsearch']
       });
 
-      this.enabledServices = response.value || ['mongodb', 'minio', 'elasticsearch'];
+      const enabledServices = response.value || ['mongodb', 'minio', 'elasticsearch'];
+      this.enabledServices = enabledServices;
 
       // Save to .smartconfig.json
-      await this.saveServiceConfiguration(this.enabledServices);
+      await this.saveServiceConfiguration(enabledServices);
     } else {
-      this.enabledServices = gitzoneConfig.services;
+      const enabledServices = gitzoneConfig.services as string[];
-      logger.log('info', `🔧 Enabled services: ${this.enabledServices.join(', ')}`);
+      this.enabledServices = enabledServices;
+      logger.log('info', `🔧 Enabled services: ${enabledServices.join(', ')}`);
     }
   }
 
@@ -902,10 +904,11 @@ export class ServiceManager {
       default: currentServices
     });
 
-    this.enabledServices = response.value || ['mongodb', 'minio', 'elasticsearch'];
+    const enabledServices = response.value || ['mongodb', 'minio', 'elasticsearch'];
+    this.enabledServices = enabledServices;
 
     // Save to .smartconfig.json
-    await this.saveServiceConfiguration(this.enabledServices);
+    await this.saveServiceConfiguration(enabledServices);
 
     logger.log('ok', '✅ Service configuration updated');
   }

ts/mod_standard/index.ts

@@ -202,6 +202,7 @@ export async function showHelp(
   console.log("  gitzone commit recommend --json");
   console.log("  gitzone release --plan");
   console.log("  gitzone format plan --json");
+  console.log("  gitzone format check");
   console.log("  gitzone services set mongodb,minio");
   console.log("  gitzone tools update");
   console.log("");

ts/mod_template/index.ts

@@ -15,7 +15,7 @@ export const isTemplate = async (templateNameArg: string) => {
 };
 
 export const getTemplate = async (templateNameArg: string) => {
-  if (isTemplate(templateNameArg)) {
+  if (await isTemplate(templateNameArg)) {
     const localScafTemplate = new plugins.smartscaf.ScafTemplate(
       getTemplatePath(templateNameArg),
     );
@@ -50,6 +50,10 @@ export const run = async (argvArg: any) => {
   }
 
   const localScafTemplate = await getTemplate(chosenTemplate);
+  if (!localScafTemplate) {
+    logger.log('error', `Template ${chosenTemplate} not available`);
+    return;
+  }
   await localScafTemplate.askCliForMissingVariables();
   await localScafTemplate.writeToDisk(paths.cwd);
 };

ts/mod_tools/classes.packagemanager.ts

@@ -3,6 +3,9 @@ import * as plugins from "./mod.plugins.js";
 export interface IInstalledPackage {
   name: string;
   version: string;
+  globalDir?: string;
+  packagePath?: string;
+  legacy?: boolean;
 }
 
 export interface IPackageUpdateInfo {
@@ -10,6 +13,8 @@ export interface IPackageUpdateInfo {
   currentVersion: string;
   latestVersion: string;
   needsUpdate: boolean;
+  needsMigration?: boolean;
+  globalDir?: string;
 }
 
 export interface IPackageManagerInfo {
@@ -19,18 +24,38 @@ export interface IPackageManagerInfo {
   needsUpdate: boolean;
 }
 
+export interface ILegacyGlobalRootInfo {
+  globalDir: string;
+  packages: IInstalledPackage[];
+  unmanagedPackageNames: string[];
+  safeToDelete: boolean;
+}
+
+export interface ILegacyCleanupResult {
+  globalDir: string;
+  deleted: boolean;
+  reason?: string;
+}
+
+export interface IShimSyncResult {
+  name: string;
+  action: "updated" | "removed" | "skipped";
+  reason?: string;
+}
+
+interface IPnpmListProject {
+  path?: string;
+  dependencies?: Record<string, any>;
+}
+
 export class PackageManagerUtil {
   private shell = new plugins.smartshell.Smartshell({
     executor: "bash",
   });
+  private pnpmCommand: string | null | undefined;
 
   public async detectPnpm(): Promise<boolean> {
-    try {
+    return Boolean(await this.getPnpmCommand());
-      const result = await this.shell.execSilent("pnpm --version 2>/dev/null");
-      return result.exitCode === 0 && Boolean(result.stdout.trim());
-    } catch {
-      return false;
-    }
   }
 
   public async getPnpmVersionInfo(): Promise<IPackageManagerInfo> {
@@ -45,53 +70,300 @@ export class PackageManagerUtil {
     }
 
     const currentVersion = await this.getCurrentPnpmVersion();
-    const latestVersion = await this.getLatestVersion("pnpm", ["https://registry.npmjs.org"]);
+    const latestVersion = await this.getLatestVersion("pnpm", [
+      "https://registry.npmjs.org",
+    ]);
 
     return {
       available: true,
       currentVersion,
       latestVersion,
-      needsUpdate: latestVersion ? this.isNewerVersion(currentVersion, latestVersion) : false,
+      needsUpdate: latestVersion
+        ? this.isNewerVersion(currentVersion, latestVersion)
+        : false,
     };
   }
 
   public async getInstalledPackages(): Promise<IInstalledPackage[]> {
-    const packages: IInstalledPackage[] = [];
+    const packageMap = new Map<string, IInstalledPackage>();
+    const currentPackages = await this.getCurrentInstalledPackages();
 
-    try {
+    for (const packageInfo of currentPackages) {
-      const result = await this.shell.execSilent("pnpm list -g --depth=0 --json 2>/dev/null || true");
+      packageMap.set(packageInfo.name, packageInfo);
-      const output = result.stdout.trim();
-      if (!output) {
-        return packages;
-      }
-
-      const data = JSON.parse(output);
-      const dataArray = Array.isArray(data) ? data : [data];
-      for (const item of dataArray) {
-        const dependencies = item.dependencies || {};
-        for (const [name, info] of Object.entries(dependencies)) {
-          if (!name.startsWith("@git.zone/")) {
-            continue;
-          }
-          packages.push({
-            name,
-            version: (info as any).version || "unknown",
-          });
-        }
-      }
-    } catch {
-      return packages;
     }
 
-    return packages;
+    const legacyRoots = await this.getLegacyGlobalRoots();
+    for (const legacyRoot of legacyRoots) {
+      for (const packageInfo of legacyRoot.packages) {
+        if (!packageMap.has(packageInfo.name)) {
+          packageMap.set(packageInfo.name, packageInfo);
+        }
+      }
+    }
+
+    return Array.from(packageMap.values()).sort((packageA, packageB) =>
+      packageA.name.localeCompare(packageB.name),
+    );
+  }
+
+  public async getLegacyGlobalRoots(): Promise<ILegacyGlobalRootInfo[]> {
+    const currentGlobalDir = await this.getCurrentGlobalDir();
+    const baseDirs = new Set<string>();
+    const pnpmHome = process.env.PNPM_HOME;
+
+    if (pnpmHome) {
+      baseDirs.add(plugins.path.join(pnpmHome, "global"));
+    }
+
+    if (currentGlobalDir) {
+      baseDirs.add(plugins.path.dirname(currentGlobalDir));
+    }
+
+    const roots: ILegacyGlobalRootInfo[] = [];
+    for (const baseDir of baseDirs) {
+      try {
+        const entries = await plugins.fs.readdir(baseDir, {
+          withFileTypes: true,
+        });
+
+        for (const entry of entries) {
+          if (!entry.isDirectory()) {
+            continue;
+          }
+
+          const globalDir = normalizePath(
+            plugins.path.join(baseDir, entry.name),
+          );
+          if (currentGlobalDir && pathsAreEqual(globalDir, currentGlobalDir)) {
+            continue;
+          }
+
+          const rootInfo = await this.inspectGlobalRoot(globalDir, false);
+          if (rootInfo.packages.length > 0) {
+            roots.push(rootInfo);
+          }
+        }
+      } catch {
+        continue;
+      }
+    }
+
+    return roots;
+  }
+
+  public async cleanupLegacyGlobalRoots(): Promise<ILegacyCleanupResult[]> {
+    const legacyRoots = await this.getLegacyGlobalRoots();
+    if (legacyRoots.length === 0) {
+      return [];
+    }
+
+    const currentPackageNames = new Set(
+      (await this.getCurrentInstalledPackages()).map(
+        (packageInfo) => packageInfo.name,
+      ),
+    );
+    const cleanupResults: ILegacyCleanupResult[] = [];
+
+    for (const legacyRoot of legacyRoots) {
+      const missingPackageNames = legacyRoot.packages
+        .map((packageInfo) => packageInfo.name)
+        .filter((packageName) => !currentPackageNames.has(packageName));
+
+      if (missingPackageNames.length > 0) {
+        cleanupResults.push({
+          globalDir: legacyRoot.globalDir,
+          deleted: false,
+          reason: `kept because ${missingPackageNames.join(", ")} are not installed in the current pnpm global root`,
+        });
+        continue;
+      }
+
+      if (!legacyRoot.safeToDelete) {
+        cleanupResults.push({
+          globalDir: legacyRoot.globalDir,
+          deleted: false,
+          reason:
+            legacyRoot.unmanagedPackageNames.length > 0
+              ? `kept because it also contains ${legacyRoot.unmanagedPackageNames.join(", ")}`
+              : "kept because it is not a managed @git.zone-only global root",
+        });
+        continue;
+      }
+
+      const blockingShims = await this.getShimReferences(legacyRoot.globalDir);
+      if (blockingShims === null) {
+        cleanupResults.push({
+          globalDir: legacyRoot.globalDir,
+          deleted: false,
+          reason:
+            "kept because PNPM_HOME is not set, so command shims could not be verified",
+        });
+        continue;
+      }
+
+      if (blockingShims.length > 0) {
+        cleanupResults.push({
+          globalDir: legacyRoot.globalDir,
+          deleted: false,
+          reason: `kept because command shims still reference it: ${blockingShims.join(", ")}`,
+        });
+        continue;
+      }
+
+      try {
+        await plugins.fs.rm(legacyRoot.globalDir, {
+          recursive: true,
+          force: true,
+        });
+        cleanupResults.push({
+          globalDir: legacyRoot.globalDir,
+          deleted: true,
+        });
+      } catch (error) {
+        cleanupResults.push({
+          globalDir: legacyRoot.globalDir,
+          deleted: false,
+          reason: `delete failed: ${(error as Error).message}`,
+        });
+      }
+    }
+
+    return cleanupResults;
+  }
+
+  public async syncCurrentGlobalShims(): Promise<IShimSyncResult[]> {
+    const pnpmShimDirs = await this.getPnpmShimDirs();
+    if (!pnpmShimDirs) {
+      return [
+        {
+          name: "PNPM_HOME",
+          action: "skipped",
+          reason: "PNPM_HOME is not set",
+        },
+      ];
+    }
+
+    const results: IShimSyncResult[] = [];
+    const currentBinNames = new Set<string>();
+    const currentPackages = await this.getCurrentInstalledPackages();
+
+    for (const packageInfo of currentPackages) {
+      if (!packageInfo.packagePath) {
+        continue;
+      }
+
+      const packageJson = await readJson(
+        plugins.path.join(packageInfo.packagePath, "package.json"),
+      );
+      const binNames = getPackageBinNames(packageInfo.name, packageJson);
+      const nodeModulesDir = getNodeModulesDir(
+        packageInfo.packagePath,
+        packageInfo.name,
+      );
+
+      for (const binName of binNames) {
+        currentBinNames.add(binName);
+        const sourceShim = plugins.path.join(nodeModulesDir, ".bin", binName);
+
+        for (const pnpmShimDir of pnpmShimDirs) {
+          const destinationShim = plugins.path.join(pnpmShimDir, binName);
+
+          try {
+            const sourceContent = await plugins.fs.readFile(sourceShim, "utf8");
+            const sourceStat = await plugins.fs.stat(sourceShim);
+            await plugins.fs.writeFile(
+              destinationShim,
+              rewriteShimForPnpmHome(sourceContent),
+              "utf8",
+            );
+            await plugins.fs.chmod(destinationShim, sourceStat.mode);
+            results.push({
+              name: formatShimName(pnpmShimDir, binName),
+              action: "updated",
+            });
+          } catch (error) {
+            results.push({
+              name: formatShimName(pnpmShimDir, binName),
+              action: "skipped",
+              reason: (error as Error).message,
+            });
+          }
+        }
+      }
+    }
+
+    const legacyRoots = await this.getLegacyGlobalRoots();
+    const legacyGlobalDirs = legacyRoots.map(
+      (legacyRoot) => legacyRoot.globalDir,
+    );
+    if (legacyGlobalDirs.length === 0) {
+      return results;
+    }
+
+    for (const pnpmShimDir of pnpmShimDirs) {
+      try {
+        const entries = await plugins.fs.readdir(pnpmShimDir, {
+          withFileTypes: true,
+        });
+        for (const entry of entries) {
+          if (!entry.isFile() || currentBinNames.has(entry.name)) {
+            continue;
+          }
+
+          const filePath = plugins.path.join(pnpmShimDir, entry.name);
+          let content = "";
+          try {
+            content = await plugins.fs.readFile(filePath, "utf8");
+          } catch {
+            continue;
+          }
+
+          if (
+            !legacyGlobalDirs.some((legacyGlobalDir) =>
+              content.includes(legacyGlobalDir),
+            )
+          ) {
+            continue;
+          }
+
+          try {
+            await plugins.fs.rm(filePath, { force: true });
+            results.push({
+              name: formatShimName(pnpmShimDir, entry.name),
+              action: "removed",
+            });
+          } catch (error) {
+            results.push({
+              name: formatShimName(pnpmShimDir, entry.name),
+              action: "skipped",
+              reason: (error as Error).message,
+            });
+          }
+        }
+      } catch (error) {
+        results.push({
+          name: pnpmShimDir,
+          action: "skipped",
+          reason: (error as Error).message,
+        });
+      }
+    }
+
+    return results;
   }
 
   public async getLatestVersion(
     packageName: string,
-    registries = ["https://verdaccio.lossless.digital", "https://registry.npmjs.org"],
+    registries = [
+      "https://verdaccio.lossless.digital",
+      "https://registry.npmjs.org",
+    ],
   ): Promise<string | null> {
     for (const registry of registries) {
-      const latest = await this.getLatestVersionFromRegistry(registry, packageName);
+      const latest = await this.getLatestVersionFromRegistry(
+        registry,
+        packageName,
+      );
       if (latest) {
         return latest;
       }
@@ -99,23 +371,60 @@ export class PackageManagerUtil {
     return null;
   }
 
-  public async installLatest(packageName: string): Promise<boolean> {
+  public async installLatest(
-    const packageSpecifier = `${packageName}@latest`;
+    packageName: string,
+    version = "latest",
+  ): Promise<boolean> {
+    const pnpmCommand = await this.getPnpmCommand();
+    if (!pnpmCommand) {
+      return false;
+    }
+
+    const packageSpecifier = `${packageName}@${version}`;
     console.log(`  Installing ${packageSpecifier} via pnpm...`);
 
     try {
-      const result = await this.shell.exec(`pnpm add -g ${shellQuote(packageSpecifier)}`);
+      const result = await this.shell.exec(
+        `${pnpmCommand} add -g ${shellQuote(packageSpecifier)}`,
+      );
       return result.exitCode === 0;
     } catch {
       return false;
     }
   }
 
+  public async updatePnpm(targetVersion: string): Promise<boolean> {
+    const pnpmCommand = await this.getPnpmCommand();
+    if (!pnpmCommand) {
+      return false;
+    }
+
+    const neutralDir = process.env.PNPM_HOME || "/tmp";
+
+    try {
+      const result = await this.shell.exec(
+        `${pnpmCommand} --dir ${shellQuote(neutralDir)} self-update ${shellQuote(targetVersion)}`,
+      );
+      this.pnpmCommand = undefined;
+      const currentVersion = await this.getCurrentPnpmVersion();
+      return (
+        result.exitCode === 0 &&
+        !this.isNewerVersion(currentVersion, targetVersion)
+      );
+    } catch {
+      return false;
+    }
+  }
+
   public isNewerVersion(current: string, latest: string): boolean {
     const currentParts = normalizeSemver(current);
     const latestParts = normalizeSemver(latest);
 
-    for (let i = 0; i < Math.max(currentParts.length, latestParts.length); i++) {
+    for (
+      let i = 0;
+      i < Math.max(currentParts.length, latestParts.length);
+      i++
+    ) {
       const currentPart = currentParts[i] || 0;
       const latestPart = latestParts[i] || 0;
       if (latestPart > currentPart) return true;
@@ -127,7 +436,10 @@ export class PackageManagerUtil {
 
   private async getCurrentPnpmVersion(): Promise<string> {
     try {
-      const result = await this.shell.execSilent("pnpm --version 2>/dev/null");
+      const result = await this.execPnpmSilent("--version 2>/dev/null");
+      if (!result) {
+        return "unknown";
+      }
       const versionMatch = result.stdout.trim().match(/(\d+\.\d+\.\d+)/);
       return versionMatch?.[1] || "unknown";
     } catch {
@@ -135,6 +447,265 @@ export class PackageManagerUtil {
     }
   }
 
+  private async getPnpmCommand(): Promise<string | null> {
+    if (this.pnpmCommand !== undefined) {
+      return this.pnpmCommand;
+    }
+
+    const candidates = [
+      "pnpm --pm-on-fail=ignore",
+      "pnpm --config.manage-package-manager-versions=false",
+      "pnpm",
+    ];
+
+    for (const candidate of candidates) {
+      try {
+        const result = await this.shell.execSilent(
+          `${candidate} --version 2>/dev/null`,
+        );
+        if (result.exitCode === 0 && Boolean(result.stdout.trim())) {
+          this.pnpmCommand = candidate;
+          return this.pnpmCommand;
+        }
+      } catch {
+        // Try the next supported pnpm invocation form.
+      }
+    }
+
+    this.pnpmCommand = null;
+    return this.pnpmCommand;
+  }
+
+  private async execPnpmSilent(commandArgs: string): Promise<any | null> {
+    const pnpmCommand = await this.getPnpmCommand();
+    if (!pnpmCommand) {
+      return null;
+    }
+    return this.shell.execSilent(`${pnpmCommand} ${commandArgs}`);
+  }
+
+  private async getPnpmListProjects(): Promise<IPnpmListProject[]> {
+    try {
+      const result = await this.execPnpmSilent(
+        "list -g --depth=0 --json 2>/dev/null || true",
+      );
+      const output = result?.stdout.trim();
+      if (!output) {
+        return [];
+      }
+
+      const data = JSON.parse(output);
+      return Array.isArray(data) ? data : [data];
+    } catch {
+      return [];
+    }
+  }
+
+  private async getCurrentGlobalDir(): Promise<string | null> {
+    const listProjects = await this.getPnpmListProjects();
+    for (const listProject of listProjects) {
+      if (typeof listProject.path === "string" && listProject.path.length > 0) {
+        return normalizeGlobalDir(listProject.path);
+      }
+    }
+
+    try {
+      const result = await this.execPnpmSilent("root -g 2>/dev/null");
+      const output = result?.stdout.trim();
+      return output ? normalizeGlobalDir(output) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  private async getCurrentInstalledPackages(): Promise<IInstalledPackage[]> {
+    const listProjects = await this.getPnpmListProjects();
+    const currentGlobalDir = await this.getCurrentGlobalDir();
+    const packageMap = new Map<string, IInstalledPackage>();
+
+    for (const listProject of listProjects) {
+      const globalDir = listProject.path
+        ? normalizeGlobalDir(listProject.path)
+        : currentGlobalDir || undefined;
+      const dependencies = listProject.dependencies || {};
+      for (const [name, info] of Object.entries(dependencies)) {
+        if (!name.startsWith("@git.zone/")) {
+          continue;
+        }
+        packageMap.set(name, {
+          name,
+          version: getDependencyVersion(info),
+          globalDir,
+          packagePath: getDependencyPackagePath(info),
+          legacy: false,
+        });
+      }
+    }
+
+    if (packageMap.size === 0 && currentGlobalDir) {
+      const currentRootInfo = await this.inspectGlobalRoot(
+        currentGlobalDir,
+        true,
+      );
+      for (const packageInfo of currentRootInfo.packages) {
+        packageMap.set(packageInfo.name, packageInfo);
+      }
+    }
+
+    return Array.from(packageMap.values());
+  }
+
+  private async inspectGlobalRoot(
+    globalDir: string,
+    current: boolean,
+  ): Promise<ILegacyGlobalRootInfo> {
+    const normalizedGlobalDir = normalizeGlobalDir(globalDir);
+    const rootPackageJson = await readJson(
+      plugins.path.join(normalizedGlobalDir, "package.json"),
+    );
+    const dependencies = getDependencyMap(rootPackageJson?.dependencies);
+    const packageMap = new Map<string, IInstalledPackage>();
+
+    for (const [name, spec] of Object.entries(dependencies)) {
+      if (!name.startsWith("@git.zone/")) {
+        continue;
+      }
+      packageMap.set(name, {
+        name,
+        version:
+          (await this.getInstalledPackageVersion(normalizedGlobalDir, name)) ||
+          normalizeDependencySpec(spec),
+        globalDir: normalizedGlobalDir,
+        packagePath: getPackagePath(normalizedGlobalDir, name),
+        legacy: !current,
+      });
+    }
+
+    const gitZoneScopeDir = plugins.path.join(
+      normalizedGlobalDir,
+      "node_modules",
+      "@git.zone",
+    );
+    try {
+      const entries = await plugins.fs.readdir(gitZoneScopeDir, {
+        withFileTypes: true,
+      });
+      for (const entry of entries) {
+        if (!entry.isDirectory() && !entry.isSymbolicLink()) {
+          continue;
+        }
+        const name = `@git.zone/${entry.name}`;
+        packageMap.set(name, {
+          name,
+          version:
+            (await this.getInstalledPackageVersion(
+              normalizedGlobalDir,
+              name,
+            )) || "unknown",
+          globalDir: normalizedGlobalDir,
+          packagePath: getPackagePath(normalizedGlobalDir, name),
+          legacy: !current,
+        });
+      }
+    } catch {
+      // A pnpm global root may be empty or may not have node_modules materialized yet.
+    }
+
+    const dependencyNames = Object.keys(dependencies);
+    const unmanagedPackageNames = dependencyNames.filter(
+      (packageName) => !packageName.startsWith("@git.zone/"),
+    );
+
+    return {
+      globalDir: normalizedGlobalDir,
+      packages: Array.from(packageMap.values()).sort((packageA, packageB) =>
+        packageA.name.localeCompare(packageB.name),
+      ),
+      unmanagedPackageNames,
+      safeToDelete:
+        !current &&
+        dependencyNames.length > 0 &&
+        unmanagedPackageNames.length === 0,
+    };
+  }
+
+  private async getInstalledPackageVersion(
+    globalDir: string,
+    packageName: string,
+  ): Promise<string | null> {
+    const packageJson = await readJson(
+      plugins.path.join(
+        globalDir,
+        "node_modules",
+        ...packageName.split("/"),
+        "package.json",
+      ),
+    );
+    return typeof packageJson?.version === "string"
+      ? packageJson.version
+      : null;
+  }
+
+  private async getShimReferences(
+    legacyGlobalDir: string,
+  ): Promise<string[] | null> {
+    const pnpmShimDirs = await this.getPnpmShimDirs();
+    if (!pnpmShimDirs) {
+      return null;
+    }
+
+    const references: string[] = [];
+    for (const pnpmShimDir of pnpmShimDirs) {
+      try {
+        const entries = await plugins.fs.readdir(pnpmShimDir, {
+          withFileTypes: true,
+        });
+
+        for (const entry of entries) {
+          if (!entry.isFile()) {
+            continue;
+          }
+
+          const filePath = plugins.path.join(pnpmShimDir, entry.name);
+          try {
+            const content = await plugins.fs.readFile(filePath, "utf8");
+            if (content.includes(legacyGlobalDir)) {
+              references.push(formatShimName(pnpmShimDir, entry.name));
+            }
+          } catch {
+            // Ignore unreadable or non-text files in PNPM_HOME.
+          }
+        }
+      } catch {
+        return null;
+      }
+    }
+
+    return references;
+  }
+
+  private async getPnpmShimDirs(): Promise<string[] | null> {
+    const pnpmHome = process.env.PNPM_HOME;
+    if (!pnpmHome) {
+      return null;
+    }
+
+    const candidateDirs = [plugins.path.join(pnpmHome, "bin"), pnpmHome];
+    const shimDirs: string[] = [];
+    for (const candidateDir of candidateDirs) {
+      try {
+        const stat = await plugins.fs.stat(candidateDir);
+        if (stat.isDirectory()) {
+          shimDirs.push(normalizePath(candidateDir));
+        }
+      } catch {
+        // Ignore missing pnpm shim directories.
+      }
+    }
+
+    return shimDirs.length > 0 ? Array.from(new Set(shimDirs)) : null;
+  }
+
   private async getLatestVersionFromRegistry(
     registry: string,
     packageName: string,
@@ -164,6 +735,125 @@ export class PackageManagerUtil {
   }
 }
 
+async function readJson(filePath: string): Promise<any | null> {
+  try {
+    const content = await plugins.fs.readFile(filePath, "utf8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+function getDependencyMap(value: unknown): Record<string, string> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  return value as Record<string, string>;
+}
+
+function getDependencyVersion(info: any): string {
+  if (info && typeof info === "object" && typeof info.version === "string") {
+    return info.version;
+  }
+  if (typeof info === "string") {
+    return normalizeDependencySpec(info);
+  }
+  return "unknown";
+}
+
+function getDependencyPackagePath(info: any): string | undefined {
+  return info && typeof info === "object" && typeof info.path === "string"
+    ? normalizePath(info.path)
+    : undefined;
+}
+
+function getPackagePath(globalDir: string, packageName: string): string {
+  return plugins.path.join(
+    globalDir,
+    "node_modules",
+    ...packageName.split("/"),
+  );
+}
+
+function getPackageBinNames(packageName: string, packageJson: any): string[] {
+  const bin = packageJson?.bin;
+  if (typeof bin === "string") {
+    return [getDefaultBinName(packageName)];
+  }
+  if (!bin || typeof bin !== "object" || Array.isArray(bin)) {
+    return [];
+  }
+  return Object.keys(bin)
+    .filter((binName) => binName.length > 0)
+    .sort();
+}
+
+function getDefaultBinName(packageName: string): string {
+  const packageNameParts = packageName.split("/");
+  return packageNameParts[packageNameParts.length - 1] || packageName;
+}
+
+function getNodeModulesDir(packagePath: string, packageName: string): string {
+  return packageName.startsWith("@")
+    ? plugins.path.dirname(plugins.path.dirname(packagePath))
+    : plugins.path.dirname(packagePath);
+}
+
+function rewriteShimForPnpmHome(content: string): string {
+  const targetMatch = content.match(/^# cmd-shim-target=(.+)$/m);
+  if (!targetMatch?.[1]) {
+    return content;
+  }
+
+  const absoluteTarget = `"${escapeDoubleQuotedShell(targetMatch[1])}"`;
+  return content.replace(
+    /"\$basedir\/(?:\.\.\/)+store\/[^"\n]+"/g,
+    absoluteTarget,
+  );
+}
+
+function escapeDoubleQuotedShell(value: string): string {
+  return value.replace(/["\\$`]/g, "\\$&");
+}
+
+function formatShimName(pnpmShimDir: string, binName: string): string {
+  const pnpmHome = process.env.PNPM_HOME;
+  if (!pnpmHome) {
+    return binName;
+  }
+
+  const relativeName = plugins.path.relative(
+    pnpmHome,
+    plugins.path.join(pnpmShimDir, binName),
+  );
+  return relativeName && !relativeName.startsWith("..")
+    ? relativeName
+    : binName;
+}
+
+function normalizeDependencySpec(spec: unknown): string {
+  if (typeof spec !== "string" || spec.length === 0) {
+    return "unknown";
+  }
+  const versionMatch = spec.match(/\d+\.\d+\.\d+(?:[-+][\w.-]+)?/);
+  return versionMatch?.[0] || spec;
+}
+
+function normalizeGlobalDir(globalDir: string): string {
+  const normalizedPath = normalizePath(globalDir);
+  return plugins.path.basename(normalizedPath) === "node_modules"
+    ? plugins.path.dirname(normalizedPath)
+    : normalizedPath;
+}
+
+function normalizePath(filePath: string): string {
+  return plugins.path.resolve(filePath).replace(/\/+$/, "");
+}
+
+function pathsAreEqual(pathA: string, pathB: string): boolean {
+  return normalizePath(pathA) === normalizePath(pathB);
+}
+
 function normalizeSemver(version: string): number[] {
   return version
     .replace(/^[^\d]*/, "")

ts/mod_tools/index.ts

@@ -51,7 +51,9 @@ async function runUpdate(argvArg: any, mode: ICliMode): Promise<void> {
 
   const pnpmInfo = await pmUtil.getPnpmVersionInfo();
   if (!pnpmInfo.available) {
-    console.log("pnpm is required for gitzone tools update, but it was not found.");
+    console.log(
+      "pnpm is required for gitzone tools update, but it was not found.",
+    );
     return;
   }
 
@@ -59,18 +61,25 @@ async function runUpdate(argvArg: any, mode: ICliMode): Promise<void> {
   console.log("  Name     Current     Latest      Status");
   console.log("  ----------------------------------------------");
   const latestPnpm = (pnpmInfo.latestVersion || "unknown").padEnd(12);
-  const pnpmStatus = pnpmInfo.latestVersion === null
+  const pnpmStatus =
-    ? "? Version unknown"
+    pnpmInfo.latestVersion === null
-    : pnpmInfo.needsUpdate
+      ? "? Version unknown"
-      ? "Update available"
+      : pnpmInfo.needsUpdate
-      : "Up to date";
+        ? "Update available"
-  console.log(`  ${"pnpm".padEnd(9)}${pnpmInfo.currentVersion.padEnd(12)}${latestPnpm}${pnpmStatus}`);
+        : "Up to date";
+  console.log(
+    `  ${"pnpm".padEnd(9)}${pnpmInfo.currentVersion.padEnd(12)}${latestPnpm}${pnpmStatus}`,
+  );
   console.log("");
 
   if (verbose) {
     console.log("Using pnpm as the supported global package manager.\n");
   }
 
+  const pnpmNeedsUpdate = Boolean(
+    pnpmInfo.latestVersion && pnpmInfo.needsUpdate,
+  );
+
   const selfUpdated = await handleSelfUpdate(pmUtil, mode);
   if (selfUpdated) {
     return;
@@ -78,39 +87,79 @@ async function runUpdate(argvArg: any, mode: ICliMode): Promise<void> {
 
   const installedPackages = await pmUtil.getInstalledPackages();
   const packageInfos = await getPackageUpdateInfos(pmUtil, installedPackages);
+  const legacyRoots = await pmUtil.getLegacyGlobalRoots();
+  const legacyCleanupNeeded = legacyRoots.length > 0;
 
   if (packageInfos.length === 0) {
     console.log("No managed @git.zone packages found installed globally.");
-    return;
+  } else {
-  }
+    console.log("Installed @git.zone packages:\n");
-
-  console.log("Installed @git.zone packages:\n");
-  console.log("  Package                      Current     Latest      Status");
-  console.log("  ------------------------------------------------------------");
-  for (const packageInfo of packageInfos) {
-    const status = packageInfo.latestVersion === "unknown"
-      ? "? Version unknown"
-      : packageInfo.needsUpdate
-        ? "Update available"
-        : "Up to date";
     console.log(
-      `  ${packageInfo.name.padEnd(28)}${packageInfo.currentVersion.padEnd(12)}${packageInfo.latestVersion.padEnd(12)}${status}`,
+      "  Package                      Current     Latest      Status",
     );
+    console.log(
+      "  ------------------------------------------------------------",
+    );
+    for (const packageInfo of packageInfos) {
+      console.log(
+        `  ${packageInfo.name.padEnd(28)}${packageInfo.currentVersion.padEnd(12)}${packageInfo.latestVersion.padEnd(12)}${getPackageStatus(packageInfo)}`,
+      );
+    }
+    console.log("");
+
+    await printMissingPackages(pmUtil, installedPackages);
   }
-  console.log("");
 
-  await printMissingPackages(pmUtil, installedPackages);
+  const packagesToUpdate = packageInfos.filter(
+    (packageInfo) => packageInfo.needsUpdate || packageInfo.needsMigration,
+  );
+  const packagesToMigrate = packageInfos.filter(
+    (packageInfo) => packageInfo.needsMigration,
+  );
 
-  const packagesToUpdate = packageInfos.filter((packageInfo) => packageInfo.needsUpdate);
+  if (packagesToMigrate.length > 0) {
-  if (packagesToUpdate.length === 0) {
+    console.log(
+      `Detected ${packagesToMigrate.length} package(s) in legacy pnpm global roots.`,
+    );
+    if (verbose) {
+      for (const packageInfo of packagesToMigrate) {
+        console.log(
+          `  ${packageInfo.name} -> ${packageInfo.globalDir || "unknown"}`,
+        );
+      }
+    }
+    console.log("");
+  } else if (legacyCleanupNeeded) {
+    console.log(
+      `Detected ${legacyRoots.length} legacy pnpm global root(s) for cleanup.`,
+    );
+    if (verbose) {
+      for (const legacyRoot of legacyRoots) {
+        console.log(`  ${legacyRoot.globalDir}`);
+      }
+    }
+    console.log("");
+  }
+
+  if (
+    packagesToUpdate.length === 0 &&
+    !pnpmNeedsUpdate &&
+    !legacyCleanupNeeded
+  ) {
     console.log("All managed packages are up to date.");
     return;
   }
 
-  console.log(`Found ${packagesToUpdate.length} package(s) with available updates.\n`);
+  const actionCount =
+    packagesToUpdate.length +
+    (pnpmNeedsUpdate ? 1 : 0) +
+    (legacyCleanupNeeded ? 1 : 0);
+  console.log(`Found ${actionCount} update action(s).\n`);
 
   if (!mode.yes && !mode.interactive) {
-    console.log("Run gitzone tools update -y to update without prompts.");
+    console.log(
+      "Run gitzone tools update -y to update, migrate, and cleanup without prompts.",
+    );
     return;
   }
 
@@ -120,7 +169,7 @@ async function runUpdate(argvArg: any, mode: ICliMode): Promise<void> {
     const answer = await interactInstance.askQuestion({
       type: "confirm",
       name: "confirmUpdate",
-      message: "Do you want to update these packages?",
+      message: "Do you want to update, migrate, and cleanup these tools?",
       default: true,
     });
     shouldUpdate = answer.value === true;
@@ -131,7 +180,35 @@ async function runUpdate(argvArg: any, mode: ICliMode): Promise<void> {
     return;
   }
 
-  await installPackages(pmUtil, packagesToUpdate.map((packageInfo) => packageInfo.name), "updated");
+  if (pnpmNeedsUpdate && pnpmInfo.latestVersion) {
+    console.log(`Updating pnpm to ${pnpmInfo.latestVersion}...`);
+    const success = await pmUtil.updatePnpm(pnpmInfo.latestVersion);
+    console.log(
+      success
+        ? "pnpm updated successfully.\n"
+        : "pnpm update failed. Continuing with package updates.\n",
+    );
+  }
+
+  const installResult =
+    packagesToUpdate.length > 0
+      ? await installPackages(
+          pmUtil,
+          packagesToUpdate.map((packageInfo) => ({
+            name: packageInfo.name,
+            version:
+              packageInfo.latestVersion !== "unknown"
+                ? packageInfo.latestVersion
+                : undefined,
+          })),
+          "updated",
+        )
+      : { successCount: 0, failCount: 0 };
+
+  if (packagesToUpdate.length > 0 || legacyCleanupNeeded) {
+    await syncCurrentGlobalShims(pmUtil);
+    await cleanupLegacyInstalls(pmUtil);
+  }
 }
 
 async function runInstall(argvArg: any, mode: ICliMode): Promise<void> {
@@ -142,7 +219,9 @@ async function runInstall(argvArg: any, mode: ICliMode): Promise<void> {
 
   const pnpmAvailable = await pmUtil.detectPnpm();
   if (!pnpmAvailable) {
-    console.log("pnpm is required for gitzone tools install, but it was not found.");
+    console.log(
+      "pnpm is required for gitzone tools install, but it was not found.",
+    );
     return;
   }
 
@@ -151,8 +230,12 @@ async function runInstall(argvArg: any, mode: ICliMode): Promise<void> {
   }
 
   const installedPackages = await pmUtil.getInstalledPackages();
-  const installedNames = new Set(installedPackages.map((packageInfo) => packageInfo.name));
+  const installedNames = new Set(
-  const missingPackages = GITZONE_PACKAGES.filter((packageName) => !installedNames.has(packageName));
+    installedPackages.map((packageInfo) => packageInfo.name),
+  );
+  const missingPackages = GITZONE_PACKAGES.filter(
+    (packageName) => !installedNames.has(packageName),
+  );
 
   if (missingPackages.length === 0) {
     console.log("All managed @git.zone packages are already installed.");
@@ -163,7 +246,9 @@ async function runInstall(argvArg: any, mode: ICliMode): Promise<void> {
 
   if (!mode.yes && !mode.interactive) {
     await printPackageListWithLatest(pmUtil, missingPackages);
-    console.log("Run gitzone tools install -y to install all missing packages without prompts.");
+    console.log(
+      "Run gitzone tools install -y to install all missing packages without prompts.",
+    );
     return;
   }
 
@@ -210,7 +295,9 @@ async function handleSelfUpdate(
     return false;
   }
 
-  console.log(`  @git.zone/cli  ${currentVersion} -> ${latestVersion}  Update available\n`);
+  console.log(
+    `  @git.zone/cli  ${currentVersion} -> ${latestVersion}  Update available\n`,
+  );
 
   if (!mode.yes && !mode.interactive) {
     console.log("Run gitzone tools update -y to update gitzone first.");
@@ -236,11 +323,15 @@ async function handleSelfUpdate(
 
   const success = await pmUtil.installLatest("@git.zone/cli");
   if (!success) {
-    console.log("\ngitzone self-update failed. Continuing with the current version.\n");
+    console.log(
+      "\ngitzone self-update failed. Continuing with the current version.\n",
+    );
     return false;
   }
 
-  console.log("\ngitzone has been updated. Re-run gitzone tools update to check remaining packages.");
+  console.log(
+    "\ngitzone has been updated. Re-run gitzone tools update to check remaining packages.",
+  );
   return true;
 }
 
@@ -261,17 +352,39 @@ async function getPackageUpdateInfos(
       needsUpdate: latestVersion
         ? pmUtil.isNewerVersion(installedPackage.version, latestVersion)
         : false,
+      needsMigration: installedPackage.legacy === true,
+      globalDir: installedPackage.globalDir,
     });
   }
   return packageInfos;
 }
 
+function getPackageStatus(packageInfo: IPackageUpdateInfo): string {
+  if (packageInfo.latestVersion === "unknown") {
+    return "? Version unknown";
+  }
+  if (packageInfo.needsUpdate && packageInfo.needsMigration) {
+    return "Update + migrate";
+  }
+  if (packageInfo.needsUpdate) {
+    return "Update available";
+  }
+  if (packageInfo.needsMigration) {
+    return "Migrate global root";
+  }
+  return "Up to date";
+}
+
 async function printMissingPackages(
   pmUtil: PackageManagerUtil,
   installedPackages: IInstalledPackage[],
 ): Promise<void> {
-  const installedNames = new Set(installedPackages.map((packageInfo) => packageInfo.name));
+  const installedNames = new Set(
-  const missingPackages = GITZONE_PACKAGES.filter((packageName) => !installedNames.has(packageName));
+    installedPackages.map((packageInfo) => packageInfo.name),
+  );
+  const missingPackages = GITZONE_PACKAGES.filter(
+    (packageName) => !installedNames.has(packageName),
+  );
   if (missingPackages.length === 0) {
     return;
   }
@@ -296,14 +409,18 @@ async function printPackageListWithLatest(
 
 async function installPackages(
   pmUtil: PackageManagerUtil,
-  packageNames: string[],
+  packageSpecs: Array<string | { name: string; version?: string }>,
   action: "installed" | "updated",
-): Promise<void> {
+): Promise<{ successCount: number; failCount: number }> {
   let successCount = 0;
   let failCount = 0;
 
-  for (const packageName of packageNames) {
+  for (const packageSpec of packageSpecs) {
-    const success = await pmUtil.installLatest(packageName);
+    const packageName =
+      typeof packageSpec === "string" ? packageSpec : packageSpec.name;
+    const packageVersion =
+      typeof packageSpec === "string" ? undefined : packageSpec.version;
+    const success = await pmUtil.installLatest(packageName, packageVersion);
     if (success) {
       console.log(`  ${packageName} ${action} successfully`);
       successCount++;
@@ -319,6 +436,56 @@ async function installPackages(
   } else {
     console.log(`${successCount} package(s) ${action}, ${failCount} failed.`);
   }
+
+  return { successCount, failCount };
+}
+
+async function cleanupLegacyInstalls(
+  pmUtil: PackageManagerUtil,
+): Promise<void> {
+  const cleanupResults = await pmUtil.cleanupLegacyGlobalRoots();
+  if (cleanupResults.length === 0) {
+    return;
+  }
+
+  console.log("Legacy pnpm global roots:\n");
+  for (const cleanupResult of cleanupResults) {
+    if (cleanupResult.deleted) {
+      console.log(`  ${cleanupResult.globalDir} deleted`);
+    } else {
+      console.log(
+        `  ${cleanupResult.globalDir} kept (${cleanupResult.reason || "unknown reason"})`,
+      );
+    }
+  }
+  console.log("");
+}
+
+async function syncCurrentGlobalShims(
+  pmUtil: PackageManagerUtil,
+): Promise<void> {
+  const shimResults = await pmUtil.syncCurrentGlobalShims();
+  const changedResults = shimResults.filter(
+    (shimResult) => shimResult.action !== "skipped",
+  );
+  const skippedResults = shimResults.filter(
+    (shimResult) => shimResult.action === "skipped",
+  );
+
+  if (changedResults.length === 0 && skippedResults.length === 0) {
+    return;
+  }
+
+  console.log("Command shims:\n");
+  for (const shimResult of changedResults) {
+    console.log(`  ${shimResult.name} ${shimResult.action}`);
+  }
+  for (const shimResult of skippedResults) {
+    console.log(
+      `  ${shimResult.name} skipped (${shimResult.reason || "unknown reason"})`,
+    );
+  }
+  console.log("");
 }
 
 export function showHelp(mode?: ICliMode): void {
@@ -327,12 +494,21 @@ export function showHelp(mode?: ICliMode): void {
       name: "gitzone tools",
       usage: "gitzone tools <command> [options]",
       commands: [
-        { name: "update", description: "Check and update globally installed @git.zone packages" },
+        {
-        { name: "install", description: "Install missing managed @git.zone packages" },
+          name: "update",
+          description: "Check and update globally installed @git.zone packages",
+        },
+        {
+          name: "install",
+          description: "Install missing managed @git.zone packages",
+        },
       ],
       flags: [
         { flag: "-y, --yes", description: "Run without confirmation prompts" },
-        { flag: "-v, --verbose", description: "Show package manager diagnostics" },
+        {
+          flag: "-v, --verbose",
+          description: "Show package manager diagnostics",
+        },
       ],
       packageManager: "pnpm",
       managedPackages: GITZONE_PACKAGES,
@@ -344,8 +520,12 @@ export function showHelp(mode?: ICliMode): void {
   console.log("Usage: gitzone tools <command> [options]");
   console.log("");
   console.log("Commands:");
-  console.log("  update             Check and update globally installed @git.zone packages");
+  console.log(
-  console.log("  install            Install missing managed @git.zone packages");
+    "  update             Check and update globally installed @git.zone packages",
+  );
+  console.log(
+    "  install            Install missing managed @git.zone packages",
+  );
   console.log("");
   console.log("Options:");
   console.log("  -y, --yes          Run without confirmation prompts");

ts/plugins.ts

@@ -2,6 +2,7 @@ import * as smartlog from '@push.rocks/smartlog';
 import * as smartlogDestinationLocal from '@push.rocks/smartlog-destination-local';
 import * as smartconfig from '@push.rocks/smartconfig';
 import * as path from 'path';
+import * as fs from 'node:fs/promises';
 import * as projectinfo from '@push.rocks/projectinfo';
 import * as smartcli from '@push.rocks/smartcli';
 import * as smartpath from '@push.rocks/smartpath';
@@ -22,6 +23,7 @@ export {
   smartlogDestinationLocal,
   smartconfig,
   path,
+  fs,
   projectinfo,
   smartcli,
   smartpath,

tsconfig.json

@@ -5,7 +5,6 @@
     "moduleResolution": "NodeNext",
     "esModuleInterop": true,
     "verbatimModuleSyntax": true,
-    "baseUrl": ".",
     "paths": {}
   },
   "exclude": ["dist_*/**/*.d.ts"]