zelari-code 1.0.2 → 1.1.0

package/dist/cli/utils/doctor.js

@@ -0,0 +1,287 @@
+/**
+ * doctor.ts — `zelari-code doctor` diagnostic.
+ *
+ * Run after a fresh install (or when something looks wrong) to check:
+ *   1. Bin shim health (does `zelari-code.cmd` / `zelari-code` exist
+ *      in the npm global prefix, and does it reference the right
+ *      package install?).
+ *   2. Node availability (`node` on PATH, version >= engines.node).
+ *   3. CLI bundle presence (did `npm run build:cli` produce
+ *      `dist/cli/main.bundled.js`?).
+ *   4. Runtime deps (ink / react / zod / ink-text-input resolvable
+ *      from the package root).
+ *   5. @zelari/core dependency (only checked if it appears in the
+ *      package's deps or devDeps — it's a build-time dep for the
+ *      workspace, and a runtime dep only for the source/tsx fallback
+ *      path in bin/zelari-code.js).
+ *   6. PATH includes the npm global prefix.
+ *
+ * Output is human-readable, with one line per check + a trailing
+ * summary. Non-zero exit code if any critical check fails so this
+ * can be used in CI / install scripts.
+ *
+ * The function never throws: it catches all per-check errors and
+ * reports them as "FAIL" with the error message. The final return
+ * value tells the caller whether the install is healthy.
+ *
+ * @see scripts/postinstall.mjs — the install-time shim check
+ * @see src/cli/updater.ts — the self-update mechanism
+ */
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, readlinkSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+const require = createRequire(import.meta.url);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// src/cli/utils/doctor.ts → <pkg>/src/cli/utils/doctor.ts
+// We need <pkg> root. In dev (tsx) this is src/cli/utils/, in prod (bundled) it's dist/cli/utils/.
+// In both cases we want the package root: that's `../../` from src/cli/utils, and `../../../` from dist/cli/utils/...
+// Simplest: walk up until we find package.json with our name.
+const packageRoot = findPackageRoot(__dirname);
+function findPackageRoot(start) {
+    let dir = start;
+    // Walk at most 6 levels up (src/cli/utils -> src/cli -> src -> root, dist/cli/utils -> dist/cli -> dist -> root).
+    for (let i = 0; i < 6; i += 1) {
+        const candidate = path.join(dir, "package.json");
+        if (existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, "utf8"));
+                if (pkg.name === "zelari-code")
+                    return dir;
+            }
+            catch {
+                // ignore
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // Fallback: assume standard layout.
+    return path.resolve(__dirname, "..", "..", "..");
+}
+const OK = (message) => ({
+    ok: true,
+    message,
+    severity: "critical",
+});
+const FAIL = (message, severity = "critical") => ({
+    ok: false,
+    message,
+    severity,
+});
+const WARN = (message) => ({
+    ok: false,
+    message,
+    severity: "warn",
+});
+/** Run a shell command and return trimmed stdout. Empty string on failure. */
+function tryExec(cmd) {
+    try {
+        return execSync(cmd, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+/** Read the installed package.json (for name + version + bin path). */
+function readPackageJson() {
+    try {
+        const pkgPath = path.join(packageRoot, "package.json");
+        return JSON.parse(readFileSync(pkgPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve the npm global prefix. Empty string on failure. */
+function getGlobalPrefix() {
+    return ((process.env.npm_config_prefix ||
+        process.env.NPM_CONFIG_PREFIX ||
+        "").trim() || tryExec("npm prefix -g"));
+}
+/** Check the bin shim in the global prefix. */
+function checkShim(pkgName) {
+    const prefix = getGlobalPrefix();
+    if (!prefix) {
+        return WARN("npm global prefix not detectable (run inside an npm context)");
+    }
+    const isWin = process.platform === "win32";
+    const shimName = isWin ? "zelari-code.cmd" : "zelari-code";
+    const shimPath = path.join(prefix, shimName);
+    if (!existsSync(shimPath)) {
+        return FAIL(`shim not found at ${shimPath}\n` +
+            `         fix:  npm install -g ${pkgName}@latest --force`);
+    }
+    try {
+        const st = statSync(shimPath);
+        if (isWin) {
+            const content = readFileSync(shimPath, "utf8");
+            if (content.includes(`${pkgName}\\bin\\`) ||
+                content.includes(`${pkgName}/bin/`)) {
+                return OK(`shim OK at ${shimPath} (${st.size} bytes)`);
+            }
+            return FAIL(`shim at ${shimPath} does not reference ${pkgName}/bin/\n` +
+                `         fix:  npm install -g ${pkgName}@latest --force`);
+        }
+        let target;
+        try {
+            target = readlinkSync(shimPath);
+        }
+        catch {
+            return FAIL(`shim at ${shimPath} is not a symlink (POSIX global installs should be symlinks)\n` +
+                `         fix:  npm install -g ${pkgName}@latest --force`);
+        }
+        const resolved = path.resolve(path.dirname(shimPath), target);
+        const expected = path.join(prefix, "node_modules", pkgName, "bin", "zelari-code.js");
+        if (resolved === expected) {
+            return OK(`shim OK at ${shimPath} → ${resolved}`);
+        }
+        return FAIL(`shim at ${shimPath} points to ${resolved}\n` +
+            `         expected ${expected}\n` +
+            `         fix:  npm install -g ${pkgName}@latest --force`);
+    }
+    catch (err) {
+        return FAIL(`could not inspect shim: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Check that node is on PATH and meets the engines requirement. */
+function checkNode(pkg) {
+    const raw = tryExec("node --version");
+    if (!raw) {
+        return FAIL("`node` not found on PATH");
+    }
+    // raw is like "v20.11.1"
+    const m = raw.match(/^v?(\d+)\.(\d+)\.(\d+)/);
+    if (!m) {
+        return WARN(`could not parse node version: ${raw}`);
+    }
+    const major = Number(m[1]);
+    if (major < 20) {
+        return FAIL(`node ${raw} is older than the required engines.node (>= 20.0.0)`);
+    }
+    return OK(`node ${raw}`);
+}
+/** Check the CLI bundle exists. */
+function checkBundle() {
+    const bundle = path.join(packageRoot, "dist", "cli", "main.bundled.js");
+    if (!existsSync(bundle)) {
+        return FAIL(`dist/cli/main.bundled.js missing at ${bundle}\n` +
+            `         fix:  npm run build:cli   (then reinstall or run via tsx)`);
+    }
+    try {
+        const st = statSync(bundle);
+        return OK(`bundle OK (${(st.size / 1024 / 1024).toFixed(2)} MB)`);
+    }
+    catch (err) {
+        return FAIL(`could not stat bundle: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Check each runtime dep is resolvable. */
+function checkRuntimeDeps() {
+    const required = ["react", "react-dom", "ink", "ink-text-input", "zod"];
+    const missing = [];
+    for (const dep of required) {
+        try {
+            // createRequire from the package root — this is what `node bin/zelari-code.js` uses.
+            const localReq = createRequire(path.join(packageRoot, "package.json"));
+            localReq.resolve(dep);
+        }
+        catch {
+            missing.push(dep);
+        }
+    }
+    if (missing.length === 0) {
+        return OK("runtime deps resolvable (react, react-dom, ink, ink-text-input, zod)");
+    }
+    return FAIL(`missing runtime deps: ${missing.join(", ")}\n` +
+        `         fix:  npm install -g ${"<pkg>"} --force    (then reopen the terminal)`);
+}
+/** Check PATH includes the npm global prefix. */
+function checkPath() {
+    const prefix = getGlobalPrefix();
+    if (!prefix)
+        return WARN("npm global prefix not detectable");
+    const pathSep = process.platform === "win32" ? ";" : ":";
+    const pathDirs = (process.env.PATH || "").split(pathSep);
+    if (pathDirs.includes(prefix)) {
+        return OK(`PATH includes npm prefix (${prefix})`);
+    }
+    return WARN(`PATH does not include npm prefix (${prefix})\n` +
+        `         symptom: "zelari-code: command not found" after install\n` +
+        `         fix (POSIX):   export PATH="$(npm prefix -g)/bin:$PATH"\n` +
+        `         fix (Windows): $env:Path = "$(npm prefix -g);$env:Path"`);
+}
+/**
+ * Run all checks and print results. Returns true if install is healthy
+ * (no critical failures), false otherwise. Never throws.
+ */
+export function runDoctor() {
+    const pkg = readPackageJson();
+    const pkgName = pkg?.name ?? "zelari-code";
+    const checks = [
+        { name: "node", run: () => checkNode(pkg) },
+        { name: "bin shim", run: () => checkShim(pkgName) },
+        { name: "cli bundle", run: () => checkBundle() },
+        { name: "runtime deps", run: () => checkRuntimeDeps() },
+        { name: "PATH", run: () => checkPath() },
+    ];
+    // eslint-disable-next-line no-console
+    console.log(`zelari-code doctor (v${pkg?.version ?? "unknown"})`);
+    // eslint-disable-next-line no-console
+    console.log("platform:", process.platform, process.arch);
+    // eslint-disable-next-line no-console
+    console.log("node:    ", process.version);
+    // eslint-disable-next-line no-console
+    console.log("prefix:  ", getGlobalPrefix() || "(unknown)");
+    // eslint-disable-next-line no-console
+    console.log("root:    ", packageRoot);
+    // eslint-disable-next-line no-console
+    console.log("");
+    let criticalFails = 0;
+    let warns = 0;
+    for (const c of checks) {
+        let result;
+        try {
+            result = c.run();
+        }
+        catch (err) {
+            result = FAIL(`unexpected error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const tag = result.ok
+            ? "OK  "
+            : result.severity === "critical"
+                ? "FAIL"
+                : "WARN";
+        const color = result.ok
+            ? "\x1b[32m"
+            : result.severity === "critical"
+                ? "\x1b[31m"
+                : "\x1b[33m";
+        const reset = "\x1b[0m";
+        // eslint-disable-next-line no-console
+        console.log(`  ${color}${tag}${reset}  ${c.name.padEnd(14)}${result.message.replace(/\n/g, "\n              ")}`);
+        if (!result.ok) {
+            if (result.severity === "critical")
+                criticalFails += 1;
+            else
+                warns += 1;
+        }
+    }
+    // eslint-disable-next-line no-console
+    console.log("");
+    if (criticalFails === 0 && warns === 0) {
+        // eslint-disable-next-line no-console
+        console.log("\x1b[32m✔ all checks passed\x1b[0m");
+        return true;
+    }
+    // eslint-disable-next-line no-console
+    console.log(`✗ ${criticalFails} critical failure(s), ${warns} warning(s)`);
+    return criticalFails === 0;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/cli/utils/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../../src/cli/utils/doctor.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zelari-code",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Zelari Code — AI Council coding agent CLI. Multi-agent orchestration (Caronte, Nettuno, Gerione, Plutone, Minosse, Lucifero) with slash commands, provider-agnostic LLM streaming, and self-update.",
   "author": "N-THEM Studio",
   "license": "SEE LICENSE IN LICENSE",
@@ -15,6 +15,7 @@
   "files": [
     "bin",
     "dist",
+    "scripts/postinstall.mjs",
     "LICENSE",
     "README.md",
     "package.json"
@@ -32,6 +33,7 @@
     "test:watch": "vitest",
     "smoke": "node bin/zelari-code.js --version",
     "verify:council": "npm run build --workspace=@zelari/core && node scripts/verify-council.mjs",
+    "postinstall": "node scripts/postinstall.mjs",
     "prepublishOnly": "node scripts/prepublish.mjs"
   },
   "dependencies": {
@@ -42,7 +44,7 @@
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.2",
-    "@zelari/core": "1.0.1",
+    "@zelari/core": "1.1.0",
     "@types/node": "^25.3.0",
     "@types/react": "^19.0.10",
     "esbuild": "^0.25.0",

package/scripts/postinstall.mjs

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+/**
+ * postinstall.mjs — Shim health check for global installs.
+ *
+ * Why this exists:
+ *   On Windows + npm 10/11, `npm install -g zelari-code@<x>` sometimes
+ *   fails to (re)create the bin shim `zelari-code.cmd` after an upgrade
+ *   (e.g. 0.7.x → 1.0.x). The package is correctly installed in
+ *   `<prefix>/node_modules/zelari-code/`, but `<prefix>/zelari-code.cmd`
+ *   is missing, so `zelari-code` returns "command not found" on the
+ *   next shell open. This script runs as `postinstall` and:
+ *
+ *     1. Detects global installs only (skips local installs to avoid noise).
+ *     2. Verifies the expected shim path exists and is current.
+ *     3. If missing or stale, prints a clear, actionable warning with the
+ *        exact fix command. It does NOT auto-repair the shim — auto-repair
+ *        is risky (shim is a privileged file in the global prefix and a
+ *        misdirected symlink can shadow other tools).
+ *     4. Also warns if the npm global prefix is not on the current PATH,
+ *        which is a separate-but-related failure mode (npm install
+ *        succeeds, the shim exists, but the user can't run the command
+ *        because the prefix isn't reachable from their shell).
+ *
+ * All output goes to stderr so it doesn't pollute the install log on
+ * success. The script is fail-safe: any error here is swallowed and
+ * logged, never thrown — a broken postinstall must NEVER fail the
+ * install itself.
+ *
+ * @see scripts/diagnose-path.ps1 — interactive Windows diagnostic
+ * @see scripts/fix-path.ps1 — adds npm prefix to user PATH
+ */
+
+import { execSync } from 'node:child_process';
+import {
+  existsSync,
+  readFileSync,
+  readlinkSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.resolve(__dirname, '..');
+
+/**
+ * Auto-repair a MISSING Windows bin shim.
+ *
+ * This is the single most common "zelari-code: command not found on some
+ * Windows PCs" failure: npm correctly unpacks the package into
+ * `<prefix>\node_modules\zelari-code\` but never (re)creates the three bin
+ * shims `<prefix>\zelari-code[.cmd|.ps1]`, so nothing on PATH resolves the
+ * command. Repairing this is safe — unlike overwriting a shim that points
+ * elsewhere (which could shadow another tool, hence why we never touch an
+ * existing shim), writing a shim under OUR own bin name, pointing at OUR
+ * own installed package, only fills a gap npm left behind.
+ *
+ * We write the exact same three files npm's own `cmd-shim` produces (cmd,
+ * PowerShell, and a POSIX sh wrapper for Git Bash/MSYS), each resolving to
+ * `%~dp0\node_modules\zelari-code\bin\zelari-code.js` relative to the shim
+ * dir — which is the global prefix, exactly where the package was unpacked.
+ *
+ * Opt out with `ZELARI_NO_SHIM_REPAIR=1`. Never throws; returns true only
+ * when at least the `.cmd` shim was written.
+ *
+ * @param {string} prefix   npm global prefix (dir that holds the shims)
+ * @param {string} pkgName  installed package name
+ * @returns {boolean}       true if the .cmd shim was created
+ */
+function repairWindowsShim(prefix, pkgName) {
+  if (process.env.ZELARI_NO_SHIM_REPAIR === '1') return false;
+  const rel = `node_modules\\${pkgName}\\bin\\zelari-code.js`;
+  const relPosix = `node_modules/${pkgName}/bin/zelari-code.js`;
+
+  const cmd = [
+    '@ECHO off',
+    'GOTO start',
+    ':find_dp0',
+    'SET dp0=%~dp0',
+    'EXIT /b',
+    ':start',
+    'SETLOCAL',
+    'CALL :find_dp0',
+    '',
+    'IF EXIST "%dp0%\\node.exe" (',
+    '  SET "_prog=%dp0%\\node.exe"',
+    ') ELSE (',
+    '  SET "_prog=node"',
+    '  SET PATHEXT=%PATHEXT:;.JS;=;%',
+    ')',
+    '',
+    `endLocal & goto #_undefined_# 2>NUL || title %COMSPEC% & "%_prog%"  "%dp0%\\${rel}" %*`,
+    '',
+  ].join('\r\n');
+
+  const ps1 = [
+    '#!/usr/bin/env pwsh',
+    '$basedir=Split-Path $MyInvocation.MyCommand.Definition -Parent',
+    '',
+    '$exe=""',
+    'if ($PSVersionTable.PSVersion -lt "6.0" -or $IsWindows) {',
+    '  $exe=".exe"',
+    '}',
+    '$ret=0',
+    'if (Test-Path "$basedir/node$exe") {',
+    '  if ($MyInvocation.ExpectingInput) {',
+    `    $input | & "$basedir/node$exe"  "$basedir/${relPosix}" $args`,
+    '  } else {',
+    `    & "$basedir/node$exe"  "$basedir/${relPosix}" $args`,
+    '  }',
+    '  $ret=$LASTEXITCODE',
+    '} else {',
+    '  if ($MyInvocation.ExpectingInput) {',
+    `    $input | & "node$exe"  "$basedir/${relPosix}" $args`,
+    '  } else {',
+    `    & "node$exe"  "$basedir/${relPosix}" $args`,
+    '  }',
+    '  $ret=$LASTEXITCODE',
+    '}',
+    'exit $ret',
+    '',
+  ].join('\n');
+
+  const sh = [
+    '#!/bin/sh',
+    'basedir=$(dirname "$(echo "$0" | sed -e \'s,\\\\,/,g\')")',
+    '',
+    'case `uname` in',
+    '    *CYGWIN*|*MINGW*|*MSYS*)',
+    '        if command -v cygpath > /dev/null 2>&1; then',
+    '            basedir=`cygpath -w "$basedir"`',
+    '        fi',
+    '    ;;',
+    'esac',
+    '',
+    'if [ -x "$basedir/node" ]; then',
+    `  exec "$basedir/node"  "$basedir/${relPosix}" "$@"`,
+    'else',
+    `  exec node  "$basedir/${relPosix}" "$@"`,
+    'fi',
+    '',
+  ].join('\n');
+
+  const targets = [
+    ['zelari-code.cmd', cmd],
+    ['zelari-code.ps1', ps1],
+    ['zelari-code', sh],
+  ];
+  let cmdWritten = false;
+  for (const [name, content] of targets) {
+    const dest = path.join(prefix, name);
+    // Never clobber an existing shim — only fill the gap npm left.
+    if (existsSync(dest)) continue;
+    try {
+      writeFileSync(dest, content, 'utf8');
+      if (name === 'zelari-code.cmd') cmdWritten = true;
+    } catch {
+      // Permission denied (prefix owned by admin) or read-only FS — the
+      // warning below still tells the user how to fix it manually.
+    }
+  }
+  return cmdWritten;
+}
+
+const warn = (msg) => {
+  // eslint-disable-next-line no-console
+  console.warn(`[zelari-code postinstall] ${msg}`);
+};
+
+const note = (msg) => {
+  // eslint-disable-next-line no-console
+  console.warn(`[zelari-code postinstall] ${msg}`);
+};
+
+try {
+  // 0. Only run for global installs. Local installs (`npm install zelari-code`)
+  //    create a `node_modules/.bin/zelari-code` symlink that npm handles
+  //    correctly, and the user runs the command via `npx` or package.json
+  //    scripts — so the global-prefix shim is irrelevant.
+  //
+  //    npm sets `npm_config_global=true` for `npm install -g` and for
+  //    `npm install -g <pkg>` invocations. Some npm versions also set
+  //    `npm_install_global` — check both for safety.
+  const isGlobal =
+    process.env.npm_config_global === 'true' ||
+    process.env.npm_install_global === 'true' ||
+    process.env.NPM_CONFIG_GLOBAL === 'true';
+
+  if (!isGlobal) {
+    process.exit(0);
+  }
+
+  // 1. Resolve the global prefix. Prefer the env var (set by npm), fall
+  //    back to `npm prefix -g`. If both fail, bail silently — we can't
+  //    diagnose without knowing where to look.
+  let prefix = (process.env.npm_config_prefix || process.env.NPM_CONFIG_PREFIX || '').trim();
+  if (!prefix) {
+    try {
+      prefix = execSync('npm prefix -g', { encoding: 'utf8' }).trim();
+    } catch {
+      // npm not on PATH, or this is a weirdly-sandboxed install.
+      // Either way, we can't help further.
+      process.exit(0);
+    }
+  }
+
+  const pkgName = process.env.npm_package_name || 'zelari-code';
+  const pkgVersion = process.env.npm_package_version || 'unknown';
+  const expectedBinScript = path.join(pkgRoot, 'bin', 'zelari-code.js');
+  const isWin = process.platform === 'win32';
+  const shimName = isWin ? 'zelari-code.cmd' : 'zelari-code';
+  const shimPath = path.join(prefix, shimName);
+  const expectedNodeModulesShim = isWin
+    ? `%~dp0\\node_modules\\${pkgName}\\bin\\zelari-code.js`
+    : path.join(prefix, 'node_modules', pkgName, 'bin', 'zelari-code.js');
+
+  // 2. Check the shim.
+  let shimOk = false;
+  let shimReason = '';
+
+  if (!existsSync(shimPath)) {
+    shimReason = `shim file not found at ${shimPath}`;
+    // Auto-repair the most common Windows failure: the package unpacked but
+    // npm never created the bin shim. We only write shims that are MISSING,
+    // and only under our own bin name → no risk of shadowing another tool.
+    if (isWin) {
+      const repaired = repairWindowsShim(prefix, pkgName);
+      if (repaired && existsSync(shimPath)) {
+        note(`shim was missing — auto-created ${shimPath}`);
+        note('open a NEW terminal and run `zelari-code --version` to confirm.');
+        process.exit(0);
+      }
+    }
+  } else {
+    try {
+      const st = statSync(shimPath);
+      if (isWin) {
+        // Windows: .cmd shim. Validate the content references the current
+        // package name + bin path. The exact text varies slightly across
+        // npm versions, so we just check for the package name + the
+        // bin/zelari-code.js substring.
+        const content = readFileSync(shimPath, 'utf8');
+        if (content.includes(`${pkgName}\\bin\\zelari-code.js`) || content.includes(`${pkgName}/bin/zelari-code.js`)) {
+          shimOk = true;
+        } else {
+          shimReason = `shim at ${shimPath} does not reference ${pkgName}/bin/zelari-code.js — it may belong to a different install`;
+        }
+      } else {
+        // POSIX: symlink (or hardlink). readlinkSync throws for non-symlinks.
+        let target;
+        try {
+          target = readlinkSync(shimPath);
+        } catch {
+          // Not a symlink — could be a hardlink or a copied file. In
+          // either case, npm shouldn't have done that. Treat as broken.
+          shimReason = `shim at ${shimPath} is not a symlink (npm should create a symlink for global installs on POSIX)`;
+          shimOk = false;
+        }
+        if (target) {
+          const resolved = path.resolve(path.dirname(shimPath), target);
+          if (resolved === expectedNodeModulesShim) {
+            shimOk = true;
+          } else {
+            shimReason = `shim at ${shimPath} points to ${resolved}, expected ${expectedNodeModulesShim}`;
+          }
+        }
+      }
+      // If we reach here with shimOk still false and shimReason still empty,
+      // it's a non-symlink non-cmd file — leave shimReason empty so the
+      // generic message is shown.
+      if (!shimOk && !shimReason) {
+        shimReason = `shim at ${shimPath} is not a regular file or symlink (mode=${st.mode})`;
+      }
+    } catch (err) {
+      shimReason = `could not inspect shim at ${shimPath}: ${err.message}`;
+    }
+  }
+
+  if (shimOk) {
+    note(`shim OK: ${shimPath}`);
+    process.exit(0);
+  }
+
+  // 3. Shim is broken or missing. Emit a clear, actionable warning.
+  warn('==============================================================');
+  warn(' npm install completed, but the `zelari-code` shim is broken.');
+  warn('==============================================================');
+  warn(`  Reason: ${shimReason}`);
+  warn('');
+  warn('  The package itself is correctly installed in:');
+  warn(`    ${path.join(prefix, 'node_modules', pkgName)}`);
+  warn('  But the bin shim is not where npm should have created it:');
+  warn(`    ${shimPath}`);
+  warn('');
+  warn('  Symptom: `zelari-code` returns "command not found" in your');
+  warn('  shell, even though `npm ls -g` lists the package.');
+  warn('');
+  warn('  Fix (try in order, run as Administrator on Windows if needed):');
+  warn('');
+  warn(`    npm install -g ${pkgName}@${pkgVersion} --force`);
+  warn('');
+  warn('  If the command is still not found after that, your npm');
+  warn('  global prefix may not be on your shell PATH. Run:');
+  warn('');
+  warn('    npm bin -g           # shows the expected shim dir');
+  warn('    echo "$PATH"         # check if it is included');
+  warn('');
+  warn('  On Windows, scripts/diagnose-path.ps1 and scripts/fix-path.ps1');
+  warn('  in the repo can inspect and repair PATH for you.');
+  warn('==============================================================');
+  process.exit(0); // Never fail the install.
+} catch (err) {
+  // Last-resort safety net: log and exit 0.
+  warn(`unexpected error (install is not affected): ${err.message}`);
+  process.exit(0);
+}