@vodmal/vdx-cli 0.13.0 → 0.14.0

package/README.md

@@ -48,7 +48,10 @@ vdx publish <patch|minor|major> [--dry-run] [--force]
 vdx doctor [--format=ansi|markdown|json]
 
 # Start your agent in a project per your profile (~/.vdx-environment.yaml or $VDX_ENVIRONMENT)
-vdx ai [project-path] [--new] [--restart] [--detach] [--dry-run]   # default: cwd
+vdx ai[@host] [project-path] [--new] [--restart] [--detach] [--dry-run]   # default: cwd; @host: over ssh, in tmux there
+
+# Print the installed version
+vdx --version
 
 # MCP stdio server consumed by the Claude Code plugin
 vdx-mcp   --project <path>
@@ -70,11 +73,19 @@ vdx publish minor   # bump → npm publish (OTP prompt) → git commit + tag (no
 # 4. Start the agent here, continuing its last conversation (--new: a new one);
 #    re-run to attach, --restart to apply a changed profile
 vdx ai
+
+# 5. The same on another machine (an ssh host with vdx), attaching from here
+vdx ai@m3
 ```
 
 `vdx ai` reads a personal profile, never a bundled one: `$VDX_ENVIRONMENT`, else
 `~/.vdx-environment.yaml`, else a plain `claude`/`codex` with no flags. Format:
 [docs/specs/environment-format.md](../docs/specs/environment-format.md).
+The session's `{project}` is `[vdx] name` from the project's `mise.toml`, else the
+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.
 
 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.13.0",
+  "version": "0.14.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.4.0"
+  version: "0.5.0"
   description: "Personal maturity rubric for multi-stack projects (vodmal)"
   owner: vodmal
   homepage: "https://github.com/vodmal/vdx-rubric"

package/src/ai.ts

@@ -4,7 +4,8 @@ import * as path from 'node:path';
 import { execFileSync, spawnSync } from 'node:child_process';
 import YAML from 'js-yaml';
 import { evalPredicate } from './evaluator.ts';
-import { autoDetectStack, type Ctx } from './facts.ts';
+import { autoDetectStack, readStructured, resolveConfigPath, type Ctx } from './facts.ts';
+import { loadManifest } from './manifest.ts';
 import type { Predicate } from './rubric.ts';
 
 /**
@@ -46,9 +47,18 @@ export interface AgentProfile {
 
 export type Multiplexer = 'tmux' | 'none';
 
+/** A place a project's short name may come from: a structured file and a dot path into it. */
+export interface NameSource {
+  /** `{repo}` is the repository name; `~` the home directory; relative to the profile's directory. */
+  file: string;
+  jsonpath: string;
+}
+
 export interface SessionProfile {
   multiplexer?: Multiplexer;
   name?: string;
+  /** Tried after `[vdx] name` in the project's mise.toml; the first non-empty string wins. */
+  project_names?: NameSource[];
 }
 
 export interface Environment {
@@ -137,6 +147,19 @@ export function parseEnvironment(text: string, source: string): Environment {
     if (session.name !== undefined && typeof session.name !== 'string') {
       fail('session.name', 'must be a string');
     }
+    if (session.project_names !== undefined) {
+      if (!Array.isArray(session.project_names)) fail('session.project_names', 'must be a list');
+      session.project_names.forEach((src, i) => {
+        const at = `session.project_names[${i}]`;
+        if (typeof src !== 'object' || src === null) fail(at, 'must be a mapping');
+        if (typeof src.file !== 'string' || src.file === '') fail(`${at}.file`, 'must be a non-empty string');
+        const unknown = src.file.match(/\{(?!repo\})\w+\}/);
+        if (unknown) fail(`${at}.file`, `has an unknown placeholder ${unknown[0]} (only {repo})`);
+        if (typeof src.jsonpath !== 'string' || src.jsonpath === '') {
+          fail(`${at}.jsonpath`, 'must be a non-empty string (a dot path, e.g. names.0)');
+        }
+      });
+    }
   }
   return envDoc;
 }
@@ -172,6 +195,8 @@ export function renderSessionName(template: string, vars: Record<string, string>
 export interface LaunchPlan {
   projectRoot: string;
   project: string;
+  /** Where `project` came from: mise.toml, a profile source, or the repository name. */
+  projectSource: string;
   host: string;
   profilePath: string | null;
   command: string;
@@ -190,6 +215,7 @@ export function planLaunch(input: {
   agent: AgentProfile;
   projectRoot: string;
   project: string;
+  projectSource?: string;
   host: string;
 }): LaunchPlan {
   const { environment, agent, projectRoot } = input;
@@ -206,6 +232,7 @@ export function planLaunch(input: {
   return {
     projectRoot,
     project: input.project,
+    projectSource: input.projectSource ?? 'repository name',
     host: input.host,
     profilePath: input.profilePath,
     command: agent.command,
@@ -384,6 +411,40 @@ export function projectIdentity(projectRoot: string): string {
   return path.basename(projectRoot);
 }
 
+export interface ProjectName {
+  name: string;
+  source: string;
+}
+
+/**
+ * `{project}`: `[vdx] name` in the project's mise.toml, else the first profile
+ * source holding a non-empty string, else the repository name. A source that is
+ * missing or unreadable is skipped — a name is a label, not a reason to fail.
+ */
+export function resolveProjectName(input: {
+  projectRoot: string;
+  repo: string;
+  sources: NameSource[];
+  home: string;
+  profileDir: string;
+}): ProjectName {
+  const own = loadManifest(input.projectRoot)?.name;
+  if (typeof own === 'string' && own.trim()) return { name: own.trim(), source: 'mise.toml [vdx] name' };
+  for (const src of input.sources) {
+    const file = path.resolve(
+      input.profileDir,
+      src.file.replace(/^~(?=$|\/)/, input.home).replace(/\{repo\}/g, input.repo),
+    );
+    // Readers take paths relative to a project root; from "/" an absolute path stays itself.
+    const value = resolveConfigPath(readStructured({ projectRoot: '/', stack: '', cache: new Map() }, file), src.jsonpath);
+    if (typeof value === 'string' && value.trim()) {
+      const shown = file.startsWith(input.home + path.sep) ? `~${file.slice(input.home.length)}` : file;
+      return { name: value.trim(), source: `${shown} ${src.jsonpath}` };
+    }
+  }
+  return { name: input.repo, source: 'repository name' };
+}
+
 /** `{host}`: `$VDX_HOST` when set (a machine label such as `lft`), else the short hostname. */
 export function hostLabel(env: NodeJS.ProcessEnv = process.env): string {
   const label = env[HOST_ENV_VAR]?.trim();
@@ -559,6 +620,7 @@ export const NOTHING_TO_RESUME_MS = 30_000;
 export function renderPlan(plan: LaunchPlan, multiplexer: Multiplexer, running: AgentPane[]): string {
   const lines = [
     `vdx ai — ${plan.projectRoot}`,
+    `  name:     ${plan.project} (${plan.projectSource})`,
     `  profile:  ${plan.profilePath ?? `none — built-in default (${FALLBACK_AGENTS.join(' or ')}, no flags, no tmux)`}`,
     `  agent:    ${commandLine(plan.command, plan.args)}`,
     `  resume:   ${plan.resumeArgs.length ? plan.resumeArgs.join(' ') : '—'}`,
@@ -693,6 +755,61 @@ function finish(ok: boolean, session: string, paneId: string, opts: AiOptions, d
   return ok ? EXIT_OK : EXIT_LAUNCH_FAILED;
 }
 
+/** `vdx ai@<host>`: an ssh destination such as `m3` — never an option to ssh. */
+export const REMOTE_HOST_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** A path under the local home as a shell word under the remote home; any other path as is. */
+export function remotePathWord(abs: string, home: string): string {
+  const rel = path.relative(home, abs);
+  if (rel === '') return '"$HOME"';
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return shellQuote(abs);
+  return `"$HOME"/${shellQuote(rel)}`;
+}
+
+/**
+ * The ssh argv for `vdx ai@<host>`: the same `vdx ai` on the host, in its own
+ * tmux there. The path goes first: an older vdx hands the token after a flag it
+ * does not know to that flag. A different vdx version there is named, not fatal.
+ */
+export function remoteAiArgs(input: {
+  host: string;
+  projectPath: string;
+  home: string;
+  version: string;
+  opts: AiOptions;
+  tty: boolean;
+}): string[] {
+  const { host, opts, version } = input;
+  const flags = [
+    opts.fresh && '--new',
+    opts.restart && '--restart',
+    opts.detach && '--detach',
+    opts.dryRun && '--dry-run',
+  ].filter((f): f is string => Boolean(f));
+  const v = shellQuote(version);
+  const script =
+    `v=$(vdx --version 2>/dev/null) || v='older than 0.13.1'; ` +
+    `[ "$v" = ${v} ] || echo "note: vdx on ${host} is $v, here "${v} >&2; ` +
+    `exec vdx ai ${[remotePathWord(input.projectPath, input.home), ...flags].join(' ')}`;
+  return [input.tty ? '-t' : '-T', host, script];
+}
+
+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;
+  const args = remoteAiArgs({ host, projectPath, home: deps.home, version, opts, tty });
+  deps.log(`→ ${host}: vdx ai ${shellQuote(projectPath)}`);
+  const res = spawnSync('ssh', args, { stdio: 'inherit' });
+  if ((res.error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT') {
+    deps.log('vdx ai: `ssh` not found on PATH');
+    return 127;
+  }
+  if (opts.detach && res.status === EXIT_OK) {
+    deps.log(`attach from here: vdx ai@${host} ${shellQuote(projectPath)}`);
+  }
+  return res.status ?? 1;
+}
+
 export function runAi(opts: AiOptions, deps: AiDeps): number {
   const { log, tmux } = deps;
 
@@ -722,6 +839,14 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
     return EXIT_USAGE;
   }
 
+  const named = resolveProjectName({
+    projectRoot,
+    repo: projectIdentity(projectRoot),
+    sources: environment.session?.project_names ?? [],
+    home: deps.home,
+    profileDir: profilePath ? path.dirname(profilePath) : deps.home,
+  });
+
   let plan: LaunchPlan;
   try {
     plan = planLaunch({
@@ -729,7 +854,8 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
       profilePath,
       agent,
       projectRoot,
-      project: projectIdentity(projectRoot),
+      project: named.name,
+      projectSource: named.source,
       host: hostLabel(deps.env),
     });
   } catch (e: any) {

package/src/doctor.ts

@@ -162,7 +162,7 @@ function checkNpmAuth(): CheckResult {
       id: 'npm-auth',
       label: 'npm auth',
       status: 'warning',
-      message: 'not logged in — `vdx publish` will fail with E404',
+      message: 'not logged in — `vdx publish` refuses at pre-flight (npm-auth)',
       remedy: 'npm login',
     };
   }

package/src/index.ts

@@ -19,7 +19,7 @@ import {
   reportDoctorJson,
   reportDoctorAnsi,
 } from './report.ts';
-import { runDoctor, looksLikeProject } from './doctor.ts';
+import { runDoctor, looksLikeProject, readCliVersion } from './doctor.ts';
 import { planInit, writeInit, renderPlanSummary } from './init.ts';
 import {
   planPublish,
@@ -29,7 +29,7 @@ import {
   type PublishOptions,
 } from './publish.ts';
 import { resolveDefaultRubric } from './defaults.ts';
-import { runAi, defaultDeps } from './ai.ts';
+import { runAi, runAiRemote, defaultDeps, hostLabel, REMOTE_HOST_RE } from './ai.ts';
 
 const DEFAULT_RUBRIC = resolveDefaultRubric();
 
@@ -41,7 +41,8 @@ function usage(): never {
   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      [project_path]  [--new] [--restart] [--detach] [--dry-run]                                    (default: cwd)
+  vdx ai[@host] [project_path] [--new] [--restart] [--detach] [--dry-run]         (default: cwd; @host: over ssh, in tmux there)
+  vdx --version
 `,
   );
   process.exit(1);
