@vodmal/vdx-cli 0.37.1 → 0.38.0

package/README.md

@@ -50,6 +50,8 @@ vdx push [project-path] [--dry-run]   # default: cwd
 
 # Environment self-check (Node / git / mise / npm auth / docker / Claude Code plugin; git hooks of the project; the GitHub token vdx asks with)
 vdx doctor [project-path] [--format=ansi|markdown|json]   # default: cwd
+vdx doctor --staged                 # pre-commit guard: Claude Code memory goes into a commit only where nobody but
+                                    # you reads every place it reaches (origin, mirrors; GitHub asked with gh's token)
 vdx doctor --check [project-path]   # one line per hook declared but not running here, and one when the memory is
                                     # not inside — the plugin's SessionStart hook tells the agent
 vdx doctor --fix [project-path]     # write the profile's personal hooks (git.hooks) into ~/.gitconfig, and put

package/package.json

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

@@ -29,7 +29,15 @@ import {
   parseMachineReport,
   runsInProject,
 } from './conversations.ts';
-import { describeMemory, fixProjectMemory, memoryNeedsFix, memoryState } from './memory.ts';
+import {
+  describeMemory,
+  fixProjectMemory,
+  memoryApplies,
+  memoryNeedsFix,
+  memoryState,
+  personalHosts,
+  type PersonalHost,
+} from './memory.ts';
 import { at, errorMessage, isStringList, str } from './narrow.ts';
 import { type Lag, sessionLag } from './session-versions.ts';
 
