@vodmal/vdx-cli 0.16.0 → 0.18.0

package/README.md

@@ -49,7 +49,10 @@ 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 --help                                                             # flags, where launch flags live, exit codes
+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
 
 # Print the installed version
 vdx --version
@@ -88,8 +91,11 @@ name. `vdx ai@<host>` runs the same command on `<host>` over ssh — that machin
 profile and tmux, the path taken under its home directory; `--detach` only
 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`).
-`vdx ai --help` (`-h`) prints the help; an unknown option or a second path is
-refused with exit 2, and nothing starts.
+
+Every command takes `--help` (`-h`) and runs nothing with it. An unknown option,
+a stray argument or a value flag without its value is refused with exit 2
+before anything runs. In 0.16.0 and earlier the commands other than `vdx ai`
+dropped such arguments, and `vdx init --help` wrote `mise.toml`.
 
 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.16.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,31 +29,40 @@ 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();
 
-function usage(): never {
-  process.stderr.write(
-    `Usage:
+const USAGE = `Usage:
   vdx <up|down|build|test|check|fix>     run lifecycle verb (via mise run <verb>)
   vdx audit   [project_path]  [--rubric <path>] [--stack <stack>] [--format=ansi|markdown|json] [--json]   (default: cwd)
   vdx init    [project_path]  [--stack <id>] [--baseline <ref>] [--dry-run] [--force]                     (default: cwd)
   vdx publish <patch|minor|major> [--dry-run] [--force]
   vdx doctor  [--format=ansi|markdown|json] [--json]
   vdx ai[@host] [project_path] [--new] [--restart] [--detach] [--dry-run]         (default: cwd; @host: over ssh, in tmux there)
-  vdx ai --help                                                                   (launch flags, profile, exit codes)
+  vdx <command> --help                   what the command does; an unknown option is refused (exit 2)
   vdx --version
-`,
-  );
+`;
+
+function usage(): never {
+  process.stderr.write(USAGE);
   process.exit(1);
 }
 
-const AI_USAGE_LINE = 'Usage: vdx ai[@host] [project_path] [--new] [--restart] [--detach] [--dry-run]';
-
-const AI_HELP = `${AI_USAGE_LINE}
+/** What a command reads from its arguments; the rest is refused. */
+interface CommandSpec {
+  usage: string;
+  /** Printed under the usage line by `--help`. */
+  help: string;
+  /** Flags that take no value. */
+  bools?: string[];
+  /** Flags that take one (`--stack node`, `--format=json`). */
+  values?: string[];
+  /** How many positional arguments the command takes. */
+  positionals: number;
+}
 
-Starts your agent in the project, or attaches to the one already running there.
+const AI_HELP = `Starts your agent in the project, or attaches to the one already running there.
 Which agent, its flags and whether it runs in tmux come from your profile:
 $VDX_ENVIRONMENT, else ~/.vdx-environment.yaml, else a plain claude/codex.
 
@@ -67,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;
@@ -75,12 +87,65 @@ was not confirmed.
 Profile format: https://github.com/VoDmAl/vdx/blob/main/docs/specs/environment-format.md
 `;
 
