@vodmal/vdx-cli 0.2.0

package/src/init.ts

@@ -0,0 +1,309 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+  Ctx,
+  fileExists,
+  readJson,
+  readText,
+  listAllTasks,
+  autoDetectStack,
+} 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';
+
+const VERB_ALIASES: Record<Verb, string[]> = {
+  up: ['docker:up', 'docker-up', 'docker:up:detached', 'start'],
+  down: ['docker:down', 'docker-down', 'stop'],
+  build: ['docker:build', 'build:prod', 'build-prod', 'build:dev', 'build-dev', 'build:assets'],
+  test: ['phpunit', 'test:unit', 'test-unit', 'test:unit:phpunit', 'jest', 'vitest'],
+  check: ['lint', 'check:config', 'check:before:commit', 'check:code:static', 'check:code:lint'],
+  fix: ['fix:ecs', 'format', 'lint:fix'],
+};
+
+const VERB_PREFIX_GROUPS: Record<Verb, string[]> = {
+  up: [],
+  down: [],
+  build: ['build:', 'build-'],
+  test: ['test:', 'test-'],
+  check: ['check:', 'check-'],
+  fix: ['fix:', 'fix-'],
+};
+
+export interface VerbMapping {
+  verb: Verb;
+  nativeTask: string | null;
+  runCommand: string | null;
+}
+
+export interface InitPlan {
+  projectRoot: string;
+  stack: string;
+  pkgManager: 'composer' | 'npm' | 'pnpm' | 'yarn' | null;
+  tools: Record<string, string>;
+  mappings: VerbMapping[];
+  miseTomlPath: string;
+  miseTomlContent: string;
+  agentsMdPath: string;
+  agentsMdContent: string;
+  baseline: string;
+}
+
+function detectNodePackageManager(projectRoot: string): 'pnpm' | 'yarn' | 'npm' {
+  if (fs.existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(projectRoot, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+}
+
+function renderRunCommand(task: string, stack: string, projectRoot: string): string {
+  if (stack === 'php') return `composer ${task}`;
+  if (stack === 'node') {
+    const pm = detectNodePackageManager(projectRoot);
+    if (pm === 'yarn') return `yarn ${task}`;
+    return `${pm} run ${task}`;
+  }
+  return task;
+}
+
+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.
+  const canonHints = ['prod', 'production', 'release', 'dist', 'all'];
+  const candidates: string[] = [];
+  for (const t of tasks) {
+    for (const pfx of prefixes) {
+      if (t.startsWith(pfx) && t !== verb) {
+        candidates.push(t);
+        break;
+      }
+    }
+  }
+  if (candidates.length === 0) return null;
+  for (const hint of canonHints) {
+    const hit = candidates.find((c) => c.toLowerCase().includes(hint));
+    if (hit) return hit;
+  }
+  candidates.sort((a, b) => a.length - b.length);
+  return candidates[0] ?? null;
+}
+
+export function mapVerb(verb: Verb, tasks: Set<string>): string | null {
+  if (tasks.has(verb)) return verb;
+  for (const alt of VERB_ALIASES[verb]) {
+    if (tasks.has(alt)) return alt;
+  }
+  return pickPrefixGroup(VERB_PREFIX_GROUPS[verb], tasks, verb);
+}
+
+function collectTools(ctx: Ctx): Record<string, string> {
+  const tools: Record<string, string> = {};
+  const composer = readJson(ctx, 'composer.json');
+  if (composer?.require?.php && typeof composer.require.php === 'string') {
+    tools.php = stripVersionConstraint(composer.require.php);
+  }
+  const pkg = readJson(ctx, 'package.json');
+  if (pkg?.engines?.node && typeof pkg.engines.node === 'string') {
+    tools.node = stripVersionConstraint(pkg.engines.node);
+  }
+  return tools;
+}
+
+function stripVersionConstraint(raw: string): string {
+  const m = raw.match(/(\d+(?:\.\d+){0,2})/);
+  if (m && m[1]) return m[1];
+  return raw.trim();
+}
+
+const VERB_DESCRIPTIONS: Record<Verb, string> = {
+  up: 'Start the project locally',
+  down: 'Stop the project',
+  build: 'Build assets / artifacts',
+  test: 'Run tests',
+  check: 'Quality checks (read-only)',
+  fix: 'Auto-fixes',
+};
+
+function quoteToml(s: string): string {
+  // mise tasks accept basic strings; only escape backslash and double quote.
+  return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+
+export function renderMiseToml(
+  tools: Record<string, string>,
+  mappings: VerbMapping[],
+  stack: string,
+  baseline: string,
+): 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 (Object.keys(tools).length > 0) {
+    out.push('[tools]');
+    for (const [k, v] of Object.entries(tools)) {
+      out.push(`${k} = ${quoteToml(v)}`);
+    }
+    out.push('');
+  }
+
+  for (const m of mappings) {
+    if (!m.runCommand) continue;
+    out.push(`[tasks.${m.verb}]`);
+    out.push(`description = ${quoteToml(VERB_DESCRIPTIONS[m.verb])}`);
+    out.push(`run = ${quoteToml(m.runCommand)}`);
+    out.push('');
+  }
+
+  out.push('[vdx]');
+  out.push('schema_version = "0.2"');
+  out.push(`baseline = ${quoteToml(baseline)}`);
+  out.push(`stack = ${quoteToml(stack)}`);
+  const verbsList = mappings
+    .filter((m) => m.runCommand)
+    .map((m) => quoteToml(m.verb))
+    .join(', ');
+  out.push(`verbs = [${verbsList}]`);
+  out.push('');
+
+  return out.join('\n');
+}
+
+const AGENTS_MARKER_OPEN = '<!-- vdx:commands -->';
+const AGENTS_MARKER_CLOSE = '<!-- /vdx:commands -->';
+
+export function renderAgentsCommandsSection(
+  mappings: VerbMapping[],
+  baseline: string,
+): string {
+  const lines: string[] = [];
+  lines.push(AGENTS_MARKER_OPEN);
+  lines.push('## Commands');
+  lines.push('');
+  lines.push(
+    `This project follows the vdx lifecycle interface (baseline: ${baseline}).`,
+  );
+  lines.push('');
+  lines.push('| Verb | What it does | Native command |');
+  lines.push('|------|--------------|----------------|');
+  for (const m of mappings) {
+    if (!m.runCommand) {
+      lines.push(`| \`mise run ${m.verb}\` | ${VERB_DESCRIPTIONS[m.verb]} | _(not mapped)_ |`);
+    } else {
+      lines.push(
+        `| \`mise run ${m.verb}\` | ${VERB_DESCRIPTIONS[m.verb]} | \`${m.runCommand}\` |`,
+      );
+    }
+  }
+  lines.push(AGENTS_MARKER_CLOSE);
+  return lines.join('\n');
+}
+
+export function buildAgentsMd(existing: string | null, section: string): string {
+  if (existing === null) {
+    return `# AGENTS\n\nProject agent guide.\n\n${section}\n`;
+  }
+  const openIdx = existing.indexOf(AGENTS_MARKER_OPEN);
+  const closeIdx = existing.indexOf(AGENTS_MARKER_CLOSE);
+  if (openIdx !== -1 && closeIdx !== -1 && closeIdx > openIdx) {
+    const before = existing.slice(0, openIdx);
+    const after = existing.slice(closeIdx + AGENTS_MARKER_CLOSE.length);
+    return before + section + after;
+  }
+  // No markers — append.
+  const sep = existing.endsWith('\n') ? '\n' : '\n\n';
+  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);
+
+  const mappings: VerbMapping[] = STANDARD_VERBS.map((verb) => {
+    const native = mapVerb(verb, tasks);
+    return {
+      verb,
+      nativeTask: native,
+      runCommand: native ? renderRunCommand(native, stack, projectRoot) : null,
+    };
+  });
+
+  const tools = collectTools(ctx);
+  const baseline = opts.baseline ?? DEFAULT_BASELINE;
+  const miseTomlContent = renderMiseToml(tools, mappings, stack, baseline);
+
+  const agentsMdPath = path.join(projectRoot, 'AGENTS.md');
+  const existingAgents = fileExists(ctx, 'AGENTS.md') ? readText(ctx, '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);
+
+  return {
+    projectRoot,
+    stack,
+    pkgManager,
+    tools,
+    mappings,
+    miseTomlPath: path.join(projectRoot, 'mise.toml'),
+    miseTomlContent,
+    agentsMdPath,
+    agentsMdContent,
+    baseline,
+  };
+}
+
+export function writeInit(plan: InitPlan, opts: { force: boolean }): void {
+  if (fs.existsSync(plan.miseTomlPath) && !opts.force) {
+    throw new Error(
+      `mise.toml уже существует: ${plan.miseTomlPath}. Используй --force для перезаписи.`,
+    );
+  }
+  fs.writeFileSync(plan.miseTomlPath, plan.miseTomlContent, 'utf8');
+  fs.writeFileSync(plan.agentsMdPath, plan.agentsMdContent, 'utf8');
+}
+
+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}`);
+  if (plan.pkgManager) lines.push(`- **Package manager**: ${plan.pkgManager}`);
+  lines.push(`- **Baseline**: ${plan.baseline}`);
+  if (Object.keys(plan.tools).length > 0) {
+    const toolStr = Object.entries(plan.tools)
+      .map(([k, v]) => `${k}=${v}`)
+      .join(', ');
+    lines.push(`- **Tools**: ${toolStr}`);
+  }
+  lines.push('');
+  lines.push('## Verb mappings');
+  lines.push('');
+  lines.push('| Verb | Native task | Generated `run` |');
+  lines.push('|------|-------------|-----------------|');
+  for (const m of plan.mappings) {
+    if (m.runCommand) {
+      lines.push(`| \`${m.verb}\` | \`${m.nativeTask}\` | \`${m.runCommand}\` |`);
+    } else {
+      lines.push(`| \`${m.verb}\` | _(not found)_ | _(skipped)_ |`);
+    }
+  }
+  lines.push('');
+  const unmatched = plan.mappings.filter((m) => !m.runCommand).map((m) => m.verb);
+  if (unmatched.length > 0) {
+    lines.push(`> Not mapped: ${unmatched.join(', ')}. Add тиски в \`mise.toml\` вручную.`);
+    lines.push('');
+  }
+  lines.push('## Generated mise.toml');
+  lines.push('');
+  lines.push('```toml');
+  lines.push(plan.miseTomlContent);
+  lines.push('```');
+  return lines.join('\n') + '\n';
+}

