@vodmal/vdx-cli 0.2.0 → 0.2.1

package/README.md

@@ -1,51 +1,63 @@
-# vdx-cli — Native predicate evaluator (v0.1)
+# @vodmal/vdx-cli — vdx evaluator + MCP server
 
-Минимальный аудит-движок для рубрики `vdx-rubric-vodmal`. Шаг C плана
-реализации (см. `../docs/decisions.md` D10 — нативный оценщик, не OPA).
+Native predicate evaluator for `vdx-rubric-vodmal` + MCP stdio server for the
+Claude Code `vdx` plugin. Decision basis: [docs/decisions.md](../docs/decisions.md)
+D10 (native evaluator, not OPA).
 
-## Установка
+Published on npm as **[@vodmal/vdx-cli](https://www.npmjs.com/package/@vodmal/vdx-cli)**.
+
+## Install
 
 ```bash
-cd "$(realpath .)"
-npm install
+# global install
+npm install -g @vodmal/vdx-cli
+
+# or one-shot via npx (no install)
+npx -y -p @vodmal/vdx-cli vdx audit /path/to/project
 ```
 
-## Запуск
+## Use
 
 ```bash
-npx tsx src/index.ts audit /path/to/project
-# или
-npm run audit -- /path/to/project --json
+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)
 ```
 
-По умолчанию рубрика читается из
-`/Users/vdm/AI Projects/vdx-rubric-vodmal/vdx-rubric.yaml`. Override:
-`--rubric /alt/path.yaml`.
+By default the bundled `rubric/vdx-rubric.yaml` is used (a mirror of canonical
+[vdx-rubric-vodmal](https://github.com/VoDmAl/vdx-rubric-vodmal) at the time of
+each CLI release). Override via `--rubric <path>` or the env var `VDX_RUBRIC`.
 
-## Smoke-тест
+## Dev
 
 ```bash
-npm run smoke
+git clone https://github.com/VoDmAl/vdx
+cd vdx/cli
+npm install
+npm run audit -- /path/to/project --json
+npm run smoke      # gauge against 3 calibration references
+npm run typecheck
 ```
 
-Прогоняет аудит на трёх калибровочных референсах
-(telegram / t23b / bookmap). Ожидаемо все capped at L2 на оси `ci`.
-
-## Структура
+## Structure
 
-- `src/rubric.ts`     — типы + YAML-загрузчик
-- `src/manifest.ts`   — парсинг `[vdx]` блока в `mise.toml` + `.vdx-overrides.yml`
-- `src/facts.ts`      — fact source loaders (tasks, packages, configs)
-- `src/predicates.ts` — registry предикатов (v0.1: 11 функций)
-- `src/evaluator.ts`  — рекурсивный evaluator + сахарная нотация
-- `src/scoring.ts`    — delta-style для уровней, flags для гибкой оси
-- `src/audit.ts`      — оркестратор: применяет overrides + считает уровень (D7)
-- `src/report.ts`     — markdown / JSON формат отчёта
+- `src/rubric.ts`     — types + YAML loader
+- `src/manifest.ts`   — parser for `[vdx]` block in `mise.toml` + `.vdx-overrides.yml`
+- `src/facts.ts`      — fact source loaders (tasks, packages, configs, sub-package detection)
+- `src/predicates.ts` — predicate registry (11 functions)
+- `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/report.ts`     — markdown / JSON output
 - `src/index.ts`      — CLI entry
+- `src/mcp-server.ts` — MCP stdio server (9 tools)
+- `src/defaults.ts`   — bundled rubric resolution
+- `bin/vdx.cjs`, `bin/vdx-mcp.cjs` — Node wrappers (tsx ESM loader in-process)
 
-## Что НЕ реализовано в v0.1
+## Not implemented yet
 
-- `config_value`, `command_succeeds` предикаты — заглушки с warning.
-- Загрузка baseline из git-репо по `baseline:` ссылке — пока только local file.
-- Watermark drift (фаза 2 из drift-algorithm.md).
-- MCP-server обёртка (D6 — следующий шаг).
+- `config_value`/`command_succeeds` predicates are stubs (warning at evaluation).
+- 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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.2.0",
+  "version": "0.2.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",
@@ -23,8 +23,8 @@
   },
   "type": "module",
   "bin": {
-    "vdx": "./bin/vdx.cjs",
-    "vdx-mcp": "./bin/vdx-mcp.cjs"
+    "vdx": "bin/vdx.cjs",
+    "vdx-mcp": "bin/vdx-mcp.cjs"
   },
   "files": [
     "src",

package/src/audit.ts

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import type { Rubric, LevelName } from './rubric.ts';
-import { findSubPackages, type Ctx } from './facts.ts';
+import { findSubPackages, stackForDir, type Ctx } from './facts.ts';
 import type { Override, VdxManifest } from './manifest.ts';
 import { evalAxis, projectLevel, type AxisResult } from './scoring.ts';
 
@@ -33,12 +33,14 @@ function resolveSubpackageCtx(
   manifest: VdxManifest | null,
 ): { ctx: Ctx; relPath: string | null } {
   let relPath: string | null = null;
+  let subpackageStack: string | null = null;
 
   if (manifest?.primary_subpackage) {
     const p = manifest.primary_subpackage;
     const abs = path.join(ctx.projectRoot, p);
     if (fs.existsSync(abs)) {
       relPath = p;
+      subpackageStack = stackForDir(abs);
     } else {
       process.stderr.write(
         `warning: primary_subpackage "${p}" does not exist — falling back to root\n`,
@@ -49,6 +51,12 @@ function resolveSubpackageCtx(
     const matching = subs.filter((s) => s.stack === ctx.stack);
     if (matching.length === 1) {
       relPath = matching[0]!.relPath;
+      subpackageStack = matching[0]!.stack;
+    } else if (matching.length === 0 && subs.length === 1) {
+      // O33: single sub-package with a stack different from ctx.stack —
+      // adopt it so applies_to-axes for that stack can evaluate.
+      relPath = subs[0]!.relPath;
+      subpackageStack = subs[0]!.stack;
     }
   }
 
@@ -56,7 +64,7 @@ function resolveSubpackageCtx(
   return {
     ctx: {
       projectRoot: path.join(ctx.projectRoot, relPath),
-      stack: ctx.stack,
+      stack: subpackageStack ?? ctx.stack,
       cache: new Map(),
     },
     relPath,
@@ -96,7 +104,8 @@ export function audit(
       });
       continue;
     }
-    if (axis.applies_to && !axis.applies_to.includes(ctx.stack)) {
+    const evalCtx = axis.applies_to ? subpackageCtx : ctx;
+    if (axis.applies_to && !axis.applies_to.includes(evalCtx.stack)) {
       perAxis.push({
         axis_id: axis.id,
         class: axis.class,
@@ -106,7 +115,6 @@ export function audit(
       });
       continue;
     }
-    const evalCtx = axis.applies_to ? subpackageCtx : ctx;
     const achieved = evalAxis(axis, evalCtx);
     const ov = overrideByAxis.get(axis.id);
     const target = (ov?.target as LevelName) ?? axis.default_target;

package/src/facts.ts

@@ -216,7 +216,7 @@ const MANIFEST_TO_STACK: Array<[string, string]> = [
   ['requirements.txt', 'python'],
 ];
 
-function stackForDir(dir: string): string | null {
+export function stackForDir(dir: string): string | null {
   for (const [manifest, stack] of MANIFEST_TO_STACK) {
     if (fs.existsSync(path.join(dir, manifest))) return stack;
   }