@vodmal/vdx-cli 0.17.0 → 0.18.0

package/README.md

@@ -49,6 +49,7 @@ vdx doctor [--format=ansi|markdown|json]
 
 # Start your agent in a project per your profile (~/.vdx-environment.yaml or $VDX_ENVIRONMENT)
 vdx ai[@host] [project-path] [--new] [--restart] [--detach] [--dry-run]   # default: cwd; @host: over ssh, in tmux there
+vdx ai --check [project-path]   # this session against the profile — what the plugin's SessionStart hook tells the agent
 
 # What a command does and takes; nothing runs (ai: also where launch flags live)
 vdx <command> --help

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.17.0",
+  "version": "0.18.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/src/ai.ts

@@ -906,12 +906,21 @@ export function runAiRemote(opts: AiOptions, host: string, deps: AiDeps, version
   return res.status ?? 1;
 }
 
-export function runAi(opts: AiOptions, deps: AiDeps): number {
-  const { log, tmux } = deps;
+interface Prepared {
+  projectRoot: string;
+  environment: Environment;
+  profilePath: string | null;
+  profileDir: string;
+  plan: LaunchPlan;
+}
+
+/** The project, the profile and the launch plan for `pathArg`; an exit code when there is none. */
+function prepare(pathArg: string, deps: AiDeps): Prepared | number {
+  const { log } = deps;
 
-  const projectRoot = resolveProjectRoot(opts.path);
+  const projectRoot = resolveProjectRoot(pathArg);
   if (!projectRoot) {
-    log(`vdx ai: ${path.resolve(opts.path)} is not a directory`);
+    log(`vdx ai: ${path.resolve(pathArg)} is not a directory`);
     return EXIT_USAGE;
   }
 
@@ -959,6 +968,70 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
     log(`vdx ai: ${profilePath ?? 'profile'}: ${e?.message ?? e}`);
     return EXIT_USAGE;
   }
+  return { projectRoot, environment, profilePath, profileDir, plan };
+}
+
+/** The nearest ancestor of `pid` that is the agent: the session a hook or a shell tool runs in. */
+export function findOwnAgent(procs: ProcInfo[], pid: number, command: string): ProcInfo | null {
+  const byPid = new Map(procs.map((p) => [p.pid, p]));
+  let cur = byPid.get(pid);
+  for (let hops = 0; cur && cur.ppid > 1 && hops < 64; hops++) {
+    cur = byPid.get(cur.ppid);
+    if (cur && isAgentProcess(cur, command)) return cur;
+  }
+  return null;
+}
+
+/**
+ * `vdx ai --check`: what an agent should know about how it is launched here,
+ * and whether the session it runs in carries the profile's flags. Prints
+ * nothing without a profile — on such a machine `vdx ai` decides nothing.
+ */
+export function runAiCheck(pathArg: string, deps: AiDeps, selfPid: number = process.pid): number {
+  if (!resolveEnvironmentPath(deps.env, deps.home)) return EXIT_OK;
+  const prepared = prepare(pathArg, deps);
+  if (typeof prepared === 'number') return prepared;
+  const { projectRoot, profilePath, plan } = prepared;
+
+  const lines = [
+    `vdx ai: the agent in this project is started with \`vdx ai\`, and its flags come from the profile ` +
+      `${profilePath} — agent.args for every project, agent.when[] for a class of projects. ` +
+      `Hand the user \`vdx ai\`, not \`${plan.command} --<flag>\`; a flag a class of projects needs is a ` +
+      `condition in the profile, not an instruction to type. More: \`vdx ai --help\`.`,
+  ];
+  const own = findOwnAgent(deps.processes(), selfPid, plan.command);
+  if (!own) {
+    lines.push(`· no ${plan.command} among the ancestors of this process — no session to compare with the profile.`);
+    deps.out(lines.join('\n') + '\n');
+    return EXIT_OK;
+  }
+  const missing = missingArgs(own.args, plan.args);
+  const why = plan.matched.length ? ` (profile conditions met here: ${plan.matched.join(', ')})` : '';
+  if (missing.length === 0) {
+    lines.push(`✓ this session carries the profile's flags${why}.`);
+    deps.out(lines.join('\n') + '\n');
+    return EXIT_OK;
+  }
+  const root = shellQuote(projectRoot);
+  lines.push(
+    `✗ this session runs without ${missing.join(' ')}${why}. Hand the user the fix — ` +
+      (deps.env['TMUX']
+        ? `\`vdx ai --restart ${root}\`: it stops this session and starts it again with the profile's flags` +
+          (plan.resumeArgs.length ? `, resuming the conversation (${plan.resumeArgs.join(' ')})` : '') +
+          `. Do not run it yourself: it ends this session.`
+        : `this session runs outside tmux, so vdx cannot restart it: the user exits it and runs \`vdx ai ${root}\`.`),
+  );
+  deps.out(lines.join('\n') + '\n');
+  return EXIT_DRIFT;
+}
+
+export function runAi(opts: AiOptions, deps: AiDeps): number {
+  const { log, tmux } = deps;
+
+  const prepared = prepare(opts.path, deps);
+  if (typeof prepared === 'number') return prepared;
+  const { projectRoot, environment, profileDir } = prepared;
+  let { plan } = prepared;
   // A start continues the last conversation unless asked for a new one.
   if (opts.fresh) plan = { ...plan, resumeArgs: [] };
 

package/src/doctor.ts

@@ -339,42 +339,45 @@ function checkClaudeCode(): CheckResult {
   };
 }
 