-const AI_FLAGS = ['new', 'restart', 'resume', 'detach', 'dry-run', 'help'];
-
-function aiUsageError(message: string): never {
-  process.stderr.write(`vdx ai: ${message}\n${AI_USAGE_LINE}\nMore: vdx ai --help\n`);
-  process.exit(2);
-}
+const COMMANDS: Record<string, CommandSpec> = {
+  audit: {
+    usage: 'vdx audit [project_path] [--rubric <path>] [--stack <stack>] [--format=ansi|markdown|json] [--json]',
+    help: `Scores the project (default: cwd) against the rubric and prints the report.
+Reads only. The rubric is the bundled one unless --rubric or $VDX_RUBRIC names another.
+`,
+    bools: ['json'],
+    values: ['rubric', 'stack', 'format'],
+    positionals: 1,
+  },
+  init: {
+    usage: 'vdx init [project_path] [--stack <id>] [--baseline <ref>] [--dry-run] [--force]',
+    help: `Writes mise.toml for the project (default: cwd): the lifecycle verbs mapped to
+the project's own scripts. --dry-run prints it and writes nothing; an existing
+mise.toml is overwritten only with --force.
+`,
+    bools: ['dry-run', 'force'],
+    values: ['stack', 'baseline'],
+    positionals: 1,
+  },
+  publish: {
+    usage: 'vdx publish <patch|minor|major> [--dry-run] [--force]',
+    help: `Releases the library in the current directory: pre-flight checks, version bump,
+npm publish (npm asks for an OTP), git commit and tag. Does not push.
+--dry-run runs the pre-flight and prints the plan; --force goes on past a failed pre-flight.
+`,
+    bools: ['dry-run', 'force'],
+    positionals: 1,
+  },
+  doctor: {
+    usage: 'vdx doctor [--format=ansi|markdown|json] [--json]',
+    help: `Checks this machine for what vdx needs (Node, git, mise, npm auth, docker, the
+Claude Code plugin) and, inside a project, its commit author. Reads only.
+Exit 2 when something is missing.
+`,
+    bools: ['json'],
+    values: ['format'],
+    positionals: 0,
+  },
+  ai: {
+    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', 'check'],
+    positionals: 1,
+  },
+  ...Object.fromEntries(
+    LIFECYCLE_VERBS.map((verb) => [
+      verb,
+      {
+        usage: `vdx ${verb}`,
+        help: `Runs \`mise run ${verb}\` in the current directory — the project's own ${verb}
+command, as mise.toml maps it. Takes no arguments.
+`,
+        positionals: 0,
+      },
+    ]),
+  ),
+};
 
 interface ParsedArgs {
   cmd: string;
@@ -116,6 +181,48 @@ function parseArgs(argv: string[]): ParsedArgs {
   return { cmd, positionals, flags };
 }
 
+/**
+ * Keeps what the command reads and refuses the rest, before anything runs: a
+ * misread argument must not run the command. `vdx ai --help` started an agent,
+ * `vdx init --help` wrote mise.toml, `vdx down --help` ran `mise run down`.
+ */
+function checkArgs(name: string, opts: ParsedArgs): ParsedArgs {
+  const spec = COMMANDS[name]!;
+  const bools = [...(spec.bools ?? []), 'help'];
+  const values = spec.values ?? [];
+  // parseArgs hands the token after a bare flag to that flag as its value; a
+  // flag that takes none gives it back — it is the path (or `-h`).
+  const positionals = [...opts.positionals];
+  const flags: Record<string, string | boolean> = {};
+  for (const [flag, value] of Object.entries(opts.flags)) {
+    if (bools.includes(flag) && typeof value === 'string') {
+      positionals.push(value);
+      flags[flag] = true;
+    } else {
+      flags[flag] = value;
+    }
+  }
+  if (flags.help || positionals.includes('-h')) {
+    process.stdout.write(`Usage: ${spec.usage}\n\n${spec.help}`);
+    process.exit(0);
+  }
+  const fail = (message: string): never => {
+    process.stderr.write(`vdx ${name}: ${message}\nUsage: ${spec.usage}\nMore: vdx ${name} --help\n`);
+    process.exit(2);
+  };
+  const unknown = [
+    ...Object.keys(flags).filter((f) => !bools.includes(f) && !values.includes(f)).map((f) => `--${f}`),
+    ...positionals.filter((p) => p.startsWith('-')),
+  ];
+  if (unknown.length > 0) fail(`unknown option ${unknown.join(', ')}`);
+  const bare = values.filter((f) => flags[f] === true).map((f) => `--${f}`);
+  if (bare.length > 0) fail(`${bare.join(', ')} needs a value`);
+  if (positionals.length > spec.positionals) {
+    fail(`unexpected argument ${positionals.slice(spec.positionals).join(' ')}`);
+  }
+  return { cmd: opts.cmd, positionals, flags };
+}
+
 function cmdAudit(opts: ParsedArgs): void {
   const projectArg = opts.positionals[0] ?? '.';
   const projectRoot = path.resolve(projectArg);
@@ -297,34 +404,24 @@ function cmdDoctor(opts: ParsedArgs): void {
 }
 
 function cmdAi(opts: ParsedArgs): void {
-  // parseArgs hands the token after a bare flag to that flag as its value;
-  // these flags take none, so such a token is the project path (or `-h`).
-  const positionals = [...opts.positionals];
-  const bool = (name: string): boolean => {
-    const v = opts.flags[name];
-    if (typeof v === 'string') positionals.push(v);
-    return v !== undefined;
-  };
-  const restart = bool('restart');
-  const fresh = bool('new');
-  // `--resume` asked to continue in 0.12; continuing is the default now.
-  // Still read, so the path after it is not taken for its value.
-  bool('resume');
-  const detach = bool('detach');
-  const dryRun = bool('dry-run');
-  // `vdx ai` starts an agent, so a misread argument must not run it: an agent
-  // that tried `vdx ai --help` got a launch in the current directory.
-  if (bool('help') || positionals.includes('-h')) {
-    process.stdout.write(AI_HELP);
-    process.exit(0);
+  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 unknown = [
-    ...Object.keys(opts.flags).filter((f) => !AI_FLAGS.includes(f)).map((f) => `--${f}`),
-    ...positionals.filter((p) => p.startsWith('-')),
-  ];
-  if (unknown.length > 0) aiUsageError(`unknown option ${unknown.join(', ')}`);
-  if (positionals.length > 1) aiUsageError(`unexpected argument ${positionals.slice(1).join(' ')}`);
-  const options = { path: positionals[0] ?? '.', restart, fresh, detach, dryRun };
+  const options = {
+    path: opts.positionals[0] ?? '.',
+    restart: opts.flags.restart === true,
+    fresh: opts.flags.new === true,
+    detach: opts.flags.detach === true,
+    dryRun: opts.flags['dry-run'] === true,
+  };
   // `ai@m3`: the same command on another machine. Its own label runs here.
   const host = opts.cmd.startsWith('ai@') ? opts.cmd.slice(3) : null;
   if (host !== null) {
@@ -341,11 +438,16 @@ function cmdAi(opts: ParsedArgs): void {
 
 const parsed = parseArgs(process.argv);
 if (parsed.cmd === '--version') process.stdout.write(readCliVersion() + '\n');
-else if (parsed.cmd === 'audit') cmdAudit(parsed);
-else if (parsed.cmd === 'init') cmdInit(parsed);
-else if (parsed.cmd === 'publish') cmdPublish(parsed);
-else if (parsed.cmd === 'doctor') cmdDoctor(parsed);
-else if (parsed.cmd === 'ai' || parsed.cmd.startsWith('ai@')) cmdAi(parsed);
-else if ((LIFECYCLE_VERBS as readonly string[]).includes(parsed.cmd))
+else if (['--help', '-h', 'help'].includes(parsed.cmd)) process.stdout.write(USAGE);
+else if (parsed.cmd === 'audit') cmdAudit(checkArgs('audit', parsed));
+else if (parsed.cmd === 'init') cmdInit(checkArgs('init', parsed));
+else if (parsed.cmd === 'publish') cmdPublish(checkArgs('publish', parsed));
+else if (parsed.cmd === 'doctor') cmdDoctor(checkArgs('doctor', parsed));
+else if (parsed.cmd === 'ai' || parsed.cmd.startsWith('ai@')) cmdAi(checkArgs('ai', parsed));
+else if ((LIFECYCLE_VERBS as readonly string[]).includes(parsed.cmd)) {
+  checkArgs(parsed.cmd, parsed);
   cmdRun(parsed.cmd as LifecycleVerb);
-else usage();
+} else {
+  if (parsed.cmd !== '') process.stderr.write(`vdx: unknown command "${parsed.cmd}"\n`);
+  usage();
+}