@@ -277,17 +278,28 @@ function cmdAi(opts: ParsedArgs): void {
   bool('resume');
   const detach = bool('detach');
   const dryRun = bool('dry-run');
-  process.exit(
-    runAi({ path: positionals[0] ?? '.', restart, fresh, detach, dryRun }, defaultDeps()),
-  );
+  const options = { path: positionals[0] ?? '.', restart, fresh, detach, dryRun };
+  // `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) {
+    if (!REMOTE_HOST_RE.test(host)) {
+      process.stderr.write(`vdx ai@host: "${host}" is not a host name (an ssh destination such as m3)\n`);
+      process.exit(2);
+    }
+    if (host.toLowerCase() !== hostLabel().toLowerCase()) {
+      process.exit(runAiRemote(options, host, defaultDeps(), readCliVersion()));
+    }
+  }
+  process.exit(runAi(options, defaultDeps()));
 }
 
 const parsed = parseArgs(process.argv);
-if (parsed.cmd === 'audit') cmdAudit(parsed);
+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') cmdAi(parsed);
+else if (parsed.cmd === 'ai' || parsed.cmd.startsWith('ai@')) cmdAi(parsed);
 else if ((LIFECYCLE_VERBS as readonly string[]).includes(parsed.cmd))
   cmdRun(parsed.cmd as LifecycleVerb);
 else usage();

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

