@vodmal/vdx-cli 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.2.1",
+  "version": "0.3.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",
@@ -39,7 +39,9 @@
     "audit": "tsx src/index.ts audit",
     "smoke": "bash smoke.sh",
     "typecheck": "tsc --noEmit",
-    "test": "tsc --noEmit"
+    "test": "vitest run",
+    "test:unit": "vitest run tests/unit",
+    "coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -51,7 +53,9 @@
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
+    "@vitest/coverage-v8": "^4.1.7",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.7"
   },
   "publishConfig": {
     "access": "public"

package/rubric/vdx-rubric.yaml

@@ -11,7 +11,7 @@ schema_version: "0.2"
 
 metadata:
   name: vdx-rubric-vodmal
-  version: "0.2.2"
+  version: "0.3.1"
   description: "Personal maturity rubric for multi-stack projects (vodmal)"
   owner: vodmal
   homepage: "https://github.com/vodmal/vdx-rubric"
@@ -534,3 +534,84 @@ axes:
           file_contains:
             paths: [misc/traefik-global/README.md, misc/traefik-global/start.sh]
             pattern: "@v\\d+\\.\\d+\\.\\d+"          # semver pin
+
+  - id: release-artifact
+    class: supporting
+    description: "Publish-readiness: metadata completeness + entry points + registry signals (O34, v0.3.0). Применяется только к проектам, заявляющим publish-intent (O35, v0.3.1) — иначе excluded."
+    applies_to: [node, php, ruby, python]
+    # O35 (v0.3.1): ось применяется только если проект декларирует намерение
+    # публиковать артефакт. Чистые app'ы (private:true в package.json или
+    # composer type:project) → excluded.
+    applies_when:
+      any_of:
+        # Node-сторона: НЕ private И есть хоть один entry-point/publish-signal.
+        - all_of:
+            - has_file: package.json
+            - not:
+                config_value: { path: package.json, jsonpath: "private", equals: true }
+            - any_of:
+                - config_value: { path: package.json, jsonpath: "publishConfig", op: present }
+                - config_value: { path: package.json, jsonpath: "bin",           op: present }
+                - config_value: { path: package.json, jsonpath: "main",          op: present }
+                - config_value: { path: package.json, jsonpath: "exports",       op: present }
+                - config_value: { path: package.json, jsonpath: "module",        op: present }
+        # PHP-сторона: composer.json есть, name задан, type ≠ project (project = app).
+        - all_of:
+            - has_file: composer.json
+            - config_value: { path: composer.json, jsonpath: "name", op: present }
+            - not:
+                config_value: { path: composer.json, jsonpath: "type", op: equals, equals: "project" }
+    storage: level
+    default_target: L4
+    fact_sources:
+      - package.json
+      - composer.json
+      - LICENSE
+      - LICENSE.md
+      - LICENSE.txt
+    levels:
+      L1:
+        requires:
+          any_of:
+            - all_of:
+                - config_value: { path: package.json, jsonpath: "name",    op: present }
+                - config_value: { path: package.json, jsonpath: "version", op: present }
+                - config_value: { path: package.json, jsonpath: "license", op: present }
+            - all_of:
+                - config_value: { path: composer.json, jsonpath: "name",    op: present }
+                - config_value: { path: composer.json, jsonpath: "license", op: present }
+      L2:
+        requires:
+          any_of:
+            - all_of:
+                - config_value: { path: package.json, jsonpath: "description", op: present }
+                - config_value: { path: package.json, jsonpath: "repository",  op: present }
+                - any_of:
+                    - has_file: LICENSE
+                    - has_file: LICENSE.md
+                    - has_file: LICENSE.txt
+            - all_of:
+                - config_value: { path: composer.json, jsonpath: "description", op: present }
+                - any_of:
+                    - has_file: LICENSE
+                    - has_file: LICENSE.md
+      L3:
+        requires:
+          any_of:
+            - all_of:
+                - config_value: { path: package.json, jsonpath: "files", op: present }
+                - any_of:
+                    - config_value: { path: package.json, jsonpath: "bin",     op: present }
+                    - config_value: { path: package.json, jsonpath: "main",    op: present }
+                    - config_value: { path: package.json, jsonpath: "exports", op: present }
+            - all_of:
+                - config_value: { path: composer.json, jsonpath: "autoload", op: present }
+                - config_value: { path: composer.json, jsonpath: "type",     op: present }
+      L4:
+        requires:
+          any_of:
+            - all_of:
+                - config_value: { path: package.json, jsonpath: "publishConfig", op: present }
+                - config_value: { path: package.json, jsonpath: "homepage",      op: present }
+                - config_value: { path: package.json, jsonpath: "bugs",          op: present }
+            - config_value: { path: composer.json, jsonpath: "extra.publish", op: present }

package/src/audit.ts

@@ -2,6 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import type { Rubric, LevelName } from './rubric.ts';
 import { findSubPackages, stackForDir, type Ctx } from './facts.ts';
+import { evalPredicate } from './evaluator.ts';
 import type { Override, VdxManifest } from './manifest.ts';
 import { evalAxis, projectLevel, type AxisResult } from './scoring.ts';
 
@@ -115,6 +116,16 @@ export function audit(
       });
       continue;
     }
