@vodmal/vdx-cli 0.7.0 → 0.8.1

package/README.md

@@ -24,6 +24,11 @@ invocation; pick global when you'll run `vdx` repeatedly, npx when you
 don't want anything in your global `node_modules` or you're in an
 ephemeral environment.
 
+**First command after install: `vdx doctor`** — it inspects your environment
+(Node version, `vdx` on PATH, git, mise, npm auth, container runtime, Claude
+Code plugin) and points to remedies for everything that's missing or
+sub-optimal.
+
 ## Use
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "vdx — unified lifecycle interface (up/down/build/test/check/fix) + versioned maturity audit with drift detection. Pairs with the vdx Claude Code plugin.",
   "keywords": [
     "vdx",

package/src/doctor.ts

@@ -149,6 +149,65 @@ function checkContainerRuntime(): CheckResult {
   };
 }
 
+function findOnPath(name: string): string | null {
+  const PATH = process.env.PATH ?? '';
+  const sep = process.platform === 'win32' ? ';' : ':';
+  for (const dir of PATH.split(sep)) {
+    if (!dir) continue;
+    const p = path.join(dir, name);
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+function isEphemeralPath(p: string): 'npx-cache' | 'local-bin' | null {
+  if (p.includes(`${path.sep}.npm${path.sep}_npx${path.sep}`)) return 'npx-cache';
+  if (p.includes(`${path.sep}node_modules${path.sep}.bin${path.sep}`)) return 'local-bin';
+  return null;
+}
+
+function checkVdxOnPath(): CheckResult {
+  const found = findOnPath('vdx');
+  if (!found) {
+    return {
+      id: 'vdx-on-path',
+      label: 'vdx install',
+      status: 'warning',
+      level: 1,
+      message:
+        '`vdx` not on PATH at check time. If you use a shell alias it is also fine — doctor cannot detect aliases.',
+      remedy:
+        'npm i -g @vodmal/vdx-cli  OR  alias vdx="npx -y -p @vodmal/vdx-cli vdx"  OR  keep using `npx -y -p @vodmal/vdx-cli vdx …` ad-hoc',
+    };
+  }
+  const ephemeral = isEphemeralPath(found);
+  if (ephemeral === 'npx-cache') {
+    return {
+      id: 'vdx-on-path',
+      label: 'vdx install',
+      status: 'ok',
+      level: 3,
+      message: `via npx cache: ${found} (ephemeral; fine for npx-only workflows — always latest)`,
+    };
+  }
+  if (ephemeral === 'local-bin') {
+    return {
+      id: 'vdx-on-path',
+      label: 'vdx install',
+      status: 'ok',
+      level: 2,
+      message: `local node_modules: ${found} (works inside this project only)`,
+    };
+  }
+  return {
+    id: 'vdx-on-path',
+    label: 'vdx install',
+    status: 'ok',
+    level: 4,
+    message: `global: ${found}`,
+  };
+}
+
 function checkClaudeCodePlugin(): CheckResult {
   const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
   if (!fs.existsSync(settingsPath)) {
@@ -189,6 +248,7 @@ function checkClaudeCodePlugin(): CheckResult {
 
 const CHECKS: Array<() => CheckResult> = [
   checkNode,
+  checkVdxOnPath,
   checkGit,
   checkMise,
   checkNpmAuth,