@vodmal/vdx-cli 0.8.3 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "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",
@@ -45,6 +45,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "cli-table3": "^0.6.5",
     "js-yaml": "^4.1.0",
     "marked": "^15.0.12",
     "marked-terminal": "^7.3.0",

package/src/doctor.ts

@@ -23,7 +23,7 @@ export interface DoctorReport {
   missing: number;
 }
 
-function readCliVersion(): string {
+export function readCliVersion(): string {
   try {
     const pkgPath = path.resolve(
       path.dirname(fileURLToPath(import.meta.url)),
@@ -37,6 +37,30 @@ function readCliVersion(): string {
   }
 }
 
+function probeNpmLatestVersion(pkg: string, timeoutMs = 2000): string | null {
+  try {
+    const out = execFileSync('npm', ['view', pkg, 'version'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: timeoutMs,
+    });
+    return out.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function compareSemver(a: string, b: string): number {
+  const pa = a.split('.').map((n) => parseInt(n, 10));
+  const pb = b.split('.').map((n) => parseInt(n, 10));
+  for (let i = 0; i < 3; i++) {
+    const ai = pa[i] ?? 0;
+    const bi = pb[i] ?? 0;
+    if (ai !== bi) return ai - bi;
+  }
+  return 0;
+}
+
 function probeVersion(binary: string, args: string[] = ['--version']): string | null {
   try {
     const out = execFileSync(binary, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
@@ -182,93 +206,122 @@ function isEphemeralPath(p: string): 'npx-cache' | 'local-bin' | null {
   return null;
 }
 
-function checkVdxOnPath(): CheckResult {
-  const found = findOnPath('vdx');
-  if (!found) {
+function checkVdxVersion(): CheckResult {
+  const current = readCliVersion();
+  const latest = probeNpmLatestVersion('@vodmal/vdx-cli');
+  if (current === 'unknown') {
     return {
-      id: 'vdx-on-path',
-      label: 'vdx install',
+      id: 'vdx-version',
+      label: 'vdx version',
       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',
+      message: 'cannot read local cli package.json version',
     };
   }
-  const ephemeral = isEphemeralPath(found);
-  if (ephemeral === 'npx-cache') {
+  if (!latest) {
     return {
-      id: 'vdx-on-path',
-      label: 'vdx install',
+      id: 'vdx-version',
+      label: 'vdx version',
       status: 'ok',
       level: 3,
-      message:
-        `via npx cache: ${found} — invoked-only (shell command \`vdx\` will not resolve outside npx). ` +
-        `For shell-global command run: npm i -g @vodmal/vdx-cli  OR  alias vdx="npx -y -p @vodmal/vdx-cli vdx".`,
+      message: `${current} (latest check skipped — offline or npm timeout)`,
     };
   }
-  if (ephemeral === 'local-bin') {
+  const cmp = compareSemver(current, latest);
+  if (cmp < 0) {
     return {
-      id: 'vdx-on-path',
-      label: 'vdx install',
-      status: 'ok',
+      id: 'vdx-version',
+      label: 'vdx version',
+      status: 'warning',
       level: 2,
-      message: `local node_modules: ${found} (works inside this project only)`,
+      message: `${current} → latest ${latest}`,
+      remedy: 'npm i -g @vodmal/vdx-cli@latest (or clear npx cache)',
+    };
+  }
+  if (cmp > 0) {
+    return {
+      id: 'vdx-version',
+      label: 'vdx version',
+      status: 'ok',
+      level: 4,
+      message: `${current} (ahead of npm latest ${latest} — local dev build)`,
     };
   }
   return {
-    id: 'vdx-on-path',
-    label: 'vdx install',
+    id: 'vdx-version',
+    label: 'vdx version',
     status: 'ok',
     level: 4,
-    message: `global: ${found}`,
+    message: `${current} (latest)`,
   };
 }
 
-function checkVdxInShell(): CheckResult {
+function classifyVdxInstall(found: string): { mode: 'global' | 'npx-cache' | 'local-bin'; level: number; tag: string } {
+  const ephemeral = isEphemeralPath(found);
+  if (ephemeral === 'npx-cache') return { mode: 'npx-cache', level: 3, tag: 'npx cache (ephemeral)' };
+  if (ephemeral === 'local-bin') return { mode: 'local-bin', level: 2, tag: 'project node_modules' };
+  return { mode: 'global', level: 4, tag: 'global' };
+}
+
+function checkVdx(): CheckResult {
   const found = findOnPath('vdx');
   if (!found) {
     return {
-      id: 'vdx-in-shell',
-      label: 'vdx in shell',
+      id: 'vdx',
+      label: 'vdx',
       status: 'warning',
       level: 1,
-      message:
-        'no — `vdx` command not on persistent PATH. If you set a shell alias, it works but doctor cannot detect aliases.',
-      remedy:
-        'npm i -g @vodmal/vdx-cli  OR  alias vdx="npx -y -p @vodmal/vdx-cli vdx"',
+      message: 'not on PATH (alias may still work — doctor cannot detect aliases)',
+      remedy: 'npm i -g @vodmal/vdx-cli  OR  alias vdx="npx -y -p @vodmal/vdx-cli vdx"',
     };
   }
-  const ephemeral = isEphemeralPath(found);
-  if (ephemeral === 'npx-cache') {
+  const { mode, level, tag } = classifyVdxInstall(found);
+  if (mode === 'global') {
     return {
-      id: 'vdx-in-shell',
-      label: 'vdx in shell',
-      status: 'warning',
-      level: 1,
-      message:
-        'no — only the ephemeral npx-cache binary is on PATH; bare `vdx <verb>` in a fresh shell will not resolve',
-      remedy:
-        'npm i -g @vodmal/vdx-cli  OR  alias vdx="npx -y -p @vodmal/vdx-cli vdx"',
+      id: 'vdx',
+      label: 'vdx',
+      status: 'ok',
+      level,
+      message: `${tag} — resolves in any shell (${found})`,
     };
   }
-  if (ephemeral === 'local-bin') {
+  if (mode === 'npx-cache') {
     return {
-      id: 'vdx-in-shell',
-      label: 'vdx in shell',
+      id: 'vdx',
+      label: 'vdx',
+      status: 'ok',
+      level,
+      message: `${tag} — \`npx -y -p @vodmal/vdx-cli vdx …\` works; bare \`vdx\` in a fresh shell does not`,
+      remedy: 'npm i -g @vodmal/vdx-cli for shell-global command',
+    };
+  }
+  return {
+    id: 'vdx',
+    label: 'vdx',
+    status: 'ok',
+    level,
+    message: `${tag} — works inside this project only (${found})`,
+    remedy: 'npm i -g @vodmal/vdx-cli for global shell access',
+  };
+}
+
+function checkClaudeCode(): CheckResult {
+  const found = findOnPath('claude');
+  if (!found) {
+    return {
+      id: 'claude-code',
+      label: 'Claude Code',
       status: 'warning',
-      level: 2,
-      message: `project-only — \`vdx\` works inside this project root (${found}) but not elsewhere`,
-      remedy: 'npm i -g @vodmal/vdx-cli for global shell access',
+      message: '`claude` CLI not on PATH',
+      remedy: 'https://docs.claude.com/en/docs/claude-code',
     };
   }
+  const v = probeVersion('claude', ['--version']);
   return {
-    id: 'vdx-in-shell',
-    label: 'vdx in shell',
+    id: 'claude-code',
+    label: 'Claude Code',
     status: 'ok',
     level: 4,
-    message: `yes — \`vdx\` resolves globally (${found})`,
+    message: v ?? `installed (${found})`,
   };
 }
 
@@ -279,7 +332,7 @@ function checkClaudeCodePlugin(): CheckResult {
       id: 'claude-plugin',
       label: 'Claude Code vdx plugin',
       status: 'warning',
-      message: '~/.claude/settings.json not found — Claude Code not installed or not configured',
+      message: '~/.claude/settings.json not found',
       remedy: 'Install Claude Code, then add vdx marketplace (see README)',
     };
   }
@@ -290,14 +343,14 @@ function checkClaudeCodePlugin(): CheckResult {
         id: 'claude-plugin',
         label: 'Claude Code vdx plugin',
         status: 'ok',
-        message: 'vdx marketplace present in extraKnownMarketplaces',
+        message: 'vdx marketplace registered',
       };
     }
     return {
       id: 'claude-plugin',
       label: 'Claude Code vdx plugin',
       status: 'warning',
-      message: 'Claude Code configured but vdx marketplace not registered',
+      message: 'vdx marketplace not registered',
       remedy: 'Add github.com/VoDmAl/vdx/marketplace to extraKnownMarketplaces',
     };
   } catch (e: any) {
@@ -311,14 +364,15 @@ function checkClaudeCodePlugin(): CheckResult {
 }
 
 const CHECKS: Array<() => CheckResult> = [
+  checkVdxVersion,
+  checkVdx,
+  checkClaudeCode,
+  checkClaudeCodePlugin,
   checkNode,
-  checkVdxOnPath,
-  checkVdxInShell,
   checkGit,
   checkMise,
   checkNpmAuth,
   checkContainerRuntime,
-  checkClaudeCodePlugin,
 ];
 
 export function runDoctor(): DoctorReport {

package/src/index.ts

@@ -59,13 +59,18 @@ function parseArgs(argv: string[]): ParsedArgs {
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i]!;
     if (a.startsWith('--')) {
-      const name = a.slice(2);
-      const next = rest[i + 1];
-      if (next !== undefined && !next.startsWith('--')) {
-        flags[name] = next;
-        i++;
+      const body = a.slice(2);
+      const eqIdx = body.indexOf('=');
+      if (eqIdx >= 0) {
+        flags[body.slice(0, eqIdx)] = body.slice(eqIdx + 1);
       } else {
-        flags[name] = true;
+        const next = rest[i + 1];
+        if (next !== undefined && !next.startsWith('--')) {
+          flags[body] = next;
+          i++;
+        } else {
+          flags[body] = true;
+        }
       }
     } else {
       positionals.push(a);

package/src/report.ts

@@ -1,8 +1,17 @@
 import { Marked } from 'marked';
 import { markedTerminal } from 'marked-terminal';
+import Table from 'cli-table3';
 import type { AuditResult } from './audit.ts';
 import type { DoctorReport, CheckStatus } from './doctor.ts';
 
+const ANSI = {
+  bold: (s: string): string => `\x1b[1m${s}\x1b[22m`,
+  dim: (s: string): string => `\x1b[2m${s}\x1b[22m`,
+  green: (s: string): string => `\x1b[32m${s}\x1b[39m`,
+  yellow: (s: string): string => `\x1b[33m${s}\x1b[39m`,
+  red: (s: string): string => `\x1b[31m${s}\x1b[39m`,
+};
+
 let terminalMarked: Marked | null = null;
 function getTerminalMarked(): Marked {
   if (terminalMarked) return terminalMarked;
@@ -76,9 +85,8 @@ export function reportDoctorMarkdown(r: DoctorReport): string {
   const lines: string[] = [];
   lines.push('# vdx doctor report');
   lines.push('');
-  lines.push(`- **@vodmal/vdx-cli version**: \`${r.cliVersion}\``);
   lines.push(
-    `- **OK**: ${r.ok}  **Warning**: ${r.warning}  **Missing**: ${r.missing}`,
+    `**OK**: ${r.ok}  **Warning**: ${r.warning}  **Missing**: ${r.missing}`,
   );
   lines.push('');
   lines.push('| Check | Status | Detail | Remedy |');
@@ -96,8 +104,48 @@ export function reportDoctorJson(r: DoctorReport): string {
   return JSON.stringify(r, null, 2);
 }
 
+const STATUS_RENDER: Record<CheckStatus, (s: string) => string> = {
+  ok: ANSI.green,
+  warning: ANSI.yellow,
+  missing: ANSI.red,
+};
+
+function termWidth(fallback = 100): number {
+  const w = process.stdout.columns;
+  if (typeof w === 'number' && w >= 60) return w;
+  return fallback;
+}
+
 export function reportDoctorAnsi(r: DoctorReport): string {
-  const md = reportDoctorMarkdown(r);
-  const out = getTerminalMarked().parse(md) as string;
-  return out.endsWith('\n') ? out : out + '\n';
+  const lines: string[] = [];
+  lines.push(ANSI.bold('vdx doctor'));
+  const summary =
+    `${STATUS_RENDER.ok(`✅ ${r.ok} ok`)}  ` +
+    `${STATUS_RENDER.warning(`⚠ ${r.warning} warning`)}  ` +
+    `${STATUS_RENDER.missing(`✗ ${r.missing} missing`)}`;
+  lines.push(summary);
+  lines.push('');
+
+  const total = termWidth();
+  const checkW = 18;
+  const statusW = 14;
+  const remedyW = Math.max(20, Math.min(36, Math.floor((total - checkW - statusW - 6) * 0.4)));
+  const detailW = Math.max(24, total - checkW - statusW - remedyW - 6);
+
+  const table = new Table({
+    head: [ANSI.bold('Check'), ANSI.bold('Status'), ANSI.bold('Detail'), ANSI.bold('Remedy')],
+    colWidths: [checkW, statusW, detailW, remedyW],
+    wordWrap: true,
+    wrapOnWordBoundary: true,
+    style: { head: [], border: [] },
+  });
+  for (const c of r.checks) {
+    const sym = CHECK_SYMBOL[c.status];
+    const level = c.level !== undefined ? ` L${c.level}` : '';
+    const statusCell = STATUS_RENDER[c.status](`${sym} ${c.status}${level}`);
+    table.push([ANSI.bold(c.label), statusCell, c.message, c.remedy ?? ANSI.dim('—')]);
+  }
+  lines.push(table.toString());
+  lines.push('');
+  return lines.join('\n');
 }