package/src/manifest.ts

@@ -5,6 +5,8 @@ import YAML from 'js-yaml';
 
 export interface VdxManifest {
   schema_version?: string;
+  /** Short name people use for the project (a session name, a sidebar); defaults to the repository name. */
+  name?: string;
   baseline?: string;
   stack?: string;
   primary_language?: string;

package/src/publish.ts

@@ -79,12 +79,21 @@ function isGitWorkingTreeClean(projectRoot: string): { ok: boolean; detail: stri
   }
 }
 
-function fetchPublishedVersion(packageName: string): string | null {
+/** Runs npm with these args and returns stdout; throws with `stderr` on a non-zero exit. */
+export type NpmRunner = (args: string[]) => string;
+
+// A caller's `npm run -s` passes `npm_config_loglevel=silent` down, and npm then
+// fails with an empty stderr — no E401 or E404 left to tell the cases apart.
+const runNpm: NpmRunner = (args) =>
+  execFileSync('npm', args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env, npm_config_loglevel: 'error' },
+  });
+
+function fetchPublishedVersion(packageName: string, npm: NpmRunner): string | null {
   try {
-    const out = execFileSync('npm', ['view', packageName, 'version'], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
+    const out = npm(['view', packageName, 'version']);
     return out.trim() || null;
   } catch (e: any) {
     const stderr = String(e?.stderr ?? e?.message ?? '');
@@ -93,6 +102,54 @@ function fetchPublishedVersion(packageName: string): string | null {
   }
 }
 
+/**
+ * The registry `npm publish` sends this package to, when it is not npm's
+ * default: `publishConfig.registry`, else the scope's registry from npm config.
+ */
+export function publishRegistry(
+  pkg: { name?: string; publishConfig?: { registry?: string } },
+  npm: NpmRunner,
+): string | null {
+  if (pkg.publishConfig?.registry) return pkg.publishConfig.registry;
+  const scope = pkg.name?.match(/^(@[^/]+)\//)?.[1];
+  if (!scope) return null;
+  try {
+    const value = npm(['config', 'get', `${scope}:registry`]).trim();
+    return value && value !== 'undefined' ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Logged in where the package goes? Without it `npm publish` fails only after
+ * the bump and the pack, and with E404 on a scoped package, not E401 — an
+ * expired npm session reads as a missing package.
+ */
+export function checkNpmAuth(registry: string | null, npm: NpmRunner): PreflightCheck {
+  const where = registry ?? 'npm';
+  const login = registry ? `npm login --registry ${registry}` : 'npm login';
+  try {
+    const who = npm(registry ? ['whoami', '--registry', registry] : ['whoami']).trim();
+    if (who) return { name: 'npm-auth', ok: true, message: `OK (logged in to ${where} as ${who})` };
+    return { name: 'npm-auth', ok: false, message: `npm whoami answered nothing for ${where}. Run: ${login}` };
+  } catch (e: any) {
+    const stderr = String(e?.stderr ?? e?.message ?? '');
+    if (/E401|ENEEDAUTH/.test(stderr)) {
+      return {
+        name: 'npm-auth',
+        ok: false,
+        message: `not logged in to ${where} (the npm session may have expired). Run: ${login}`,
+      };
+    }
+    return {
+      name: 'npm-auth',
+      ok: false,
+      message: `npm whoami failed for ${where}: ${stderr.split('\n').find((l) => l.trim()) ?? stderr}`,
+    };
+  }
+}
+
 function checkMiseOverride(projectRoot: string): boolean {
   const miseToml = path.join(projectRoot, 'mise.toml');
   if (!fs.existsSync(miseToml)) return false;
@@ -116,6 +173,7 @@ export function planPublish(
   opts: PublishOptions,
   audit: AuditResult,
   ctx: Ctx,
+  npm: NpmRunner = runNpm,
 ): PublishPlan {
   if (checkMiseOverride(opts.projectRoot)) {
     return {
@@ -197,10 +255,12 @@ export function planPublish(
         : `release-artifact at ${raLevel}, need >= L3. Add files[], main/exports, license in package.json.`,
   });
 
+  preflight.push(checkNpmAuth(publishRegistry(pkg, npm), npm));
+
   let published: string | null = null;
   let registryError: string | null = null;
   try {
-    published = fetchPublishedVersion(packageName);
+    published = fetchPublishedVersion(packageName, npm);
   } catch (e: any) {
     registryError = e?.message ?? String(e);
   }