@vodmal/vdx-cli 0.5.0 → 0.7.0

package/README.md

@@ -8,14 +8,22 @@ Published on npm as **[@vodmal/vdx-cli](https://www.npmjs.com/package/@vodmal/vd
 
 ## Install
 
+Two equally supported paths:
+
 ```bash
-# global install
+# A. Daily-use install — recommended when you run `vdx <verb>` many times per session
 npm install -g @vodmal/vdx-cli
+vdx audit /path/to/project
 
-# or one-shot via npx (no install)
+# B. Zero-install via npx — recommended for CI runners, one-shot trial, or fresh envs
 npx -y -p @vodmal/vdx-cli vdx audit /path/to/project
 ```
 
+Same binary, same behavior. `npx` adds ~200–500 ms resolve overhead per
+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.
+
 ## Use
 
 ```bash
@@ -23,7 +31,7 @@ npx -y -p @vodmal/vdx-cli vdx audit /path/to/project
 vdx up | down | build | test | check | fix
 
 # Maturity audit against the owner baseline rubric
-vdx audit <project-path> [--json] [--rubric <path>] [--stack <id>]
+vdx audit <project-path> [--format=ansi|markdown|json] [--rubric <path>] [--stack <id>]
 
 # Generate mise.toml + AGENTS.md for a project
 vdx init  <project-path> [--baseline github.com/org/repo@vX.Y] [--stack <id>] [--dry-run] [--force]
@@ -31,6 +39,9 @@ vdx init  <project-path> [--baseline github.com/org/repo@vX.Y] [--stack <id>] [-
 # Publish a library (Node MVP; PHP/Python coming in Y.3)
 vdx publish <patch|minor|major> [--dry-run] [--force]
 
+# Environment self-check (Node / git / mise / npm auth / docker / Claude Code plugin)
+vdx doctor [--format=ansi|markdown|json]
+
 # MCP stdio server consumed by the Claude Code plugin
 vdx-mcp   --project <path>
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.5.0",
+  "version": "0.7.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",
@@ -46,12 +46,15 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "js-yaml": "^4.1.0",
+    "marked": "^15.0.12",
+    "marked-terminal": "^7.3.0",
     "smol-toml": "^1.3.0",
     "tsx": "^4.19.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
+    "@types/marked-terminal": "^6.1.1",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^4.1.7",
     "typescript": "^5.6.0",

package/src/doctor.ts

@@ -0,0 +1,223 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+export type CheckStatus = 'ok' | 'warning' | 'missing';
+
+export interface CheckResult {
+  id: string;
+  label: string;
+  status: CheckStatus;
+  level?: number;
+  message: string;
+  remedy?: string;
+}
+
+export interface DoctorReport {
+  checks: CheckResult[];
+  ok: number;
+  warning: number;
+  missing: number;
+}
+
+function probeVersion(binary: string, args: string[] = ['--version']): string | null {
+  try {
+    const out = execFileSync(binary, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return out.trim().split('\n')[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function parseSemverMajor(s: string): number | null {
+  const m = s.match(/(\d+)\.(\d+)\.(\d+)/);
+  return m ? parseInt(m[1]!, 10) : null;
+}
+
+function checkNode(): CheckResult {
+  const v = probeVersion('node', ['--version']);
+  if (!v) {
+    return {
+      id: 'node',
+      label: 'Node.js',
+      status: 'missing',
+      message: 'node binary not on PATH',
+      remedy: 'https://nodejs.org/en/download (LTS ≥ 20 recommended)',
+    };
+  }
+  const major = parseSemverMajor(v);
+  if (major === null) {
+    return { id: 'node', label: 'Node.js', status: 'warning', message: `unparseable version: ${v}` };
+  }
+  if (major < 20) {
+    return {
+      id: 'node',
+      label: 'Node.js',
+      status: 'warning',
+      level: 1,
+      message: `${v} — below recommended (≥ 20 LTS)`,
+      remedy: 'mise use -g node@20 (or upgrade via nvm/brew)',
+    };
+  }
+  return { id: 'node', label: 'Node.js', status: 'ok', level: major >= 22 ? 4 : 3, message: v };
+}
+
+function checkGit(): CheckResult {
+  const v = probeVersion('git', ['--version']);
+  if (!v) {
+    return {
+      id: 'git',
+      label: 'git',
+      status: 'missing',
+      message: 'git binary not on PATH',
+      remedy: 'https://git-scm.com/downloads',
+    };
+  }
+  return { id: 'git', label: 'git', status: 'ok', message: v };
+}
+
+function checkMise(): CheckResult {
+  const v = probeVersion('mise', ['--version']);
+  if (!v) {
+    return {
+      id: 'mise',
+      label: 'mise',
+      status: 'missing',
+      message: 'mise not on PATH — `vdx <verb>` will fail',
+      remedy: 'https://mise.jdx.dev/getting-started.html',
+    };
+  }
+  return { id: 'mise', label: 'mise', status: 'ok', message: v };
+}
+
+function checkNpmAuth(): CheckResult {
+  try {
+    const who = execFileSync('npm', ['whoami'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (!who) {
+      return {
+        id: 'npm-auth',
+        label: 'npm auth',
+        status: 'warning',
+        message: 'npm whoami returned empty',
+        remedy: 'npm login',
+      };
+    }
+    return { id: 'npm-auth', label: 'npm auth', status: 'ok', message: `logged in as ${who}` };
+  } catch {
+    return {
+      id: 'npm-auth',
+      label: 'npm auth',
+      status: 'warning',
+      message: 'not logged in — `vdx publish` will fail with E404',
+      remedy: 'npm login',
+    };
+  }
+}
+
+function checkContainerRuntime(): CheckResult {
+  const orbV = probeVersion('orb', ['version']);
+  if (orbV) {
+    return {
+      id: 'container-runtime',
+      label: 'container runtime',
+      status: 'ok',
+      level: 4,
+      message: `OrbStack: ${orbV.split('\n')[0]}`,
+    };
+  }
+  const dockerV = probeVersion('docker', ['--version']);
+  if (dockerV) {
+    return {
+      id: 'container-runtime',
+      label: 'container runtime',
+      status: 'ok',
+      level: 3,
+      message: `Docker: ${dockerV} (OrbStack recommended on macOS)`,
+      remedy: 'https://orbstack.dev (optional upgrade)',
+    };
+  }
+  return {
+    id: 'container-runtime',
+    label: 'container runtime',
+    status: 'missing',
+    message: 'no docker/orbstack — `vdx up` of containerised projects will fail',
+    remedy: 'https://orbstack.dev (macOS) or https://docker.com',
+  };
+}
+
+function checkClaudeCodePlugin(): CheckResult {
+  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+  if (!fs.existsSync(settingsPath)) {
+    return {
+      id: 'claude-plugin',
+      label: 'Claude Code vdx plugin',
+      status: 'warning',
+      message: '~/.claude/settings.json not found — Claude Code not installed or not configured',
+      remedy: 'Install Claude Code, then add vdx marketplace (see README)',
+    };
+  }
+  try {
+    const raw = fs.readFileSync(settingsPath, 'utf8');
+    if (raw.includes('VoDmAl/vdx') || raw.includes('vdx/marketplace')) {
+      return {
+        id: 'claude-plugin',
+        label: 'Claude Code vdx plugin',
+        status: 'ok',
+        message: 'vdx marketplace present in extraKnownMarketplaces',
+      };
+    }
+    return {
+      id: 'claude-plugin',
+      label: 'Claude Code vdx plugin',
+      status: 'warning',
+      message: 'Claude Code configured but vdx marketplace not registered',
+      remedy: 'Add github.com/VoDmAl/vdx/marketplace to extraKnownMarketplaces',
+    };
+  } catch (e: any) {
+    return {
+      id: 'claude-plugin',
+      label: 'Claude Code vdx plugin',
+      status: 'warning',
+      message: `cannot read settings.json: ${e?.message ?? e}`,
+    };
+  }
+}
+
+const CHECKS: Array<() => CheckResult> = [
+  checkNode,
+  checkGit,
+  checkMise,
+  checkNpmAuth,
+  checkContainerRuntime,
+  checkClaudeCodePlugin,
+];
+
+export function runDoctor(): DoctorReport {
+  const checks = CHECKS.map((fn) => fn());
+  const ok = checks.filter((c) => c.status === 'ok').length;
+  const warning = checks.filter((c) => c.status === 'warning').length;
+  const missing = checks.filter((c) => c.status === 'missing').length;
+  return { checks, ok, warning, missing };
+}
+
+const PROJECT_MARKER_FILES = [
+  'package.json',
+  'composer.json',
+  'pyproject.toml',
+  'Makefile',
+  'mise.toml',
+  'Cargo.toml',
+  'go.mod',
+  '.git',
+];
+
+export function looksLikeProject(projectRoot: string): boolean {
+  for (const marker of PROJECT_MARKER_FILES) {
+    if (fs.existsSync(path.join(projectRoot, marker))) return true;
+  }
+  return false;
+}

package/src/index.ts

@@ -11,7 +11,15 @@ import {
   renderResolveError,
 } from './run.ts';
 import { audit } from './audit.ts';
-import { reportMarkdown, reportJson } from './report.ts';
+import {
+  reportMarkdown,
+  reportJson,
+  reportAnsi,
+  reportDoctorMarkdown,
+  reportDoctorJson,
+  reportDoctorAnsi,
+} from './report.ts';
+import { runDoctor, looksLikeProject } from './doctor.ts';
 import { planInit, writeInit, renderPlanSummary } from './init.ts';
 import {
   planPublish,
@@ -28,9 +36,10 @@ function usage(): never {
   process.stderr.write(
     `Usage:
   vdx <up|down|build|test|check|fix>     run lifecycle verb (via mise run <verb>)
-  vdx audit   <project_path> [--rubric <path>] [--stack <stack>] [--json]
+  vdx audit   <project_path> [--rubric <path>] [--stack <stack>] [--format=ansi|markdown|json] [--json]
   vdx init    <project_path> [--stack <id>] [--baseline <ref>] [--dry-run] [--force]
   vdx publish <patch|minor|major> [--dry-run] [--force]
+  vdx doctor  [--format=ansi|markdown|json] [--json]
 `,
   );
   process.exit(1);
@@ -70,6 +79,14 @@ function cmdAudit(opts: ParsedArgs): void {
   if (!projectArg) usage();
   const projectRoot = path.resolve(projectArg);
 
+  if (!looksLikeProject(projectRoot)) {
+    process.stderr.write(
+      `vdx: ${projectRoot} doesn't look like a project root ` +
+        `(no package.json / composer.json / pyproject.toml / Makefile / mise.toml / .git found)\n` +
+        `hint: try \`vdx doctor\` to check your environment, or \`vdx audit <path-to-project>\`.\n\n`,
+    );
+  }
+
   const manifest = loadManifest(projectRoot);
   const overrides = loadOverrides(projectRoot);
 