package/src/manifest.ts

@@ -0,0 +1,52 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as TOML from 'smol-toml';
+import YAML from 'js-yaml';
+
+export interface VdxManifest {
+  schema_version?: string;
+  baseline?: string;
+  stack?: string;
+  primary_language?: string;
+  primary_subpackage?: string;
+  verbs?: string[];
+  shared_infra?: {
+    provider?: string;
+    precheck?: boolean;
+    healthcheck_url?: string;
+  };
+  success_path?: Record<string, unknown>;
+  audit?: Record<string, unknown>;
+}
+
+export interface Override {
+  axis: string;
+  target?: string;
+  suppress?: boolean;
+  reason: string;
+  until?: string;
+}
+
+export function loadManifest(projectRoot: string): VdxManifest | null {
+  const miseToml = path.join(projectRoot, 'mise.toml');
+  if (!fs.existsSync(miseToml)) return null;
+  try {
+    const text = fs.readFileSync(miseToml, 'utf8');
+    const data = TOML.parse(text) as { vdx?: VdxManifest };
+    return data?.vdx ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function loadOverrides(projectRoot: string): Override[] {
+  const file = path.join(projectRoot, '.vdx-overrides.yml');
+  if (!fs.existsSync(file)) return [];
+  try {
+    const text = fs.readFileSync(file, 'utf8');
+    const data = YAML.load(text) as { overrides?: Override[] };
+    return data?.overrides ?? [];
+  } catch {
+    return [];
+  }
+}

package/src/mcp-server.ts

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { spawn } from 'node:child_process';
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import * as TOML from 'smol-toml';
+
+import { loadRubric } from './rubric.ts';
+import { loadManifest, loadOverrides } from './manifest.ts';
+import { autoDetectStack, readToml, type Ctx } from './facts.ts';
+import { audit } from './audit.ts';
+import { reportJson, reportMarkdown } from './report.ts';
+import { STANDARD_VERBS, type Verb } from './init.ts';
+import { resolveDefaultRubric } from './defaults.ts';
+
+const DEFAULT_RUBRIC = resolveDefaultRubric();
+
+function resolveProjectRoot(argv: string[]): string {
+  const i = argv.indexOf('--project');
+  if (i !== -1 && argv[i + 1]) return path.resolve(argv[i + 1]!);
+  return process.cwd();
+}
+
+const PROJECT_ROOT = resolveProjectRoot(process.argv);
+
+function freshCtx(): Ctx {
+  const stack = autoDetectStack(PROJECT_ROOT);
+  return { projectRoot: PROJECT_ROOT, stack, cache: new Map() };
+}
+
+function readMiseToml(): any {
+  return readToml(freshCtx(), 'mise.toml');
+}
+
+function getVdxBlock(): any {
+  const t = readMiseToml();
+  return t?.vdx ?? null;
+}
+
+function getTasks(): Record<string, any> {
+  const t = readMiseToml();
+  return (t?.tasks as Record<string, any>) ?? {};
+}
+
+interface RunResult {
+  ok: boolean;
+  exit_code: number;
+  stdout: string;
+  stderr: string;
+  duration_ms: number;
+}
+
+function spawnVerb(verb: Verb, extraArgs: string[]): Promise<RunResult> {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const child = spawn('mise', ['run', verb, ...extraArgs], {
+      cwd: PROJECT_ROOT,
+      env: process.env,
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (b) => {
+      stdout += b.toString();
+    });
+    child.stderr.on('data', (b) => {
+      stderr += b.toString();
+    });
+    child.on('error', (e) => {
+      resolve({
+        ok: false,
+        exit_code: -1,
+        stdout,
+        stderr: stderr + `\nspawn-error: ${e.message}`,
+        duration_ms: Date.now() - started,
+      });
+    });
+    child.on('close', (code) => {
+      resolve({
+        ok: code === 0,
+        exit_code: code ?? -1,
+        stdout,
+        stderr,
+        duration_ms: Date.now() - started,
+      });
+    });
+  });
+}
+
+function buildCapabilities() {
+  const vdxBlock = getVdxBlock();
+  const tasks = getTasks();
+  const verbsList = (vdxBlock?.verbs as string[] | undefined) ?? STANDARD_VERBS.slice();
+  const verbs = verbsList.map((name) => {
+    const t = tasks[name];
+    const nativeCommand =
+      t && typeof t === 'object' && typeof t.run === 'string' ? t.run : null;
+    return {
+      name,
+      has_manifest: Boolean(t),
+      native_command: nativeCommand,
+    };
+  });
+
+  const sharedInfra = vdxBlock?.shared_infra
+    ? {
+        provider: String(vdxBlock.shared_infra.provider ?? ''),
+        precheck: Boolean(vdxBlock.shared_infra.precheck),
+        is_running: false,
+      }
+    : null;
+
+  return {
+    schema_version: String(vdxBlock?.schema_version ?? '0.2'),
+    stack: String(vdxBlock?.stack ?? autoDetectStack(PROJECT_ROOT)),
+    baseline: String(vdxBlock?.baseline ?? `file://${DEFAULT_RUBRIC}`),
+    verbs,
+    shared_infra: sharedInfra,
+    last_verified: vdxBlock?.success_path?.last_verified ?? null,
+  };
+}
+
+function buildAuditPayload(baselineOverride: string | undefined, fmt: 'json' | 'markdown') {
+  const ctx = freshCtx();
+  const rubricPath = DEFAULT_RUBRIC;
+  const rubric = loadRubric(rubricPath);
+  const manifest = loadManifest(PROJECT_ROOT);
+  const overrides = loadOverrides(PROJECT_ROOT);
+  const baselineRef = baselineOverride ?? manifest?.baseline ?? `file://${rubricPath}`;
+  const result = audit(rubric, ctx, overrides, baselineRef, manifest);
+  if (fmt === 'markdown') return reportMarkdown(result);
+  return reportJson(result);
+}
+
+function recordSuccessPath(input: {
+  verbs: { name: string; command: string }[];
+  shared_infra?: { provider: string; precheck: boolean };
+  notes?: string;
+}): { ok: boolean; manifest_path: string; agents_md_updated: boolean } {
+  const manifestPath = path.join(PROJECT_ROOT, 'mise.toml');
+  let doc: any = {};
+  if (fs.existsSync(manifestPath)) {
+    const text = fs.readFileSync(manifestPath, 'utf8');
+    try {
+      doc = TOML.parse(text);
+    } catch (e: any) {
+      throw new Error(`mise.toml parse error: ${e?.message}`);
+    }
+  }
+
+  doc.tasks = doc.tasks ?? {};
+  for (const v of input.verbs) {
+    doc.tasks[v.name] = { run: v.command };
+  }
+
+  doc.vdx = doc.vdx ?? {
+    schema_version: '0.2',
+    baseline: 'github.com/VoDmAl/vdx-rubric-vodmal@v0.2.1',
+    stack: autoDetectStack(PROJECT_ROOT),
+  };
+  doc.vdx.verbs = input.verbs.map((v) => v.name);
+
+  if (input.shared_infra) {
+    doc.vdx.shared_infra = {
+      provider: input.shared_infra.provider,
+      precheck: input.shared_infra.precheck,
+    };
+  }
+
+  doc.vdx.success_path = {
+    last_verified: new Date().toISOString().slice(0, 10),
+    verified_by: 'vdx-mcp',
+    ...(input.notes ? { notes: input.notes } : {}),
+  };
+
+  const newText = TOML.stringify(doc);
+  fs.writeFileSync(manifestPath, newText, 'utf8');
+
+  return { ok: true, manifest_path: manifestPath, agents_md_updated: false };
+}
+
+const server = new McpServer({
+  name: 'vdx',
+  version: '0.1.0',
+});
+
+server.registerTool(
+  'list_capabilities',
+  {
+    description:
+      'Возвращает manifest проекта: stack, baseline, доступные глаголы и их native команды, shared_infra и last_verified. Самый частый вызов агента, входящего в проект.',
+    inputSchema: {},
+  },
+  async () => {
+    const payload = buildCapabilities();
+    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+  },
+);
+
+for (const verb of STANDARD_VERBS) {
+  server.registerTool(
+    `vdx_${verb}`,
+    {
+      description: `Запускает lifecycle-глагол '${verb}' через 'mise run ${verb}'. Возвращает stdout/stderr/exit_code/duration_ms.`,
+      inputSchema: { args: z.array(z.string()).optional() },
+    },
+    async ({ args }) => {
+      const result = await spawnVerb(verb, args ?? []);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    },
+  );
+}
+
+server.registerTool(
+  'vdx_audit',
+  {
+    description:
+      'Запускает аудит проекта против owner-рубрики. Возвращает JSON-отчёт по контракту (per_axis с уровнями) или markdown.',
+    inputSchema: {
+      baseline: z.string().optional(),
+      format: z.enum(['json', 'markdown']).optional(),
+    },
+  },
+  async ({ baseline, format }) => {
+    const fmt = format ?? 'json';
+    const payload = buildAuditPayload(baseline, fmt);
+    return { content: [{ type: 'text', text: payload }] };
+  },
+);
+
+server.registerTool(
+  'vdx_record_success_path',
+  {
+    description:
+      'Записывает обнаруженные команды в [tasks.X] секцию mise.toml + обновляет [vdx.success_path]. Используется после успешной верификации команд агентом.',
+    inputSchema: {
+      verbs: z.array(z.object({ name: z.string(), command: z.string() })),
+      shared_infra: z
+        .object({ provider: z.string(), precheck: z.boolean() })
+        .optional(),
+      notes: z.string().optional(),
+    },
+  },
+  async ({ verbs, shared_infra, notes }) => {
+    const args: Parameters<typeof recordSuccessPath>[0] = { verbs };
+    if (shared_infra) args.shared_infra = shared_infra;
+    if (notes !== undefined) args.notes = notes;
+    const result = recordSuccessPath(args);
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  },
+);
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write(`vdx-mcp connected (project: ${PROJECT_ROOT})\n`);
+}
+
+main().catch((e) => {
+  process.stderr.write(`vdx-mcp fatal: ${e?.message ?? e}\n`);
+  process.exit(1);
+});