@vodmal/vdx-cli 0.14.0 → 0.15.0

package/README.md

@@ -26,7 +26,7 @@ ephemeral environment.
 
 **First command after install: `vdx doctor`** — it inspects your environment
 (Node version, `vdx` on PATH, git, mise, npm auth, container runtime, Claude
-Code plugin) and points to remedies for everything that's missing or
+Code plugin; in a project — git hooks and the commit author) and points to remedies for everything that's missing or
 sub-optimal.
 
 ## Use
@@ -85,7 +85,8 @@ The session's `{project}` is `[vdx] name` from the project's `mise.toml`, else t
 first file in the profile's `session.project_names` that has one, else the repo
 name. `vdx ai@<host>` runs the same command on `<host>` over ssh — that machine's vdx,
 profile and tmux, the path taken under its home directory; `--detach` only
-starts it. The machine's own label (`$VDX_HOST`) runs here.
+starts it. The machine's own label (`$VDX_HOST`) runs here. Where git knows no
+commit author, `vdx ai` proposes one (Enter writes it into `.git/config`).
 
 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

package/package.json

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

package/rubric/vdx-rubric.yaml

@@ -11,7 +11,7 @@ schema_version: "0.2"
 
 metadata:
   name: vdx-rubric-vodmal
-  version: "0.5.0"
+  version: "0.6.0"
   description: "Personal maturity rubric for multi-stack projects (vodmal)"
   owner: vodmal
   homepage: "https://github.com/vodmal/vdx-rubric"

package/src/ai.ts

@@ -6,6 +6,7 @@ import YAML from 'js-yaml';
 import { evalPredicate } from './evaluator.ts';
 import { autoDetectStack, readStructured, resolveConfigPath, type Ctx } from './facts.ts';
 import { loadManifest } from './manifest.ts';
+import { type Author, effectiveAuthor, isGitRepo, rankAuthors, scanPool, writeAuthor } from './author.ts';
 import type { Predicate } from './rubric.ts';
 
 /**
@@ -61,11 +62,17 @@ export interface SessionProfile {
   project_names?: NameSource[];
 }
 
+export interface GitProfile {
+  /** Directories whose repos are the neighbours an author is proposed from; default — the project's parent. */
+  author_pool?: string[];
+}
+
 export interface Environment {
   schema_version?: string;
   metadata?: Record<string, unknown>;
   agent?: AgentProfile;
   session?: SessionProfile;
+  git?: GitProfile;
 }
 
 export const ENVIRONMENT_ENV_VAR = 'VDX_ENVIRONMENT';
@@ -161,6 +168,14 @@ export function parseEnvironment(text: string, source: string): Environment {
       });
     }
   }
+
+  const gitDoc = envDoc.git;
+  if (gitDoc !== undefined) {
+    if (typeof gitDoc !== 'object' || gitDoc === null) fail('git', 'must be a mapping');
+    if (gitDoc.author_pool !== undefined && !isStringList(gitDoc.author_pool)) {
+      fail('git.author_pool', 'must be a list of directories');
+    }
+  }
   return envDoc;
 }
 
