@vodmal/vdx-cli 0.5.0 → 0.6.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.5.0",
+  "version": "0.6.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/index.ts

@@ -11,7 +11,7 @@ import {
   renderResolveError,
 } from './run.ts';
 import { audit } from './audit.ts';
-import { reportMarkdown, reportJson } from './report.ts';
+import { reportMarkdown, reportJson, reportAnsi } from './report.ts';
 import { planInit, writeInit, renderPlanSummary } from './init.ts';
 import {
   planPublish,
@@ -28,7 +28,7 @@ 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]
 `,
@@ -88,8 +88,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));
   }

package/src/report.ts

@@ -1,5 +1,16 @@
+import { Marked } from 'marked';
+import { markedTerminal } from 'marked-terminal';
 import type { AuditResult } from './audit.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: '✅',
   gap: '⚠️ ',
@@ -47,3 +58,9 @@ 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';
+}