@@ -88,8 +105,19 @@ function cmdAudit(opts: ParsedArgs): void {
   const baselineRef = manifest?.baseline ?? `file://${rubricPath}`;
   const result = audit(rubric, ctx, overrides, baselineRef, manifest);
 
-  if (opts.flags.json) {
+  const formatFlag =
+    typeof opts.flags.format === 'string' ? opts.flags.format : undefined;
+  const wantJson = opts.flags.json === true || formatFlag === 'json';
+  const wantMarkdown = formatFlag === 'markdown' || formatFlag === 'md';
+  const wantAnsi = formatFlag === 'ansi';
+  const isTty = process.stdout.isTTY === true;
+
+  if (wantJson) {
     process.stdout.write(reportJson(result) + '\n');
+  } else if (wantMarkdown) {
+    process.stdout.write(reportMarkdown(result));
+  } else if (wantAnsi || (isTty && !formatFlag)) {
+    process.stdout.write(reportAnsi(result));
   } else {
     process.stdout.write(reportMarkdown(result));
   }
@@ -206,10 +234,34 @@ function cmdRun(verb: LifecycleVerb): void {
   }
 }
 
+function cmdDoctor(opts: ParsedArgs): void {
+  const report = runDoctor();
+
+  const formatFlag =
+    typeof opts.flags.format === 'string' ? opts.flags.format : undefined;
+  const wantJson = opts.flags.json === true || formatFlag === 'json';
+  const wantMarkdown = formatFlag === 'markdown' || formatFlag === 'md';
+  const wantAnsi = formatFlag === 'ansi';
+  const isTty = process.stdout.isTTY === true;
+
+  if (wantJson) {
+    process.stdout.write(reportDoctorJson(report) + '\n');
+  } else if (wantMarkdown) {
+    process.stdout.write(reportDoctorMarkdown(report));
+  } else if (wantAnsi || (isTty && !formatFlag)) {
+    process.stdout.write(reportDoctorAnsi(report));
+  } else {
+    process.stdout.write(reportDoctorMarkdown(report));
+  }
+
+  if (report.missing > 0) process.exit(2);
+}
+
 const parsed = parseArgs(process.argv);
 if (parsed.cmd === 'audit') cmdAudit(parsed);
 else if (parsed.cmd === 'init') cmdInit(parsed);
 else if (parsed.cmd === 'publish') cmdPublish(parsed);
+else if (parsed.cmd === 'doctor') cmdDoctor(parsed);
 else if ((LIFECYCLE_VERBS as readonly string[]).includes(parsed.cmd))
   cmdRun(parsed.cmd as LifecycleVerb);
 else usage();

package/src/report.ts

@@ -1,4 +1,16 @@
+import { Marked } from 'marked';
+import { markedTerminal } from 'marked-terminal';
 import type { AuditResult } from './audit.ts';
+import type { DoctorReport, CheckStatus } from './doctor.ts';
+
+let terminalMarked: Marked | null = null;
+function getTerminalMarked(): Marked {
+  if (terminalMarked) return terminalMarked;
+  const m = new Marked();
+  m.use(markedTerminal({ reflowText: false, tab: 2 }) as never);
+  terminalMarked = m;
+  return m;
+}
 
 const SYMBOL: Record<string, string> = {
   aligned: '✅',
@@ -47,3 +59,44 @@ export function reportMarkdown(r: AuditResult): string {
 export function reportJson(r: AuditResult): string {
   return JSON.stringify(r, null, 2);
 }
+
+export function reportAnsi(r: AuditResult): string {
+  const md = reportMarkdown(r);
+  const out = getTerminalMarked().parse(md) as string;
+  return out.endsWith('\n') ? out : out + '\n';
+}
+
+const CHECK_SYMBOL: Record<CheckStatus, string> = {
+  ok: '✅',
+  warning: '⚠️ ',
+  missing: '❌',
+};
+
+export function reportDoctorMarkdown(r: DoctorReport): string {
+  const lines: string[] = [];
+  lines.push('# vdx doctor report');
+  lines.push('');
+  lines.push(
+    `- **OK**: ${r.ok}  **Warning**: ${r.warning}  **Missing**: ${r.missing}`,
+  );
+  lines.push('');
+  lines.push('| Check | Status | Detail | Remedy |');
+  lines.push('|-------|:------:|--------|--------|');
+  for (const c of r.checks) {
+    const sym = CHECK_SYMBOL[c.status];
+    const level = c.level !== undefined ? ` (L${c.level})` : '';
+    const remedy = c.remedy ? `\`${c.remedy}\`` : '—';
+    lines.push(`| **${c.label}** | ${sym} ${c.status}${level} | ${c.message} | ${remedy} |`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+export function reportDoctorJson(r: DoctorReport): string {
+  return JSON.stringify(r, null, 2);
+}
+
+export function reportDoctorAnsi(r: DoctorReport): string {
+  const md = reportDoctorMarkdown(r);
+  const out = getTerminalMarked().parse(md) as string;
+  return out.endsWith('\n') ? out : out + '\n';
+}