@imdeadpool/guardex 7.0.41 → 7.1.0

package/src/terminal/tmux.js

@@ -0,0 +1,125 @@
+'use strict';
+
+const tmuxCommand = require('../tmux/command');
+const tmuxSession = require('../tmux/session');
+
+function text(value, fallback = '') {
+  if (typeof value === 'string') return value.trim() || fallback;
+  if (value === null || value === undefined) return fallback;
+  return String(value).trim() || fallback;
+}
+
+function requireText(value, name) {
+  const normalized = text(value);
+  if (!normalized) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+  return normalized;
+}
+
+function targetId(target) {
+  if (target && typeof target === 'object') {
+    return requireText(target.paneId || target.tmuxPaneId || target.tmuxTarget || target.id || target.target, 'tmux target');
+  }
+  return requireText(target, 'tmux target');
+}
+
+function assertStatus(result, message) {
+  if (result && result.error) throw result.error;
+  if (!result || result.status === 0) return result;
+  const detail = String(result.stderr || result.stdout || '').trim();
+  throw new Error(`${message}${detail ? `: ${detail}` : '.'}`);
+}
+
+function defaultTmuxApi() {
+  return {
+    ensureTmuxAvailable: tmuxSession.ensureTmuxAvailable,
+    sessionExists: tmuxSession.sessionExists,
+    createSession: tmuxSession.createSession,
+    attachSession: tmuxSession.attachSession,
+    newWindowOrPane: tmuxSession.newWindowOrPane,
+    sendKeys: tmuxSession.sendKeys,
+  };
+}
+
+function createBackend(options = {}) {
+  const tmux = options.tmux || defaultTmuxApi();
+  const runTmux = typeof options.runTmux === 'function' ? options.runTmux : tmuxCommand.runTmux;
+
+  return {
+    name: 'tmux',
+    isAvailable() {
+      try {
+        if (typeof tmux.isAvailable === 'function') return Boolean(tmux.isAvailable());
+        tmux.ensureTmuxAvailable();
+        return true;
+      } catch (_error) {
+        return false;
+      }
+    },
+    openCockpitLayout(config = {}) {
+      const sessionName = requireText(config.sessionName, 'tmux sessionName');
+      const repoRoot = requireText(config.repoRoot, 'tmux repoRoot');
+      const command = requireText(config.command, 'tmux cockpit command');
+
+      tmux.ensureTmuxAvailable();
+
+      if (tmux.sessionExists(sessionName)) {
+        assertStatus(tmux.attachSession(sessionName), `tmux could not attach session '${sessionName}'`);
+        return { action: 'attached', sessionName, repoRoot };
+      }
+
+      assertStatus(
+        tmux.createSession(sessionName, repoRoot),
+        `tmux could not create session '${sessionName}'`,
+      );
+      assertStatus(
+        tmux.sendKeys(sessionName, command),
+        'tmux could not start cockpit control pane',
+      );
+
+      if (config.attach) {
+        assertStatus(tmux.attachSession(sessionName), `tmux could not attach session '${sessionName}'`);
+        return { action: 'created-attached', sessionName, repoRoot };
+      }
+      return { action: 'created', sessionName, repoRoot };
+    },
+    launchAgentPane(config = {}) {
+      const session = config.session && typeof config.session === 'object' ? config.session : {};
+      const cwd = requireText(config.worktree || session.worktreePath || session.path, 'tmux agent worktree');
+      const result = tmux.newWindowOrPane({
+        pane: true,
+        split: 'horizontal',
+        target: config.target || session.tmuxTarget || session.tmuxSession || session.sessionName,
+        cwd,
+        name: config.title || session.title,
+      });
+      return assertStatus(result, 'tmux could not launch agent pane');
+    },
+    launchTerminalPane(config = {}) {
+      const result = tmux.newWindowOrPane({
+        pane: true,
+        split: 'horizontal',
+        target: config.target,
+        cwd: requireText(config.cwd, 'tmux terminal cwd'),
+        name: config.title,
+      });
+      return assertStatus(result, 'tmux could not launch terminal pane');
+    },
+    focusPane(target) {
+      return assertStatus(runTmux(['select-pane', '-t', targetId(target)]), 'tmux could not focus pane');
+    },
+    closePane(target) {
+      return assertStatus(runTmux(['kill-pane', '-t', targetId(target)]), 'tmux could not close pane');
+    },
+    sendText(target, value, options = {}) {
+      const args = ['send-keys', '-t', targetId(target), String(value === undefined || value === null ? '' : value)];
+      if (options.submit) args.push('C-m');
+      return assertStatus(runTmux(args), 'tmux could not send text');
+    },
+  };
+}
+
+module.exports = {
+  createBackend,
+};