@@ -583,12 +598,37 @@ export interface AiDeps {
   processes: () => ProcInfo[];
   sleep: (ms: number) => void;
   confirmTimeoutMs: number;
+  /** One line from the person at the terminal, or null when there is none. */
+  ask: (prompt: string) => string | null;
 }
 
 export function sleepSync(ms: number): void {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 
+/** Read one line from the terminal, synchronously: the prompt runs before tmux takes it. */
+export function askLine(prompt: string): string | null {
+  process.stderr.write(prompt);
+  const buf = Buffer.alloc(256);
+  let text = '';
+  for (;;) {
+    let n: number;
+    try {
+      n = fs.readSync(0, buf, 0, buf.length, null);
+    } catch (e: any) {
+      if (e?.code === 'EAGAIN') {
+        sleepSync(50);
+        continue;
+      }
+      return null;
+    }
+    if (n === 0) return text === '' ? null : text.trim();
+    text += buf.toString('utf8', 0, n);
+    const nl = text.indexOf('\n');
+    if (nl >= 0) return text.slice(0, nl).trim();
+  }
+}
+
 export function defaultDeps(): AiDeps {
   return {
     env: process.env,
@@ -602,6 +642,7 @@ export function defaultDeps(): AiDeps {
     processes: listProcesses,
     sleep: sleepSync,
     confirmTimeoutMs: 30_000,
+    ask: askLine,
   };
 }
 
@@ -794,6 +835,61 @@ export function remoteAiArgs(input: {
   return [input.tty ? '-t' : '-T', host, script];
 }
 
+/** Where neighbour repos live: the profile's `git.author_pool`, else the project's parent directory. */
+export function authorPoolDirs(environment: Environment, projectRoot: string, home: string, profileDir: string): string[] {
+  const listed = environment.git?.author_pool;
+  if (!listed?.length) return [path.dirname(projectRoot)];
+  return listed.map((d) => path.resolve(profileDir, d.replace(/^~(?=$|\/)/, home)));
+}
+
+/**
+ * A repo without its own author makes git refuse to commit (`user.useConfigOnly`).
+ * At a terminal vdx proposes the likely author and Enter takes the first;
+ * without one it says so and goes on — a scripted start must not stop here.
+ * A running agent needs no restart: git reads the author at each commit.
+ */
+export function ensureAuthor(projectRoot: string, poolDirs: string[], deps: AiDeps, dryRun: boolean): void {
+  if (!isGitRepo(projectRoot)) return;
+  const current = effectiveAuthor(projectRoot);
+  if (current) {
+    if (dryRun) deps.out(`  author:   ${current.email} (${current.scope})\n`);
+    return;
+  }
+  const top = rankAuthors(projectRoot, scanPool(poolDirs)).slice(0, 3);
+  const q = shellQuote(projectRoot);
+  const command = (a: Author) =>
+    `git -C ${q} config --local user.name ${shellQuote(a.name)} && git -C ${q} config --local user.email ${shellQuote(a.email)}`;
+  if (dryRun) {
+    const proposal = top.length ? `; would propose ${top.map((c) => c.email).join(', ')}` : '';
+    deps.out(`  author:   none — git refuses to commit here${proposal}\n`);
+    return;
+  }
+  deps.log(`⚠ ${path.basename(projectRoot)}: no commit author of its own — git will refuse to commit here`);
+  if (!deps.interactive || top.length === 0) {
+    deps.log(`  set it: ${top[0] ? command(top[0]) : `git -C ${q} config --local user.email <address>`}`);
+    return;
+  }
+  top.forEach((c, i) => deps.log(`  ${i + 1}) ${c.name} <${c.email}>${c.why.length ? `   ${c.why.join('; ')}` : ''}`));
+  deps.log('  s) skip');
+  for (let tries = 0; tries < 2; tries++) {
+    const answer = deps.ask('Author [1]: ');
+    if (answer === null) return;
+    const a = answer.trim();
+    if (/^[sn]$/i.test(a)) {
+      deps.log('  skipped');
+      return;
+    }
+    const pick: Author | undefined =
+      a === '' ? top[0] : /^\d+$/.test(a) ? top[Number(a) - 1] : a.includes('@') ? { name: top[0]!.name, email: a } : undefined;
+    if (pick) {
+      if (writeAuthor(projectRoot, pick)) deps.log(`✓ ${pick.name} <${pick.email}> → .git/config`);
+      else deps.log(`✗ could not write .git/config — ${command(pick)}`);
+      return;
+    }
+    deps.log(`  1–${top.length}, an address, or s`);
+  }
+}
+
 export function runAiRemote(opts: AiOptions, host: string, deps: AiDeps, version: string): number {
   const projectPath = resolveProjectRoot(opts.path) ?? path.resolve(opts.path);
   const tty = deps.interactive && !opts.detach && !opts.dryRun;
@@ -839,12 +935,13 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
     return EXIT_USAGE;
   }
 
+  const profileDir = profilePath ? path.dirname(profilePath) : deps.home;
   const named = resolveProjectName({
     projectRoot,
     repo: projectIdentity(projectRoot),
     sources: environment.session?.project_names ?? [],
     home: deps.home,
-    profileDir: profilePath ? path.dirname(profilePath) : deps.home,
+    profileDir,
   });
 
   let plan: LaunchPlan;
@@ -876,10 +973,13 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
       ? findAgentPanes(tmux.panes(), deps.processes(), projectRoot, plan.command)
       : [];
 
+  const poolDirs = authorPoolDirs(environment, projectRoot, deps.home, profileDir);
   if (opts.dryRun) {
     deps.out(renderPlan(plan, multiplexer, running));
+    ensureAuthor(projectRoot, poolDirs, deps, true);
     return EXIT_OK;
   }
+  ensureAuthor(projectRoot, poolDirs, deps, false);
 
   if (multiplexer === 'none') {
     if (opts.restart) {

package/src/author.ts

@@ -0,0 +1,192 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+/**
+ * Who commits in a repo. The rule this serves: every repo carries its own
+ * author in `.git/config`, and git refuses where there is none
+ * (`user.useConfigOnly`). When a repo has none, vdx proposes one — the
+ * addresses some repo in the pool already carries, ranked by this repo's
+ * history, repos in the same remote group, and repos with a similar name.
+ */
+
+export interface Author {
+  name: string;
+  email: string;
+}
+
+export interface PoolRepo {
+  dir: string;
+  author: Author | null;
+  host: string;
+  group: string;
+  tokens: Set<string>;
+}
+
+export interface AuthorCandidate extends Author {
+  score: number;
+  why: string[];
+}
+
+function git(dir: string, args: string[]): string | null {
+  try {
+    return execFileSync('git', ['--no-optional-locks', '-C', dir, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function isGitRepo(dir: string): boolean {
+  return git(dir, ['rev-parse', '--git-dir']) !== null;
+}
+
+/** The address git would commit with here, and the scope it comes from; null when git knows none. */
+export function effectiveAuthor(dir: string): { email: string; scope: string } | null {
+  const out = git(dir, ['config', '--show-scope', '--get', 'user.email']);
+  if (!out) return null;
+  const [scope, email] = out.split('\t');
+  return email ? { email, scope: scope ?? '' } : null;
+}
+
+/** `git@host:group/repo.git`, `ssh://git@host:7999/group/repo.git` → host and group ("" when none). */
+export function remoteParts(url: string): { host: string; group: string; path: string } {
+  const m = url.match(/^(?:[a-z+]+:\/\/)?(?:[^@/]+@)?([^/:]+)(?::\d+)?[:/](.*?)(?:\.git)?\/?$/);
+  if (!m) return { host: '', group: '', path: '' };
+  const p = m[2]!;
+  return { host: m[1]!, group: p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : '', path: p };
+}
+
+/** Words that say nothing about whose repo it is. */
+const GENERIC = new Set([
+  'git', 'com', 'org', 'name', 'www', 'ssh', 'http', 'https', 'the', 'app', 'mcp',
+  'github', 'gitlab', 'dev', 'net', 'vorobyev', 'vodmal', 'dmitry',
+]);
+
+export function nameTokens(dir: string, remotePath: string): Set<string> {
+  return new Set(
+    `${path.basename(dir)} ${remotePath}`
+      .toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .filter((t) => t.length > 2 && !GENERIC.has(t)),
+  );
+}
+
+function describe(dir: string): PoolRepo {
+  const cfg = git(dir, ['config', '--local', '--get-regexp', '^(user\\.(name|email)|remote\\.origin\\.url)$']) ?? '';
+  const val = (key: string) =>
+    cfg.split('\n').find((l) => l.toLowerCase().startsWith(`${key} `))?.slice(key.length + 1).trim() ?? '';
+  const email = val('user.email');
+  const remote = remoteParts(val('remote.origin.url'));
+  return {
+    dir,
+    author: email ? { name: val('user.name'), email: email.toLowerCase() } : null,
+    host: remote.host,
+    group: remote.group,
+    tokens: nameTokens(dir, remote.path),
+  };
+}
+
+/** Git repos one level under each directory; the directories themselves are not repos. */
+export function scanPool(dirs: string[]): PoolRepo[] {
+  const seen = new Set<string>();
+  const out: PoolRepo[] = [];
+  for (const d of dirs) {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(d, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const dir = path.join(d, e.name);
+      if (!e.isDirectory() || seen.has(dir) || !fs.existsSync(path.join(dir, '.git'))) continue;
+      seen.add(dir);
+      out.push(describe(dir));
+    }
+  }
+  return out;
+}
+
+/**
+ * Weights measured 2026-09-30 against the owner's 38 repos with their own
+ * author, each guessed from the others: the right address came first in 31,
+ * among the first three in 37.
+ */
+const W_HISTORY = 1.0;
+const W_GROUP = 0.3;
+const W_HOST = 0.1;
+const W_TOKEN = 0.4;
+
+/** The pool's addresses, best first. Only addresses some pool repo carries are proposed. */
+export function rankAuthors(dir: string, pool: PoolRepo[]): AuthorCandidate[] {
+  const self = describe(dir);
+  const others = pool.filter((p) => p.author && path.resolve(p.dir) !== path.resolve(dir));
+  const names = new Map<string, Map<string, number>>();
+  for (const p of others) {
+    const byName = names.get(p.author!.email) ?? new Map<string, number>();
+    if (p.author!.name) byName.set(p.author!.name, (byName.get(p.author!.name) ?? 0) + 1);
+    names.set(p.author!.email, byName);
+  }
+  if (names.size === 0) return [];
+
+  const score = new Map<string, number>();
+  const why = new Map<string, string[]>();
+  const add = (email: string, s: number, reason?: string) => {
+    score.set(email, (score.get(email) ?? 0) + s);
+    if (reason) why.set(email, [...(why.get(email) ?? []), reason]);
+  };
+
+  // Counted by git: a per-commit log of a large repo overflows the output buffer.
+  const history = new Map<string, number>();
+  for (const line of (git(dir, ['shortlog', '-se', '--all']) ?? '').split('\n')) {
+    const m = line.match(/^\s*(\d+)\s+.*<([^>]*)>\s*$/);
+    const e = m?.[2]?.toLowerCase();
+    if (e && names.has(e)) history.set(e, (history.get(e) ?? 0) + Number(m![1]));
+  }
+  const total = [...history.values()].reduce((a, b) => a + b, 0);
+  for (const [e, n] of history) add(e, (W_HISTORY * n) / total, `history ${n}`);
+
+  const group = new Map<string, number>();
+  const similar = new Map<string, string[]>();
+  for (const p of others) {
+    const e = p.author!.email;
+    if (self.host && p.host === self.host) {
+      const same = Boolean(self.group) && p.group === self.group;
+      add(e, same ? W_GROUP : W_HOST);
+      if (same) group.set(e, (group.get(e) ?? 0) + 1);
+    }
+    const overlap = [...self.tokens].filter((t) => p.tokens.has(t)).length;
+    if (overlap > 0) {
+      add(e, W_TOKEN * overlap);
+      similar.set(e, [...(similar.get(e) ?? []), path.basename(p.dir)]);
+    }
+  }
+  for (const [e, n] of group) add(e, 0, `same group ${self.host}/${self.group}: ${n}`);
+  for (const [e, list] of similar) add(e, 0, `similar: ${list.slice(0, 3).join(', ')}`);
+
+  const ranked = [...score.entries()].sort((a, b) => b[1] - a[1]);
+  // Addresses with no signal still belong in the menu, after the rest, by how many repos carry them.
+  const repos = (e: string) => [...(names.get(e)?.values() ?? [])].reduce((a, b) => a + b, 0);
+  const unsignalled = [...names.keys()].filter((e) => !score.has(e)).sort((a, b) => repos(b) - repos(a));
+  for (const e of unsignalled) {
+    ranked.push([e, 0]);
+    why.set(e, [`in ${repos(e)} repos`]);
+  }
+
+  const fallbackName = [...names.values()].flatMap((m) => [...m.entries()]).sort((a, b) => b[1] - a[1])[0]?.[0] ?? '';
+  return ranked
+    .map(([email, s]) => {
+      const byName = [...(names.get(email)?.entries() ?? [])].sort((a, b) => b[1] - a[1]);
+      return { email, name: byName[0]?.[0] ?? fallbackName, score: s, why: why.get(email) ?? [] };
+    });
+}
+
+export function writeAuthor(dir: string, author: Author): boolean {
+  return (
+    git(dir, ['config', '--local', 'user.name', author.name]) !== null &&
+    git(dir, ['config', '--local', 'user.email', author.email]) !== null
+  );
+}

package/src/doctor.ts

@@ -3,6 +3,8 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
+import { effectiveAuthor, isGitRepo, rankAuthors, scanPool } from './author.ts';
+import { authorPoolDirs, loadEnvironment, resolveEnvironmentPath, shellQuote, type Environment } from './ai.ts';
 
 export type CheckStatus = 'ok' | 'warning' | 'missing';
 
@@ -503,6 +505,40 @@ function checkGitHooks(ctx: DoctorCtx): CheckResult | null {
   };
 }
 
+/**
+ * The project's commit author. With `user.useConfigOnly` git refuses to commit
+ * in a repo that has none; the remedy names the likely one, as `vdx ai` does.
+ */
+export function checkGitAuthor(ctx: DoctorCtx): CheckResult | null {
+  const root = ctx.projectRoot;
+  if (root === null || !isGitRepo(root)) return null;
+  const id = 'git-author';
+  const label = 'git author';
+  const current = effectiveAuthor(root);
+  if (current) return { id, label, status: 'ok', message: `${current.email} (${current.scope})` };
+
+  let environment: Environment = {};
+  const profilePath = resolveEnvironmentPath();
+  try {
+    if (profilePath) environment = loadEnvironment(profilePath);
+  } catch {
+    /* a broken profile is vdx ai's report; the parent directory still gives neighbours */
+  }
+  const home = os.homedir();
+  const dirs = authorPoolDirs(environment, root, home, profilePath ? path.dirname(profilePath) : home);
+  const top = rankAuthors(root, scanPool(dirs))[0];
+  const q = shellQuote(root);
+  return {
+    id,
+    label,
+    status: 'warning',
+    message: `no author of its own — git refuses to commit here${top ? `; likely ${top.email}` : ''}`,
+    remedy: top
+      ? `git -C ${q} config --local user.name ${shellQuote(top.name)} && git -C ${q} config --local user.email ${shellQuote(top.email)}`
+      : `git -C ${q} config --local user.email <address>`,
+  };
+}
+
 const CHECKS: Array<(ctx: DoctorCtx) => CheckResult | null> = [
   checkVdxVersion,
   checkVdx,
@@ -514,6 +550,7 @@ const CHECKS: Array<(ctx: DoctorCtx) => CheckResult | null> = [
   checkNpmAuth,
   checkContainerRuntime,
   checkGitHooks,
+  checkGitAuthor,
 ];
 
 export function resolveDoctorCtx(cwd: string = process.cwd()): DoctorCtx {

package/src/init.ts

@@ -12,7 +12,7 @@ import {
 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.5.0';
+export const DEFAULT_BASELINE = 'github.com/VoDmAl/vdx-rubric-vodmal@v0.6.0';
 
 const VERB_ALIASES: Record<Verb, string[]> = {
   up: ['docker:up', 'docker-up', 'docker:up:detached', 'start', 'dev', 'serve'],