+    if (axis.applies_when && !evalPredicate(axis.applies_when, evalCtx)) {
+      perAxis.push({
+        axis_id: axis.id,
+        class: axis.class,
+        achieved: 'L0',
+        target: axis.default_target,
+        drift_kind: 'excluded',
+      });
+      continue;
+    }
     const achieved = evalAxis(axis, evalCtx);
     const ov = overrideByAxis.get(axis.id);
     const target = (ov?.target as LevelName) ?? axis.default_target;

package/src/index.ts

@@ -14,7 +14,7 @@ function usage(): never {
   process.stderr.write(
     `Usage:
   vdx audit <project_path> [--rubric <path>] [--stack <stack>] [--json]
-  vdx init  <project_path> [--baseline <ref>] [--dry-run] [--force]
+  vdx init  <project_path> [--stack <id>] [--baseline <ref>] [--dry-run] [--force]
 `,
   );
   process.exit(1);
@@ -86,10 +86,19 @@ function cmdInit(opts: ParsedArgs): void {
 
   const baselineFlag = opts.flags.baseline;
   const baseline = typeof baselineFlag === 'string' ? baselineFlag : undefined;
-  const plan = planInit(projectRoot, baseline ? { baseline } : {});
+  const stackFlag = opts.flags.stack;
+  const stackOverride = typeof stackFlag === 'string' ? stackFlag : undefined;
+  const plan = planInit(projectRoot, {
+    ...(baseline ? { baseline } : {}),
+    ...(stackOverride ? { stack: stackOverride } : {}),
+  });
 
   process.stdout.write(renderPlanSummary(plan));
 
+  for (const w of plan.warnings) {
+    process.stderr.write(`\n⚠ ${w}\n`);
+  }
+
   if (opts.flags['dry-run']) {
     process.stderr.write('\n[dry-run] mise.toml / AGENTS.md не записаны.\n');
     return;

package/src/init.ts

@@ -7,12 +7,14 @@ import {
   readText,
   listAllTasks,
   autoDetectStack,
+  findSubPackages,
+  type SubPackage,
 } from './facts.ts';
 
 export const STANDARD_VERBS = ['up', 'down', 'build', 'test', 'check', 'fix'] as const;
 export type Verb = (typeof STANDARD_VERBS)[number];
 
-export const DEFAULT_BASELINE = 'github.com/VoDmAl/vdx-rubric-vodmal@v0.2.2';
+export const DEFAULT_BASELINE = 'github.com/VoDmAl/vdx-rubric-vodmal@v0.3.1';
 
 const VERB_ALIASES: Record<Verb, string[]> = {
   up: ['docker:up', 'docker-up', 'docker:up:detached', 'start'],
@@ -41,6 +43,10 @@ export interface VerbMapping {
 export interface InitPlan {
   projectRoot: string;
   stack: string;
+  /** Was `stack` derived from autoDetectStack (false) or supplied via --stack (true). */
+  stackOverridden: boolean;
+  /** Non-null only when stack === 'meta' and resolved a single nested manifest. */
+  primarySubpackage: string | null;
   pkgManager: 'composer' | 'npm' | 'pnpm' | 'yarn' | null;
   tools: Record<string, string>;
   mappings: VerbMapping[];
@@ -49,6 +55,8 @@ export interface InitPlan {
   agentsMdPath: string;
   agentsMdContent: string;
   baseline: string;
+  /** Human-readable advisories for the user — printed to stderr by the CLI. */
+  warnings: string[];
 }
 
 function detectNodePackageManager(projectRoot: string): 'pnpm' | 'yarn' | 'npm' {
@@ -67,6 +75,15 @@ function renderRunCommand(task: string, stack: string, projectRoot: string): str
   return task;
 }
 
+function renderRunCommandInSubpackage(
+  task: string,
+  subStack: string,
+  subAbs: string,
+  subRel: string,
+): string {
+  return `cd ${subRel} && ${renderRunCommand(task, subStack, subAbs)}`;
+}
+
 function pickPrefixGroup(prefixes: string[], tasks: Set<string>, verb: Verb): string | null {
   if (prefixes.length === 0) return null;
   // Prefer entries that look like a canonical "prod/dist/release" first, then any.
@@ -135,12 +152,23 @@ export function renderMiseToml(
   mappings: VerbMapping[],
   stack: string,
   baseline: string,
+  primarySubpackage: string | null = null,
 ): string {
   const out: string[] = [];
   out.push('# Generated by vdx init. The [vdx] block is metadata for vdx audit.');
   out.push('# Lifecycle verbs follow the vdx contract: up/down/build/test/check/fix.');
   out.push('');
 
+  if (stack === 'unknown' || stack === 'monorepo') {
+    out.push(
+      '# TODO(vdx): stack auto-detection вернул "' +
+        stack +
+        '". Замени на php/node/go/python/meta',
+    );
+    out.push('#   и заполни [tasks.*] блоки руками, либо перегенери: vdx init . --stack <id>.');
+    out.push('');
+  }
+
   if (Object.keys(tools).length > 0) {
     out.push('[tools]');
     for (const [k, v] of Object.entries(tools)) {
@@ -161,6 +189,9 @@ export function renderMiseToml(
   out.push('schema_version = "0.2"');
   out.push(`baseline = ${quoteToml(baseline)}`);
   out.push(`stack = ${quoteToml(stack)}`);
+  if (primarySubpackage) {
+    out.push(`primary_subpackage = ${quoteToml(primarySubpackage)}`);
+  }
   const verbsList = mappings
     .filter((m) => m.runCommand)
     .map((m) => quoteToml(m.verb))
@@ -217,36 +248,93 @@ export function buildAgentsMd(existing: string | null, section: string): string
   return existing + sep + section + '\n';
 }
 
-export function planInit(projectRoot: string, opts: { baseline?: string } = {}): InitPlan {
-  const stack = autoDetectStack(projectRoot);
-  const ctx: Ctx = { projectRoot, stack, cache: new Map() };
-  const tasks = listAllTasks(ctx);
+export function planInit(
+  projectRoot: string,
+  opts: { baseline?: string; stack?: string } = {},
+): InitPlan {
+  const detectedStack = autoDetectStack(projectRoot);
+  const stackOverridden = opts.stack !== undefined && opts.stack !== detectedStack;
+  const stack = opts.stack ?? detectedStack;
+  const warnings: string[] = [];
+
+  // For meta-stack — try to resolve a single nested subpackage and scan it for tasks.
+  let primarySubpackage: string | null = null;
+  let scanRoot = projectRoot;
+  let scanStack = stack;
+
+  if (stack === 'meta') {
+    const subs: SubPackage[] = findSubPackages(projectRoot);
+    if (subs.length === 1) {
+      primarySubpackage = subs[0]!.relPath;
+      scanRoot = path.join(projectRoot, primarySubpackage);
+      scanStack = subs[0]!.stack;
+    } else if (subs.length === 0) {
+      warnings.push(
+        'stack="meta", но nested manifest не найден. mise.toml будет иметь пустой verbs[]; ' +
+          'заполни [tasks.*] руками.',
+      );
+    } else {
+      const list = subs.map((s) => `${s.relPath}(${s.stack})`).join(', ');
+      warnings.push(
+        `stack="meta", найдено несколько subpackages: ${list}. ` +
+          'primary_subpackage не выбран; укажи его руками в [vdx] блоке.',
+      );
+    }
+  } else if (!stackOverridden && (detectedStack === 'unknown' || detectedStack === 'monorepo')) {
+    if (detectedStack === 'unknown') {
+      warnings.push(
+        'autoDetectStack вернул "unknown" — в корне нет manifest и нет subpackages. ' +
+          'Передай --stack <id> (php|node|go|python|meta) либо отредактируй mise.toml вручную.',
+      );
+    } else {
+      const subs = findSubPackages(projectRoot);
+      const list = subs.map((s) => `${s.relPath}(${s.stack})`).join(', ');
+      warnings.push(
+        `autoDetectStack вернул "monorepo": ${list}. ` +
+          'Передай --stack <id> чтобы выбрать конкретный стек, либо --stack meta + укажи primary_subpackage.',
+      );
+    }
+  }
+
+  const scanCtx: Ctx = { projectRoot: scanRoot, stack: scanStack, cache: new Map() };
+  const tasks = listAllTasks(scanCtx);
 
   const mappings: VerbMapping[] = STANDARD_VERBS.map((verb) => {
     const native = mapVerb(verb, tasks);
-    return {
-      verb,
-      nativeTask: native,
-      runCommand: native ? renderRunCommand(native, stack, projectRoot) : null,
-    };
+    let runCommand: string | null = null;
+    if (native) {
+      runCommand =
+        primarySubpackage !== null
+          ? renderRunCommandInSubpackage(native, scanStack, scanRoot, primarySubpackage)
+          : renderRunCommand(native, stack, projectRoot);
+    }
+    return { verb, nativeTask: native, runCommand };
   });
 
-  const tools = collectTools(ctx);
+  // tools читаем из root независимо: для PHP/Node корневой manifest часто
+  // содержит engines/require php; для meta-проектов вынос tool-версий в
+  // root mise.toml — общая практика.
+  const rootCtx: Ctx = { projectRoot, stack, cache: new Map() };
+  const tools = collectTools(rootCtx);
   const baseline = opts.baseline ?? DEFAULT_BASELINE;
-  const miseTomlContent = renderMiseToml(tools, mappings, stack, baseline);
+  const miseTomlContent = renderMiseToml(tools, mappings, stack, baseline, primarySubpackage);
 
   const agentsMdPath = path.join(projectRoot, 'AGENTS.md');
-  const existingAgents = fileExists(ctx, 'AGENTS.md') ? readText(ctx, 'AGENTS.md') : null;
+  const existingAgents = fileExists(rootCtx, 'AGENTS.md') ? readText(rootCtx, 'AGENTS.md') : null;
   const section = renderAgentsCommandsSection(mappings, baseline);
   const agentsMdContent = buildAgentsMd(existingAgents, section);
 
   let pkgManager: InitPlan['pkgManager'] = null;
-  if (stack === 'php') pkgManager = 'composer';
-  else if (stack === 'node') pkgManager = detectNodePackageManager(projectRoot);
+  const pmStack = primarySubpackage ? scanStack : stack;
+  const pmRoot = primarySubpackage ? scanRoot : projectRoot;
+  if (pmStack === 'php') pkgManager = 'composer';
+  else if (pmStack === 'node') pkgManager = detectNodePackageManager(pmRoot);
 
   return {
     projectRoot,
     stack,
+    stackOverridden,
+    primarySubpackage,
     pkgManager,
     tools,
     mappings,
@@ -255,6 +343,7 @@ export function planInit(projectRoot: string, opts: { baseline?: string } = {}):
     agentsMdPath,
     agentsMdContent,
     baseline,
+    warnings,
   };
 }
 
@@ -272,10 +361,23 @@ export function renderPlanSummary(plan: InitPlan): string {
   const lines: string[] = [];
   lines.push(`# vdx init plan`);
   lines.push('');
-  lines.push(`- **Project**: ${plan.projectRoot}`);
-  lines.push(`- **Stack**: ${plan.stack}`);
+  lines.push(
+    `- **Project**: ${plan.projectRoot}`,
+  );
+  lines.push(
+    `- **Stack**: ${plan.stack}${plan.stackOverridden ? ' (via --stack)' : ''}`,
+  );
+  if (plan.primarySubpackage) {
+    lines.push(`- **Primary subpackage**: ${plan.primarySubpackage}`);
+  }
   if (plan.pkgManager) lines.push(`- **Package manager**: ${plan.pkgManager}`);
   lines.push(`- **Baseline**: ${plan.baseline}`);
+  if (plan.warnings.length > 0) {
+    lines.push('');
+    lines.push('## ⚠ Warnings');
+    lines.push('');
+    for (const w of plan.warnings) lines.push(`- ${w}`);
+  }
   if (Object.keys(plan.tools).length > 0) {
     const toolStr = Object.entries(plan.tools)
       .map(([k, v]) => `${k}=${v}`)

package/src/rubric.ts

@@ -30,6 +30,7 @@ export interface Axis {
   levels?: Partial<Record<LevelName, { requires: Predicate }>>;
   stack_implementations?: Record<string, StackImpl>;
   applies_to?: string[];
+  applies_when?: Predicate;
 }
 
 export interface Rubric {