package/src/tmux/command.js

@@ -0,0 +1,27 @@
+const runtime = require('../core/runtime');
+
+function assertArgs(args) {
+  if (!Array.isArray(args)) {
+    throw new TypeError('tmux args must be an array');
+  }
+  for (const arg of args) {
+    if (typeof arg !== 'string') {
+      throw new TypeError('tmux args must contain only strings');
+    }
+  }
+}
+
+function runTmux(args, options = {}) {
+  assertArgs(args);
+  return runtime.run(process.env.GUARDEX_TMUX_BIN || 'tmux', args, options);
+}
+
+function isTmuxAvailable() {
+  const result = runTmux(['-V'], { stdio: 'pipe' });
+  return result.status === 0 && !result.error;
+}
+
+module.exports = {
+  isTmuxAvailable,
+  runTmux,
+};

package/src/tmux/session.js

@@ -0,0 +1,89 @@
+const tmux = require('./command');
+
+function requireName(name) {
+  if (typeof name !== 'string' || name.trim() === '') {
+    throw new TypeError('tmux session name must be a non-empty string');
+  }
+  return name;
+}
+
+function addCwd(args, cwd) {
+  if (cwd !== undefined) {
+    if (typeof cwd !== 'string' || cwd.trim() === '') {
+      throw new TypeError('tmux cwd must be a non-empty string');
+    }
+    args.push('-c', cwd);
+  }
+}
+
+function ensureTmuxAvailable() {
+  if (tmux.isTmuxAvailable()) return;
+  throw new Error('tmux is required for gx cockpit. Install tmux and retry.');
+}
+
+function sessionExists(name) {
+  const result = tmux.runTmux(['has-session', '-t', requireName(name)], {
+    stdio: 'pipe',
+  });
+  return result.status === 0;
+}
+
+function createSession(name, cwd) {
+  const args = ['new-session', '-d', '-s', requireName(name)];
+  addCwd(args, cwd);
+  return tmux.runTmux(args);
+}
+
+function attachSession(name) {
+  return tmux.runTmux(['attach-session', '-t', requireName(name)], {
+    stdio: 'inherit',
+  });
+}
+
+function newWindowOrPane(options = {}) {
+  const {
+    target,
+    cwd,
+    name,
+    pane = false,
+    split = 'vertical',
+  } = options;
+  const args = pane ? ['split-window'] : ['new-window'];
+
+  if (pane) {
+    if (split === 'horizontal') {
+      args.push('-h');
+    } else if (split === 'vertical') {
+      args.push('-v');
+    } else {
+      throw new TypeError('tmux split must be horizontal or vertical');
+    }
+  }
+  if (target !== undefined) {
+    args.push('-t', requireName(target));
+  }
+  if (!pane && name !== undefined) {
+    args.push('-n', requireName(name));
+  }
+  addCwd(args, cwd);
+  return tmux.runTmux(args);
+}
+
+function sendKeys(paneId, command) {
+  if (typeof paneId !== 'string' || paneId.trim() === '') {
+    throw new TypeError('tmux pane id must be a non-empty string');
+  }
+  if (typeof command !== 'string') {
+    throw new TypeError('tmux command must be a string');
+  }
+  return tmux.runTmux(['send-keys', '-t', paneId, command, 'C-m']);
+}
+
+module.exports = {
+  ensureTmuxAvailable,
+  sessionExists,
+  createSession,
+  attachSession,
+  newWindowOrPane,
+  sendKeys,
+};

