@vodmal/vdx-cli 0.23.0 → 0.24.0

package/README.md

@@ -75,11 +75,12 @@ vdx init --stack node
 vdx test            # → mise run test (which calls `vitest run` or whatever was detected)
 
 # 3. Ship a new minor release of a Node lib
-vdx publish minor   # npm login if expired → bump package.json + lock → npm publish (OTP) → commit + tag → push → wait for the registry
+vdx publish minor   # npm login if expired → bump package.json + lock → npm publish (OTP or browser) → commit + tag → push → wait for the registry
 
 # 4. Start the agent here, continuing its last conversation (--new: a new one;
 #    another machine's conversation is continued on that machine);
-#    re-run to attach, --restart to apply a changed profile
+#    re-run to attach; an agent without the profile's flags is a question:
+#    Enter attaches as is, r restarts it; --restart applies a changed profile
 vdx ai
 
 # 5. The same on another machine (an ssh host with vdx), attaching from here

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.23.0",
+  "version": "0.24.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.3"
 
 metadata:
   name: vdx-rubric-vodmal
-  version: "1.2.0"
+  version: "1.3.0"
   description: "Personal maturity rubric for multi-stack projects (vodmal)"
   owner: vodmal
   homepage: "https://github.com/vodmal/vdx-rubric"

package/src/ai.ts

@@ -84,6 +84,8 @@ export interface SessionProfile {
   project_names?: NameSource[];
   /** The machines a project's agent may run on, as ssh destinations; vdx asks the others what runs there. */
   machines?: string[];
+  /** What to do when a session cannot read ~/Downloads, ~/Desktop or ~/Documents (macOS): shown after the warning. */
+  folders_fix?: string;
 }
 
 /**
@@ -222,6 +224,9 @@ export function parseEnvironment(text: string, source: string): Environment {
         if (!isMachineLabel(m)) fail(`session.machines[${i}]`, 'must be an ssh destination: letters, digits, . _ - and no leading -');
       });
     }
+    if (session.folders_fix !== undefined && (typeof session.folders_fix !== 'string' || session.folders_fix.trim() === '')) {
+      fail('session.folders_fix', 'must be a non-empty string');
+    }
   }
 
   const gitDoc = envDoc.git;
@@ -708,6 +713,8 @@ export interface AiDeps {
   processes: () => ProcInfo[];
   /** Was this agent process started focused; default: its environment (`processFocused`). */
   agentFocused?: (pid: number) => boolean;
+  /** Default `process.platform`: the folder check is for macOS. */
+  platform?: NodeJS.Platform;
   sleep: (ms: number) => void;
   confirmTimeoutMs: number;
   /** One line from the person at the terminal, or null when there is none. */
@@ -1308,6 +1315,46 @@ export function processFocused(pid: number): boolean {
   }
 }
 
+/** macOS guards these folders on their own; a tmux server can hold a denial for every session under it. */
+export const GUARDED_FOLDERS = ['Downloads', 'Desktop', 'Documents'];
+
+/**
+ * The guarded folders an agent started here could not read. Through the tmux server
+ * (`run-shell`): its sessions have the server's rights, not vdx's. Without a server, or
+ * without tmux, this process's own — the agent gets the rights of this terminal. A folder
+ * that does not exist is skipped.
+ */
+export function unreadableFolders(tmux: Tmux | null, home: string): string[] {
+  const dirs = GUARDED_FOLDERS.map((f) => path.join(home, f));
+  // `ls`, not `[ -d ]`: a denied folder still passes -d.
+  const script = dirs.map((d) => `{ [ ! -d ${shellQuote(d)} ] || ls ${shellQuote(d)} >/dev/null 2>&1 || echo ${shellQuote(d)}; }`).join('; ');
+  const out = tmux?.tryRun(['run-shell', script]);
+  if (out !== undefined && out !== null) return out.split('\n').filter(Boolean);
+  return dirs.filter((d) => {
+    try {
+      fs.readdirSync(d);
+      return false;
+    } catch (e: any) {
+      return e?.code === 'EPERM' || e?.code === 'EACCES';
+    }
+  });
+}
+
+/** One warning and its fix — the profile's `session.folders_fix`, else what works anywhere. */
+export function foldersWarning(denied: string[], viaTmux: boolean, fix: string | undefined, home: string): string[] {
+  const names = denied.map((d) => (d.startsWith(home + path.sep) ? `~${d.slice(home.length)}` : d)).join(', ');
+  return [
+    `⚠ this session cannot read ${names} — macOS holds the denial ${viaTmux ? 'in the tmux server' : 'for this terminal'}; ` +
+      `files there are out of the agent's reach`,
+    `  fix: ${
+      fix ??
+      (viaTmux
+        ? 'restart the tmux server (it closes every session)'
+        : 'allow this terminal app in System Settings → Privacy & Security → Files and Folders')
+    }`,
+  ];
+}
+
 /** The agent's command line; a focused one carries VDX_FOCUSED=1 in front, for the shell in its tmux pane. */
 function agentLine(plan: LaunchPlan, args: string[]): string {
   return `${plan.focused ? `${FOCUSED_ENV_VAR}=1 ` : ''}${commandLine(plan.command, args)}`;
@@ -1436,13 +1483,18 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
   }
 
   const poolDirs = authorPoolDirs(environment, projectRoot, deps.home, profileDir);