-function checkClaudeCodePlugin(): CheckResult {
-  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
-  if (!fs.existsSync(settingsPath)) {
-    return {
-      id: 'claude-plugin',
-      label: 'Claude Code vdx plugin',
-      status: 'warning',
-      message: '~/.claude/settings.json not found',
-      remedy: 'Install Claude Code, then add vdx marketplace (see README)',
-    };
-  }
-  try {
-    const raw = fs.readFileSync(settingsPath, 'utf8');
-    if (raw.includes('VoDmAl/vdx') || raw.includes('vdx/marketplace')) {
-      return {
-        id: 'claude-plugin',
-        label: 'Claude Code vdx plugin',
-        status: 'ok',
-        message: 'vdx marketplace registered',
-      };
+const PLUGIN_INSTALL_HINT =
+  'in Claude Code: /plugin marketplace add VoDmAl/ai-dev-plugins, then /plugin install vdx from it';
+
+/**
+ * The vdx plugin as Claude Code records it: `vdx@<marketplace>` in
+ * plugins/installed_plugins.json, and not switched off in settings.json
+ * enabledPlugins. Whichever marketplace brought it — the plugin ships through
+ * the owner's marketplace (VoDmAl/ai-dev-plugins), not a vdx one of its own.
+ */
+export function checkClaudeCodePlugin(
+  claudeDir: string = process.env['CLAUDE_CONFIG_DIR'] || path.join(os.homedir(), '.claude'),
+): CheckResult {
+  const base = { id: 'claude-plugin', label: 'Claude Code vdx plugin' };
+  const readJson = (file: string): any => {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(claudeDir, file), 'utf8'));
+    } catch {
+      return null;
     }
+  };
+  const installed = readJson(path.join('plugins', 'installed_plugins.json'));
+  if (!installed) {
     return {
-      id: 'claude-plugin',
-      label: 'Claude Code vdx plugin',
-      status: 'warning',
-      message: 'vdx marketplace not registered',
-      remedy: 'Add github.com/VoDmAl/vdx/marketplace to extraKnownMarketplaces',
-    };
-  } catch (e: any) {
-    return {
-      id: 'claude-plugin',
-      label: 'Claude Code vdx plugin',
+      ...base,
       status: 'warning',
-      message: `cannot read settings.json: ${e?.message ?? e}`,
+      message: `no plugin records in ${claudeDir}/plugins/installed_plugins.json`,
+      remedy: PLUGIN_INSTALL_HINT,
     };
   }
+  const key = Object.keys(installed.plugins ?? {}).find((k) => k.startsWith('vdx@'));
+  if (!key) {
+    return { ...base, status: 'warning', message: 'not installed', remedy: PLUGIN_INSTALL_HINT };
+  }
+  const version = installed.plugins[key]?.[0]?.version;
+  const label = `${key}${typeof version === 'string' ? ` ${version}` : ''}`;
+  if (readJson('settings.json')?.enabledPlugins?.[key] === false) {
+    return { ...base, status: 'warning', message: `${label} installed but disabled`, remedy: `/plugin enable ${key}` };
+  }
+  return { ...base, status: 'ok', message: label };
 }
 
 /**
@@ -543,7 +546,7 @@ const CHECKS: Array<(ctx: DoctorCtx) => CheckResult | null> = [
   checkVdxVersion,
   checkVdx,
   checkClaudeCode,
-  checkClaudeCodePlugin,
+  () => checkClaudeCodePlugin(),
   checkNode,
   checkGit,
   checkMise,

package/src/index.ts

@@ -29,7 +29,7 @@ import {
   type PublishOptions,
 } from './publish.ts';
 import { resolveDefaultRubric } from './defaults.ts';
-import { runAi, runAiRemote, defaultDeps, hostLabel, REMOTE_HOST_RE } from './ai.ts';
+import { runAi, runAiCheck, runAiRemote, defaultDeps, hostLabel, REMOTE_HOST_RE } from './ai.ts';
 
 const DEFAULT_RUBRIC = resolveDefaultRubric();
 
@@ -76,6 +76,9 @@ the project's files). Hand a person \`vdx ai\`, not \`<agent> --<flag>\`.
   --restart     restart the running agent in its pane — applies a changed profile
   --detach      start without attaching; print the command that attaches
   --dry-run     print the plan and the project's running agents; start nothing
+  --check       for the agent's own session: how the agent here is launched, and
+                whether this session carries the profile's flags (the vdx plugin's
+                SessionStart hook); prints nothing without a profile; exit 3 on drift
   -h, --help    this help
 
 Exit codes: 0 the agent runs per the profile; 2 profile or usage error;
@@ -127,7 +130,7 @@ Exit 2 when something is missing.
     usage: 'vdx ai[@host] [project_path] [--new] [--restart] [--detach] [--dry-run]',
     help: AI_HELP,
     // `--resume` asked to continue in 0.12; continuing is the default now.
-    bools: ['new', 'restart', 'resume', 'detach', 'dry-run'],
+    bools: ['new', 'restart', 'resume', 'detach', 'dry-run', 'check'],
     positionals: 1,
   },
   ...Object.fromEntries(
@@ -401,6 +404,17 @@ function cmdDoctor(opts: ParsedArgs): void {
 }
 
 function cmdAi(opts: ParsedArgs): void {
+  if (opts.flags.check === true) {
+    // About the session this runs in — there is nothing to start, and no other machine.
+    const others = Object.keys(opts.flags).filter((f) => f !== 'check');
+    if (others.length > 0 || opts.cmd !== 'ai') {
+      process.stderr.write(
+        `vdx ai: --check takes only the project path (not ${opts.cmd !== 'ai' ? opts.cmd : `--${others.join(', --')}`})\n`,
+      );
+      process.exit(2);
+    }
+    process.exit(runAiCheck(opts.positionals[0] ?? '.', defaultDeps()));
+  }
   const options = {
     path: opts.positionals[0] ?? '.',
     restart: opts.flags.restart === true,