@@ -116,8 +124,11 @@ interface GitProfile {
   /** Directories whose repos are the neighbours an author is proposed from; default — the project's parent. */
   author_pool?: string[];
   hooks?: PersonalHook[];
-  /** Hosts whose repos are the owner's alone: Claude Code's memory goes under git there (claude-memory-in-project). */
-  personal_hosts?: string[];
+  /**
+   * Hosts whose repos are the owner's alone, and where their repos are mirrored: Claude Code's
+   * memory goes under git only where nobody else reads (claude-memory-in-project).
+   */
+  personal_hosts?: Array<string | { host: string; mirrors?: string[] }>;
 }
 
 export interface Environment {
@@ -255,8 +266,21 @@ export function parseEnvironment(text: string, source: string): Environment {
     if (gitDoc.author_pool !== undefined && !isStringList(gitDoc.author_pool)) {
       fail('git.author_pool', 'must be a list of directories');
     }
-    if (gitDoc.personal_hosts !== undefined && !isStringList(gitDoc.personal_hosts)) {
-      fail('git.personal_hosts', 'must be a list of host names');
+    if (gitDoc.personal_hosts !== undefined) {
+      if (!Array.isArray(gitDoc.personal_hosts)) fail('git.personal_hosts', 'must be a list');
+      gitDoc.personal_hosts.forEach((h, i) => {
+        const at = `git.personal_hosts[${i}]`;
+        if (typeof h === 'string') {
+          if (h.trim() === '') fail(at, 'must be a host name');
+          return;
+        }
+        if (typeof h !== 'object' || h === null || typeof h.host !== 'string' || h.host.trim() === '') {
+          fail(at, 'must be a host name, or a mapping with host');
+        }
+        if (h.mirrors !== undefined && (!isStringList(h.mirrors) || !h.mirrors.every((m) => m.includes('{repo}')))) {
+          fail(`${at}.mirrors`, 'must be a list of places like github.com/<owner>/{repo}');
+        }
+      });
     }
     if (gitDoc.hooks !== undefined) {
       if (!Array.isArray(gitDoc.hooks)) fail('git.hooks', 'must be a list');
@@ -1157,13 +1181,13 @@ export function ensureAuthor(projectRoot: string, poolDirs: string[], deps: AiDe
 export function ensureMemory(
   projectRoot: string,
   command: string,
-  personalHosts: string[],
+  hosts: PersonalHost[],
   deps: AiDeps,
   dryRun: boolean,
   agentRunning: boolean,
 ): void {
-  if (!isClaude(command)) return;
   const ctx = { env: deps.env, home: deps.home };
+  if (!isClaude(command) || !memoryApplies(projectRoot, ctx)) return;
   const state = memoryState(projectRoot, ctx);
   if (dryRun) {
     deps.out(`  memory:   ${describeMemory(state, ctx)}\n`);
@@ -1194,7 +1218,7 @@ export function ensureMemory(
       ask: deps.ask,
       log: deps.log,
       today: new Date().toLocaleDateString('sv-SE'),
-      personalHosts,
+      personalHosts: hosts,
     });
     for (const d of done) deps.log(`✓ ${d}`);
   } catch (e) {
@@ -1937,7 +1961,14 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
     for (const l of choice?.lines ?? []) deps.out(`  conversation: ${l}\n`);
     for (const l of folders) deps.out(`  ${l}\n`);
     ensureAuthor(projectRoot, poolDirs, deps, true);
-    ensureMemory(projectRoot, plan.command, environment.git?.personal_hosts ?? [], deps, true, agentsHere.length > 0);
+    ensureMemory(
+      projectRoot,
+      plan.command,
+      personalHosts(environment.git?.personal_hosts),
+      deps,
+      true,
+      agentsHere.length > 0,
+    );
     return EXIT_OK;
   }
   for (const l of choice?.lines ?? []) log(l);
@@ -1973,7 +2004,14 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
     plan = { ...plan, resumeArgs: resumeId(id) };
   }
   ensureAuthor(projectRoot, poolDirs, deps, false);
-  ensureMemory(projectRoot, plan.command, environment.git?.personal_hosts ?? [], deps, false, agentsHere.length > 0);
+  ensureMemory(
+    projectRoot,
+    plan.command,
+    personalHosts(environment.git?.personal_hosts),
+    deps,
+    false,
+    agentsHere.length > 0,
+  );
 
   if (multiplexer === 'none') {
     if (opts.restart) {

package/src/doctor.ts

@@ -17,7 +17,10 @@ import { githubToken, machineIo, type HostingIo } from './hosting.ts';
 import {
   describeMemory,
   fixProjectMemory,
+  memoryApplies,
   memoryNeedsFix,
+  memoryReaders,
+  personalHosts,
   memoryState,
   type MemoryCtx,
   type MemoryState,
@@ -522,6 +525,7 @@ export function checkClaudeMemory(
   if (ctx.projectRoot === null || !claudeIsTheAgent(environment)) return null;
   // Claude Code's slot is the folder the agent starts in — the checkout's top for vdx ai.
   const root = resolveProjectRoot(ctx.projectRoot) ?? ctx.projectRoot;
+  if (!memoryApplies(root, mctx)) return null;
   const state = memoryState(root, mctx);
   return {
     id: 'claude-memory',
@@ -553,7 +557,19 @@ const CHECKS: Array<(ctx: DoctorCtx) => CheckResult | null> = [
   (ctx) => checkClaudeMemory(ctx),
 ];
 
-export function resolveDoctorCtx(cwd: string = process.cwd()): DoctorCtx {
+/**
+ * The project doctor looks at: a directory named on the command line is one, whatever it
+ * holds — a folder of notes or of other repos has Claude Code memory too (avatar,
+ * l10inc, 2026-10-23); the working directory only with a project's marker file.
+ */
+export function resolveDoctorCtx(cwd: string = process.cwd(), named = false): DoctorCtx {
+  if (named) {
+    try {
+      if (fs.statSync(cwd).isDirectory()) return { projectRoot: cwd };
+    } catch {
+      /* no such directory: no project */
+    }
+  }
   return { projectRoot: looksLikeProject(cwd) ? cwd : null };
 }
 
@@ -609,10 +625,33 @@ export function fixDoctorMemory(
 ): string[] {
   return fixProjectMemory(projectRoot, state, memoryCtx(), {
     ...io,
-    personalHosts: profile().git?.personal_hosts ?? [],
+    personalHosts: personalHosts(profile().git?.personal_hosts),
   });
 }
 
+/**
+ * `vdx doctor --staged`, the profile's pre-commit hook: Claude Code's memory goes into a
+ * commit only where nobody but the owner reads every place the commit reaches
+ * (claude-memory-in-project DL #11, #12). Nothing staged under `.claude/memory/` — no word.
+ * Returns the refusal, or null to let the commit go.
+ */
+export function runDoctorStaged(
+  projectRoot: string,
+  io: HostingIo = machineIo(projectRoot),
+  environment: Environment = profile(),
+): string | null {
+  const staged = io.git(['diff', '--cached', '--name-only', '--', '.claude/memory']);
+  if (!staged) return null;
+  const readers = memoryReaders(io, personalHosts(environment.git?.personal_hosts));
+  if (readers.only) return null;
+  const n = staged.split('\n').length;
+  return (
+    `vdx doctor: Claude memory stays out of this commit (${n} file(s)) — ${readers.why}.\n` +
+    `  commit the rest: git restore --staged .claude/memory, and commit again\n` +
+    `  keep it out of git here: echo /.claude/memory/ >> "$(git rev-parse --git-path info/exclude)"`
+  );
+}
+
 const PROJECT_MARKER_FILES = [
   'package.json',
   'composer.json',

package/src/index.ts

@@ -19,6 +19,7 @@ import {
 import {
   checkClaudeMemory,
   fixDoctorMemory,
+  runDoctorStaged,
   runDoctor,
   runDoctorCheck,
   runDoctorFix,
@@ -234,9 +235,10 @@ or GitHub stopped answering; a plain git push exits with git's own code.
     positionals: 1,
   },
   doctor: {
-    usage: 'vdx doctor [project_path] [--check | --fix] [--format=ansi|markdown|json] [--json]',
+    usage: 'vdx doctor [project_path] [--check | --fix | --staged] [--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 (default: cwd), its commit author and
+Claude Code plugin) and, inside a project (default: cwd, when it looks like one; a
+folder named here is one, git or not — the home directory never), its commit author and
 its git hooks: are the hooks the repository declares on in this clone, and do
 the personal hooks of your profile (git.hooks) run on this machine; with origin on
 GitHub, the token vdx asks GitHub with ($GH_TOKEN, $GITHUB_TOKEN or gh) and
@@ -252,13 +254,18 @@ takes it along. Reads only, unless --fix. Exit 2 when something is missing.
            install step, which the report names); and put the memory inside:
            notes from ~/.claude/projects/<path>/memory into .claude/memory/, none
            overwritten, the old place renamed, autoMemoryDirectory written —
-           into .claude/settings.json in a personal project (no origin, or origin
-           on a host of git.personal_hosts), else into .claude/settings.local.json,
+           into .claude/settings.json in a personal project (only you read where
+           its commits go — see --staged), else into .claude/settings.local.json,
            with the memory kept out of git (.git/info/exclude) unless you say
            yes. After a folder is moved: the path follows it, and the project's
            conversations move to the new path
+  --staged the profile's pre-commit hook: refuses a commit that stages
+           .claude/memory/ unless only you read every place the commit reaches —
+           origin on a host of git.personal_hosts or a private GitHub repo with
+           nobody else, and each mirror the profile names (GitHub asked with gh's
+           token); no answer, no token — refused. Silent otherwise
 `,
-    bools: ['json', 'check', 'fix'],
+    bools: ['json', 'check', 'fix', 'staged'],
     values: ['format'],
     positionals: 1,
   },
@@ -606,11 +613,20 @@ function cmdRun(verb: LifecycleVerb): void {
 }
 
 function cmdDoctor(opts: ParsedArgs): void {
-  const ctx = resolveDoctorCtx(path.resolve(opts.positionals[0] ?? '.'));
-  if (opts.flags.check === true && opts.flags.fix === true) {
-    process.stderr.write('vdx doctor: --check reports and --fix writes — pick one\n');
+  const ctx = resolveDoctorCtx(path.resolve(opts.positionals[0] ?? '.'), opts.positionals[0] !== undefined);
+  if ([opts.flags.check, opts.flags.fix, opts.flags.staged].filter((f) => f === true).length > 1) {
+    process.stderr.write('vdx doctor: --check reports, --fix writes, --staged guards a commit — pick one\n');
     process.exit(2);
   }
+  if (opts.flags.staged === true) {
+    const root = resolveProjectRoot(ctx.projectRoot ?? '.') ?? process.cwd();
+    const refusal = runDoctorStaged(root);
+    if (refusal) {
+      process.stderr.write(refusal + '\n');
+      process.exit(1);
+    }
+    return;
+  }
   if (opts.flags.check === true) {
     const text = runDoctorCheck(ctx);
     if (text) process.stdout.write(text + '\n');

package/src/memory.ts

@@ -3,7 +3,8 @@ import * as path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { remoteParts } from './author.ts';
 import { claudeConfigDir, projectDirName } from './conversations.ts';
-import { dict, str } from './narrow.ts';
+import { githubToken, machineIo, type HostingIo } from './hosting.ts';
+import { at, dict, errorMessage, list, str } from './narrow.ts';
 
 /**
  * Where Claude Code keeps a project's memory (docs/tasks/claude-memory-in-project).
@@ -53,6 +54,19 @@ function realRoot(root: string): string {
   }
 }
 
+/**
+ * A folder whose memory vdx may move: not the home directory or above it — its
+ * `.claude/settings.json` is the user's own, read by every project — and not inside
+ * Claude Code's configuration.
+ */
+export function memoryApplies(projectRoot: string, ctx: MemoryCtx): boolean {
+  const root = realRoot(projectRoot);
+  const home = realRoot(ctx.home);
+  const config = realRoot(claudeConfigDir(ctx.env, ctx.home));
+  const within = (a: string, b: string) => a === b || a.startsWith(b + path.sep);
+  return !within(home, root) && !within(root, config);
+}
+
 /** Where the setting is read, in Claude Code's order: local settings, the project's, the user's. */
 function settingFiles(root: string, ctx: MemoryCtx): string[] {
   return [
@@ -145,16 +159,83 @@ function git(root: string, args: string[]): string | null {
   }
 }
 
+/** A host of `git.personal_hosts`: its repos are the owner's alone; `mirrors` — where its repos may be copied. */
+export interface PersonalHost {
+  host: string;
+  /** `github.com/<owner>/{repo}`: a repo of the host may be mirrored there (gitolite's post-update hook). */
+  mirrors: string[];
+}
+
+/** The profile's `git.personal_hosts`: a host name, or `{host, mirrors}`. */
+export function personalHosts(
+  listed: Array<string | { host: string; mirrors?: string[] }> | undefined,
+): PersonalHost[] {
+  return (listed ?? []).map((h) =>
+    typeof h === 'string'
+      ? { host: h.toLowerCase(), mirrors: [] }
+      : { host: h.host.toLowerCase(), mirrors: h.mirrors ?? [] },
+  );
+}
+
+/** Who may read where the repo's commits go: only its owner, or — why not. */
+export type Readers = { only: true } | { only: false; why: string };
+
 /**
- * A personal project's memory goes under git with it; anyone else's would reach
- * whoever clones it (DL #3, #4). Personal: no origin, or origin on a host the
- * profile names in `git.personal_hosts`.
+ * Whether only the owner reads every place a commit of this repo reaches (DL #12 of
+ * docs/tasks/claude-memory-in-project): origin on a host the profile names as the
+ * owner's (`git.personal_hosts`), or a private GitHub repo with no other collaborator;
+ * and every mirror the profile names for that host — absent, or private and nobody
+ * else's. No origin: nothing leaves the machine. GitHub is asked with the token gh
+ * keeps; no token, no answer, `VDX_OFFLINE` — not known, so not only.
  */
-export function isPersonalProject(projectRoot: string, personalHosts: string[]): boolean {
-  const url = git(projectRoot, ['remote', 'get-url', 'origin']);
-  if (!url) return true;
-  const host = remoteParts(url).host.toLowerCase();
-  return personalHosts.some((h) => h.toLowerCase() === host);
+export function memoryReaders(io: HostingIo, hosts: PersonalHost[]): Readers {
+  const url = io.git(['remote', 'get-url', 'origin']);
+  if (!url) return { only: true };
+  const { host, path: repo } = remoteParts(url);
+  const lower = host.toLowerCase();
+  const own = hosts.find((h) => h.host === lower);
+  const places: string[] = [];
+  if (lower === 'github.com') places.push(repo);
+  else if (!own)
+    return { only: false, why: `origin is on ${host} — not a host the profile names as yours (git.personal_hosts)` };
+  for (const m of own?.mirrors ?? []) {
+    const at = m.replace(/^https?:\/\//, '').replace('{repo}', repo);
+    if (!at.startsWith('github.com/'))
+      return { only: false, why: `the mirror ${m} is not on GitHub — vdx cannot tell who reads it` };
+    places.push(at.slice('github.com/'.length));
+  }
+  if (places.length === 0) return { only: true };
+  if (io.env.VDX_OFFLINE) return { only: false, why: 'VDX_OFFLINE is set — GitHub was not asked who reads' };
+  const token = githubToken(io)?.token ?? null;
+  if (!token) return { only: false, why: 'no GitHub token to ask who reads — gh auth login' };
+  try {
+    const me = str(at(io.get('/user', token).body, 'login'));
+    if (!me) return { only: false, why: 'GitHub named no user for the token' };
+    for (const p of places) {
+      const r = io.get(`/repos/${p}`, token);
+      if (r.status === 404 && p !== repo) continue; // that mirror does not exist
+      if (r.status !== 200) return { only: false, why: `GitHub answered ${r.status} for ${p}` };
+      if (at(r.body, 'private') !== true) return { only: false, why: `github.com/${p} is public` };
+      const c = io.get(`/repos/${p}/collaborators?per_page=100`, token);
+      if (c.status !== 200) return { only: false, why: `GitHub does not show who reads github.com/${p} (${c.status})` };
+      const others = list(c.body)
+        .map((x) => str(at(x, 'login')))
+        .filter((l) => l && l !== me);
+      if (others.length) return { only: false, why: `github.com/${p} is read by ${others.length} more besides ${me}` };
+    }
+    return { only: true };
+  } catch (e) {
+    return { only: false, why: `GitHub did not answer: ${errorMessage(e)}` };
+  }
+}
+
+/** A personal project: its memory may go under git (DL #3, #4, #12). */
+export function isPersonalProject(
+  projectRoot: string,
+  hosts: PersonalHost[],
+  io: HostingIo = machineIo(projectRoot),
+): boolean {
+  return memoryReaders(io, hosts).only;
 }
 
 /** Needs `vdx doctor --fix`: anything but inside, or a path of the owner's own. */
@@ -283,6 +364,8 @@ function moveConversations(from: string, to: string, today: string): string {
  * already has stays, the old place is renamed. Returns what was done, one line each.
  */
 export function fixMemory(projectRoot: string, state: MemoryState, ctx: MemoryCtx, opts: MemoryFixOptions): string[] {
+  if (!memoryApplies(projectRoot, ctx))
+    throw new Error(`${projectRoot} is no project folder — its settings are the user's own`);
   const root = realRoot(projectRoot);
   const target = path.join(root, MEMORY);
   const done: string[] = [];
@@ -310,7 +393,13 @@ export function fixMemory(projectRoot: string, state: MemoryState, ctx: MemoryCt
       if (!opts.personal && !opts.underGit && excludeMemory(root)) done.push('.claude/memory/ → .git/info/exclude');
       setAside(state.old);
       if (opts.personal && git(root, ['rev-parse', '--git-dir']) !== null) {
-        done.push('commit .claude/memory/ and .claude/settings.json with the project');
+        // The project's own .gitignore may keep .claude/ out (mediko, 2026-10-23).
+        const ignored = git(root, ['check-ignore', '-q', '.claude/memory/MEMORY.md']) !== null;
+        done.push(
+          ignored
+            ? ".claude/memory/ stays out of git by the project's own .gitignore"
+            : 'commit .claude/memory/ and .claude/settings.json with the project',
+        );
       }
       return done;
     }
@@ -339,7 +428,9 @@ export interface ProjectMemoryDeps {
   log: (line: string) => void;
   today: string;
   /** The profile's `git.personal_hosts`. */
-  personalHosts: string[];
+  personalHosts: PersonalHost[];
+  /** Asks GitHub who reads the repo; the machine's own by default. */
+  io?: HostingIo;
 }
 
 /**
@@ -353,7 +444,7 @@ export function fixProjectMemory(
   ctx: MemoryCtx,
   deps: ProjectMemoryDeps,
 ): string[] {
-  const personal = isPersonalProject(projectRoot, deps.personalHosts);
+  const personal = isPersonalProject(projectRoot, deps.personalHosts, deps.io);
   let underGit = false;
   if (state.kind === 'outside' && !personal && git(projectRoot, ['rev-parse', '--git-dir']) !== null) {
     deps.log(`  ${path.basename(projectRoot)} is not a personal repo: memory under git reaches whoever clones it`);