+  // Said before a start or an attach, never in the way: the agent runs, without those files.
+  const denied = (deps.platform ?? process.platform) === 'darwin' ? unreadableFolders(multiplexer === 'tmux' ? tmux : null, deps.home) : [];
+  const folders = denied.length ? foldersWarning(denied, multiplexer === 'tmux', environment.session?.folders_fix, deps.home) : [];
   if (opts.dryRun) {
     deps.out(renderPlan(plan, multiplexer, running, focusedOf));
     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);
     return EXIT_OK;
   }
   for (const l of choice?.lines ?? []) log(l);
+  for (const l of folders) log(l);
   if (choice?.abort) return EXIT_LAUNCH_FAILED;
   if (choice?.elsewhere && !current) {
     const answer = deps.interactive ? deps.ask(`Start a new conversation ${here}${atSeat ? ',' : ''} anyway? [y/N]: `) : null;
@@ -1516,29 +1568,39 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
         );
       }
     }
-    if (plan.focused && !runningFocused) {
-      log(`✗ ${current.pane.session}: ${plan.command} is running, not focused`);
-      log(
-        `  to focus it: vdx ai --restart --focused ${shellQuote(projectRoot)}` +
-          (plan.resumeArgs.length ? ' (stops the running agent, then resumes its conversation)' : ' (stops the running agent)'),
-      );
+    const unfocused = plan.focused && !runningFocused;
+    const missing = unfocused ? [] : missingArgs(current.proc.args, plan.args);
+    if (!unfocused && missing.length === 0) {
+      log(`✓ ${current.pane.session}: already running with the profile${runningFocused ? ', focused' : ''} — ${current.proc.args}`);
+      return finish(true, current.pane.session, current.pane.paneId, opts, deps);
+    }
+    // Drift. In a terminal the person picks: the agent as it runs, or a restart
+    // with the profile; without one nothing is touched, and the fix is named.
+    const drift = `${current.pane.session}: ${plan.command} is running${unfocused ? ', not focused' : ` without ${missing.join(' ')}`}`;
+    const fix = `vdx ai --restart${plan.focused ? ' --focused' : ''}${opts.fresh ? ' --new' : ''} ${shellQuote(projectRoot)}`;
+    const effect = plan.resumeArgs.length
+      ? 'stops the running agent, then resumes its conversation'
+      : opts.fresh
+        ? 'stops the running agent and starts a new conversation'
+        : 'stops the running agent; the conversation is not resumed — the profile has no resume_args';
+    if (!deps.interactive) {
+      log(`✗ ${drift}`);
+      log(`  ${unfocused ? 'to focus it' : 'to apply the profile'}: ${fix} (${effect})`);
       return EXIT_DRIFT;
     }
-    const missing = missingArgs(current.proc.args, plan.args);
-    if (missing.length > 0) {
-      log(`✗ ${current.pane.session}: ${plan.command} is running without ${missing.join(' ')}`);
-      log(
-        `  to apply the profile: vdx ai --restart${plan.focused ? ' --focused' : ''}${opts.fresh ? ' --new' : ''} ${shellQuote(projectRoot)}` +
-          (plan.resumeArgs.length
-            ? ` (stops the running agent, then resumes its conversation)`
-            : opts.fresh
-              ? ' (stops the running agent and starts a new conversation)'
-              : ' (stops the running agent; the conversation is not resumed — the profile has no resume_args)'),
-      );
+    log(`⚠ ${drift}`);
+    log(`  Enter  ${opts.detach ? 'leave it running' : 'attach to it'} as is${unfocused ? '' : ' — the flags wait for a restart'}`);
+    log(`  r      restart it ${unfocused ? 'focused' : 'with the profile'}: ${effect}`);
+    log(`  q      leave it; later: ${fix}`);
+    const answer = deps.ask(`${opts.detach ? 'Leave it as is' : 'Attach as is'}? [Enter/r/q]: `);
+    if (answer === '') {
+      log(`→ ${current.pane.session}: as is — ${current.proc.args}`);
+      return finish(true, current.pane.session, current.pane.paneId, opts, deps);
+    }
+    if (answer?.toLowerCase() !== 'r') {
+      log('nothing done');
       return EXIT_DRIFT;
     }
-    log(`✓ ${current.pane.session}: already running with the profile${runningFocused ? ', focused' : ''} — ${current.proc.args}`);
-    return finish(true, current.pane.session, current.pane.paneId, opts, deps);
   }
 
   if (current) {

package/src/index.ts

@@ -83,7 +83,10 @@ the project's files). Hand a person \`vdx ai\`, not \`<agent> --<flag>\`.
                 applies this one
   --conversation <id>
                 continue this Claude Code conversation
-  --restart     restart the running agent in its pane — applies a changed profile
+  --restart     restart the running agent in its pane — applies a changed profile.
+                Without it, an agent running without the profile's flags is
+                a question in a terminal: Enter attaches to it as is, r
+                restarts it, q leaves it
   --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
@@ -102,8 +105,8 @@ machine's. A new conversation (--new, or none to continue) while an agent of
 the project runs on another machine starts only after a yes.
 
 Exit codes: 0 the agent runs per the profile; 2 profile or usage error;
-3 the running agent lacks profile flags, or is not focused under --focused
-(rerun with --restart); 4 the start
+3 the running agent lacks profile flags, or is not focused under --focused,
+and was left as is — no terminal, or q (rerun with --restart); 4 the start
 was not confirmed.
 Profile format: https://github.com/VoDmAl/vdx/blob/main/docs/specs/environment-format.md
 `;
@@ -134,7 +137,8 @@ mise.toml is overwritten only with --force.
   pre-flight checks — at a terminal an expired npm login is renewed (\`npm login\`)
   and the checks run again;
   the version bump in package.json and package-lock.json;
-  npm publish (npm asks for an OTP);
+  npm publish (npm asks for an OTP or a confirmation in the browser; Ctrl-C
+  there puts the version back);
   git commit and tag, then \`git push --follow-tags\` to the branch's upstream;
   a wait until the registry shows the new version (up to 3 min).
 --dry-run runs the pre-flight and prints the plan; --force goes on past a failed

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

package/src/publish.ts

@@ -481,7 +481,7 @@ export function waitForRegistry(name: string, version: string, deps: PublishDeps
  *      or there is none. The pre-flight refused a branch behind its upstream.
  *   5. Wait until the registry shows the version.
  *
- * On npm publish failure → restore the original files.
+ * On npm publish failure or interruption (Ctrl-C at its prompt) → restore the original files.
  * Git failures after a successful npm publish leave the user in a
  * partially-released state; they fix it manually (commit/tag/push what's
  * needed) — we don't try to unpublish.
@@ -511,14 +511,22 @@ export function executePublish(plan: PublishPlan, deps: PublishDeps = defaultPub
     `✓ bumped ${bumped.map((f) => path.relative(plan.projectRoot, f)).join(' and ')}: ${plan.currentVersion} → ${plan.newVersion}`,
   );
 
-  // 2. npm publish (interactive — OTP prompt may appear)
-  deps.log('→ running `npm publish` (OTP prompt may appear)...');
+  // 2. npm publish (interactive — npm asks for an OTP or a confirmation in the browser).
+  // Ctrl-C at that prompt reaches npm and vdx alike: vdx holds out while npm runs, so the
+  // interrupted npm comes back as an error and the bump is put back — not left for the next run.
+  deps.log('→ running `npm publish` (npm may ask for an OTP or a confirmation in the browser)...');
+  const holdOut = () => {};
+  const signals: NodeJS.Signals[] = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+  for (const s of signals) process.on(s, holdOut);
   try {
     deps.run('npm', ['publish'], path.dirname(plan.packageJsonPath));
   } catch (e: any) {
     for (const [file, text] of originals) fs.writeFileSync(file, text, 'utf8');
-    deps.log(`✗ npm publish failed (exit ${e?.status ?? '?'}); reverted ${bumped.map((f) => path.basename(f)).join(' and ')}`);
-    throw new Error('npm publish failed');
+    const what = e?.signal ? `interrupted (${e.signal})` : `failed (exit ${e?.status ?? '?'})`;
+    deps.log(`✗ npm publish ${what}; reverted ${bumped.map((f) => path.basename(f)).join(' and ')}`);
+    throw new Error(`npm publish ${e?.signal ? 'interrupted' : 'failed'}`);
+  } finally {
+    for (const s of signals) process.off(s, holdOut);
   }
   deps.log(`✓ published ${plan.packageName}@${plan.newVersion}`);