@vodmal/vdx-cli 0.4.0 → 0.6.0

package/README.md

@@ -8,20 +8,53 @@ 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
+# Lifecycle verbs (pass-through to `mise run <verb>`; requires mise + mise.toml)
+vdx up | down | build | test | check | fix
+
+# Maturity audit against the owner baseline rubric
 vdx audit <project-path> [--json] [--rubric <path>] [--stack <id>]
-vdx init  <project-path> [--baseline github.com/org/repo@vX.Y] [--dry-run] [--force]
-vdx-mcp   --project <path>   # MCP stdio server (used by the plugin)
+
+# Generate mise.toml + AGENTS.md for a project
+vdx init  <project-path> [--baseline github.com/org/repo@vX.Y] [--stack <id>] [--dry-run] [--force]
+
+# Publish a library (Node MVP; PHP/Python coming in Y.3)
+vdx publish <patch|minor|major> [--dry-run] [--force]
+
+# MCP stdio server consumed by the Claude Code plugin
+vdx-mcp   --project <path>
+```
+
+**Three quick examples**
+
+```bash
+# 1. Score the project I'm standing in
+vdx audit .
+
+# 2. Wire native scripts into the 6 lifecycle verbs, then run one
+vdx init . --stack node
+vdx test            # → mise run test (which calls `vitest run` or whatever was detected)
+
+# 3. Ship a new minor release of a Node lib
+vdx publish minor   # bump → npm publish (OTP prompt) → git commit + tag (no push)
 ```
 
 By default the bundled `rubric/vdx-rubric.yaml` is used (a mirror of canonical
@@ -48,6 +81,9 @@ npm run typecheck
 - `src/evaluator.ts`  — recursive evaluator + sugar notation
 - `src/scoring.ts`    — delta-style levels, flags for orthogonal axes
 - `src/audit.ts`      — orchestrator: overrides + applies_to filter + subpackage-ctx
+- `src/init.ts`       — `vdx init` planner (`selectVerbTask` + mise.toml/AGENTS.md renderers)
+- `src/run.ts`        — `resolveLifecycleVerb` + error renderer (pure logic for `vdx <verb>`)
+- `src/publish.ts`    — `planPublish` (pre-flight) + `executePublish` (bump → npm → git)
 - `src/report.ts`     — markdown / JSON output
 - `src/index.ts`      — CLI entry
 - `src/mcp-server.ts` — MCP stdio server (9 tools)
@@ -60,4 +96,8 @@ npm run typecheck
 - Baseline loading from a git ref is documented but evaluator still reads file
   paths only — `baseline:` in `mise.toml` is recorded but does not auto-fetch.
 - Watermark drift (phase 2 of `drift-algorithm.md`).
-- O25/O26/O27/O33/O34 — see [docs/decisions.md](../docs/decisions.md).
+- `vdx publish` only ships for Node (MVP). PHP/Python in Y.3; Cargo/Ruby/Go/Java
+  in Y.4.
+- Open items: O25 (mock-infra delta for Node), O26 (TOML round-trip), O27 (real
+  shared-infra precheck), O32 (multi-subpackage monorepo). See
+  [docs/decisions.md](../docs/decisions.md).

package/package.json

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

@@ -1,10 +1,17 @@
 #!/usr/bin/env node
 import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { loadRubric } from './rubric.ts';
 import { loadManifest, loadOverrides } from './manifest.ts';
 import { autoDetectStack, type Ctx } from './facts.ts';
+import {
+  LIFECYCLE_VERBS,
+  type LifecycleVerb,
+  resolveLifecycleVerb,
+  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,
@@ -20,7 +27,8 @@ const DEFAULT_RUBRIC = resolveDefaultRubric();
 function usage(): never {
   process.stderr.write(
     `Usage:
-  vdx audit   <project_path> [--rubric <path>] [--stack <stack>] [--json]
+  vdx <up|down|build|test|check|fix>     run lifecycle verb (via mise run <verb>)
+  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]
 `,
@@ -80,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));
   }
@@ -176,8 +195,32 @@ function cmdPublish(opts: ParsedArgs): void {
   }
 }
 
+function cmdRun(verb: LifecycleVerb): void {
+  const projectRoot = process.cwd();
+  const res = resolveLifecycleVerb(projectRoot, verb);
+  if (!res.ok) {
+    process.stderr.write(renderResolveError(res, projectRoot, verb));
+    process.exit(2);
+  }
+
+  try {
+    execFileSync('mise', ['run', verb], { cwd: projectRoot, stdio: 'inherit' });
+  } catch (e: any) {
+    if (e?.code === 'ENOENT') {
+      process.stderr.write(
+        `vdx: \`mise\` binary not found on PATH\n` +
+          `hint: install mise — https://mise.jdx.dev/getting-started.html\n`,
+      );
+      process.exit(127);
+    }
+    process.exit(typeof e?.status === 'number' ? e.status : 1);
+  }
+}
+
 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 ((LIFECYCLE_VERBS as readonly string[]).includes(parsed.cmd))
+  cmdRun(parsed.cmd as LifecycleVerb);
 else usage();

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';
+}

package/src/run.ts

@@ -0,0 +1,56 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as TOML from 'smol-toml';
+
+export const LIFECYCLE_VERBS = ['up', 'down', 'build', 'test', 'check', 'fix'] as const;
+export type LifecycleVerb = (typeof LIFECYCLE_VERBS)[number];
+
+export type VerbResolveResult =
+  | { ok: true; miseTomlPath: string }
+  | {
+      ok: false;
+      reason: 'no-mise-toml' | 'parse-error' | 'no-task';
+      detail?: string;
+    };
+
+export function resolveLifecycleVerb(
+  projectRoot: string,
+  verb: string,
+): VerbResolveResult {
+  const miseTomlPath = path.join(projectRoot, 'mise.toml');
+  if (!fs.existsSync(miseTomlPath)) {
+    return { ok: false, reason: 'no-mise-toml' };
+  }
+  let parsed: unknown;
+  try {
+    parsed = TOML.parse(fs.readFileSync(miseTomlPath, 'utf8'));
+  } catch (e: any) {
+    return { ok: false, reason: 'parse-error', detail: e?.message ?? String(e) };
+  }
+  const tasks = (parsed as { tasks?: Record<string, unknown> })?.tasks;
+  if (!tasks || typeof tasks !== 'object' || !(verb in tasks)) {
+    return { ok: false, reason: 'no-task' };
+  }
+  return { ok: true, miseTomlPath };
+}
+
+export function renderResolveError(
+  res: Exclude<VerbResolveResult, { ok: true }>,
+  projectRoot: string,
+  verb: string,
+): string {
+  switch (res.reason) {
+    case 'no-mise-toml':
+      return (
+        `vdx: no mise.toml in ${projectRoot}\n` +
+        `hint: run \`vdx init .\` to generate one, or define it manually.\n`
+      );
+    case 'parse-error':
+      return `vdx: failed to parse mise.toml: ${res.detail ?? 'unknown error'}\n`;
+    case 'no-task':
+      return (
+        `vdx: no \`[tasks.${verb}]\` in mise.toml\n` +
+        `hint: run \`vdx init . --force\` to re-detect, or add the task manually.\n`
+      );
+  }
+}