package/src/toolchain/index.js

@@ -293,7 +293,24 @@ function buildMissingCompanionInstallPrompt(missingPackages, missingLocalTools)
   return `${dependencyPrefix}Install missing companion tools now? (${installCommands.join(' && ')})`;
 }
 
+// Process-scoped memo for the slow `npm list -g` probe (~1.6-2.4s). Detection is
+// invariant within one gx invocation, but the bare-`gx`/`gx status` path queries
+// it twice (self-update check + status snapshot). Busted after a global install.
+let globalToolchainDetectionCache = null;
+
+function resetGlobalToolchainDetectionCache() {
+  globalToolchainDetectionCache = null;
+}
+
 function detectGlobalToolchainPackages() {
+  if (globalToolchainDetectionCache) {
+    return globalToolchainDetectionCache;
+  }
+  globalToolchainDetectionCache = computeGlobalToolchainPackages();
+  return globalToolchainDetectionCache;
+}
+
+function computeGlobalToolchainPackages() {
   const result = run(NPM_BIN, ['list', '-g', '--depth=0', '--json']);
   if (result.status !== 0) {
     const stderr = (result.stderr || '').trim();
@@ -563,6 +580,8 @@ function performCompanionInstall(missingPackages, missingLocalTools) {
       };
     }
     installed.push(...missingPackages);
+    // Global package set changed; drop the memo so any later detection re-probes.
+    resetGlobalToolchainDetectionCache();
   }
 
   for (const tool of missingLocalTools) {
@@ -599,6 +618,7 @@ module.exports = {
   describeCompanionInstallCommands,
   buildMissingCompanionInstallPrompt,
   detectGlobalToolchainPackages,
+  resetGlobalToolchainDetectionCache,
   detectRequiredSystemTools,
   detectOptionalLocalCompanionTools,
   askGlobalInstallForMissing,

package/templates/AGENTS.monorepo-apps.md

@@ -0,0 +1,26 @@
+<!-- monorepo-apps:START -->
+## Monorepo workflow (`apps/*`)
+
+This repo has `apps/*` (storefront, backend, etc.). The **root worktree is kept on the protected base branch** so the user can keep `pnpm <app>:dev` running there and see merged-to-main state in real time. Never edit or commit on the root worktree.
+
+### Per-task loop
+
+1. **Start in a sibling worktree.** Run `gx pivot` (auto) or `gx branch start --type <kind> --task <slug>` — both spawn a worktree under `.omx/agent-worktrees/` on a fresh `agent/*` branch.
+2. **Run scoped dev servers from your worktree**, e.g. `pnpm --filter storefront dev` from `.omx/agent-worktrees/<your>/`. Pick a non-conflicting port if the user is already running the root.
+3. **Commit + push** as you go — the agent branch tracks `origin/agent/*`. The user can watch your branch live in their git client.
+4. **Ship via PR.** When the user approves the work, run `gx ship` (alias for `gx finish --via-pr --wait-for-merge --cleanup`). This: opens a PR → auto-merges to the protected base → prunes the worktree + branch.
+5. The user's root worktree is now showing the merged result on next pull.
+
+### Cross-app guardrails
+
+- Edits to **both** `apps/storefront` AND `apps/backend` in one branch → split into two PRs unless they must land atomically. Reviews stay clean, rollbacks stay surgical.
+- Edits to root configs (`pnpm-workspace.yaml`, `turbo.json`, `package.json`) lock every other agent. Claim → change → release fast.
+- Migrations under `apps/backend/src/migrations/*` require explicit user OK before commit — they're irreversible on prod.
+- Don't `pnpm install` from the root unless the user asks; do it inside your worktree if you added a dep.
+
+### What the user sees
+
+- `git log --all --graph --oneline` shows every active agent branch in real time.
+- `gx status` lists active worktrees + their branches.
+- Each `gx ship` produces a PR — link goes in the user's GitHub notifications.
+<!-- monorepo-apps:END -->