@imdeadpool/guardex 7.0.43 → 7.1.0

package/src/scaffold/index.js

@@ -14,6 +14,8 @@ const {
   USER_LEVEL_SKILL_ASSETS,
   AGENTS_MARKER_START,
   AGENTS_MARKER_END,
+  MONOREPO_MARKER_START,
+  MONOREPO_MARKER_END,
   GITIGNORE_MARKER_START,
   GITIGNORE_MARKER_END,
   SHARED_VSCODE_SETTINGS_RELATIVE,
@@ -500,31 +502,54 @@ function removeLegacyManagedRepoFile(repoRoot, relativePath, options = {}) {
   return { status: dryRun ? 'would-remove' : 'removed', file: relativePath };
 }
 
-function ensureAgentsSnippet(repoRoot, dryRun) {
+// A managed block longer than this many non-blank lines is treated as the full
+// contract. The minimal block is ~8 lines and the full contract is ~171, so any
+// threshold between the two is safe; 40 leaves a wide margin on both sides.
+const FULL_BLOCK_LINE_THRESHOLD = 40;
+
+function countNonBlankLines(text) {
+  return text.split('\n').filter((line) => line.trim().length > 0).length;
+}
+
+// Default install ships the minimal block; the full 171-line contract is opt-in
+// via `options.contract` (--contract / --full). Once a repo has the full block,
+// it is never silently downgraded: an existing managed block over the line
+// threshold keeps refreshing from the full template even without the flag.
+function ensureAgentsSnippet(repoRoot, dryRun, options = {}) {
   const agentsPath = path.join(repoRoot, 'AGENTS.md');
-  const snippet = fs.readFileSync(path.join(TEMPLATE_ROOT, 'AGENTS.multiagent-safety.md'), 'utf8').trimEnd();
   const managedRegex = new RegExp(
     `${AGENTS_MARKER_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${AGENTS_MARKER_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`,
     'm',
   );
 
-  if (!fs.existsSync(agentsPath)) {
+  const existing = fs.existsSync(agentsPath) ? fs.readFileSync(agentsPath, 'utf8') : null;
+  const existingBlock = existing ? existing.match(managedRegex) : null;
+  const existingIsFull = Boolean(existingBlock)
+    && countNonBlankLines(existingBlock[0]) > FULL_BLOCK_LINE_THRESHOLD;
+  const wantFull = Boolean(options.contract) || existingIsFull;
+
+  const templateFile = wantFull
+    ? 'AGENTS.multiagent-safety.md'
+    : 'AGENTS.multiagent-safety.min.md';
+  const snippet = fs.readFileSync(path.join(TEMPLATE_ROOT, templateFile), 'utf8').trimEnd();
+  const variant = wantFull ? 'full contract block' : 'minimal block';
+
+  if (existing == null) {
     if (!dryRun) {
       fs.writeFileSync(agentsPath, `# AGENTS\n\n${snippet}\n`, 'utf8');
     }
-    return { status: 'created', file: 'AGENTS.md' };
+    return { status: 'created', file: 'AGENTS.md', note: variant };
   }
 
-  const existing = fs.readFileSync(agentsPath, 'utf8');
-  if (managedRegex.test(existing)) {
-    const next = existing.replace(managedRegex, snippet);
+  if (existingBlock) {
+    const next = existing.replace(managedRegex, () => snippet);
     if (next === existing) {
-      return { status: 'unchanged', file: 'AGENTS.md' };
+      return { status: 'unchanged', file: 'AGENTS.md', note: variant };
     }
     if (!dryRun) {
       fs.writeFileSync(agentsPath, next, 'utf8');
     }
-    return { status: 'updated', file: 'AGENTS.md', note: 'refreshed gitguardex-managed block' };
+    return { status: 'updated', file: 'AGENTS.md', note: `refreshed gitguardex-managed block (${variant})` };
   }
 
   if (existing.includes(AGENTS_MARKER_START)) {
@@ -536,7 +561,7 @@ function ensureAgentsSnippet(repoRoot, dryRun) {
     fs.writeFileSync(agentsPath, `${existing}${separator}${snippet}\n`, 'utf8');
   }
 
-  return { status: 'updated', file: 'AGENTS.md' };
+  return { status: 'updated', file: 'AGENTS.md', note: variant };
 }
 
 function ensureClaudeAgentsLink(repoRoot, dryRun) {
@@ -557,6 +582,77 @@ function ensureClaudeAgentsLink(repoRoot, dryRun) {
   return { status: dryRun ? 'would-create' : 'created', file: 'CLAUDE.md', note: 'symlink to AGENTS.md' };
 }
 
+function detectMonorepoApps(repoRoot) {
+  const appsDir = path.join(repoRoot, 'apps');
+  let stat;
+  try {
+    stat = fs.statSync(appsDir);
+  } catch {
+    return false;
+  }
+  if (!stat.isDirectory()) return false;
+  let entries;
+  try {
+    entries = fs.readdirSync(appsDir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  return entries.some(
+    (entry) =>
+      entry.isDirectory() &&
+      fs.existsSync(path.join(appsDir, entry.name, 'package.json')),
+  );
+}
+
+function ensureMonorepoAppsSnippet(repoRoot, dryRun) {
+  const agentsPath = path.join(repoRoot, 'AGENTS.md');
+  if (!detectMonorepoApps(repoRoot)) {
+    return {
+      status: 'skipped',
+      file: 'AGENTS.md',
+      note: 'no apps/<pkg>/package.json detected — monorepo block not needed',
+    };
+  }
+  const snippet = fs
+    .readFileSync(path.join(TEMPLATE_ROOT, 'AGENTS.monorepo-apps.md'), 'utf8')
+    .trimEnd();
+  const managedRegex = new RegExp(
+    `${MONOREPO_MARKER_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${MONOREPO_MARKER_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`,
+    'm',
+  );
+
+  // Ensure AGENTS.md exists first (created by ensureAgentsSnippet upstream).
+  if (!fs.existsSync(agentsPath)) {
+    if (!dryRun) {
+      fs.writeFileSync(agentsPath, `# AGENTS\n\n${snippet}\n`, 'utf8');
+    }
+    return { status: 'created', file: 'AGENTS.md', note: 'monorepo-apps block' };
+  }
+
+  const existing = fs.readFileSync(agentsPath, 'utf8');
+  if (managedRegex.test(existing)) {
+    const next = existing.replace(managedRegex, snippet);
+    if (next === existing) {
+      return { status: 'unchanged', file: 'AGENTS.md', note: 'monorepo-apps block' };
+    }
+    if (!dryRun) {
+      fs.writeFileSync(agentsPath, next, 'utf8');
+    }
+    return {
+      status: 'updated',
+      file: 'AGENTS.md',
+      note: 'refreshed monorepo-apps block',
+    };
+  }
+
+  const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+  if (!dryRun) {
+    fs.writeFileSync(agentsPath, `${existing}${separator}${snippet}\n`, 'utf8');
+  }
+
+  return { status: 'updated', file: 'AGENTS.md', note: 'appended monorepo-apps block' };
+}
+
 function ensureManagedGitignore(repoRoot, dryRun) {
   const gitignorePath = path.join(repoRoot, '.gitignore');
   const managedBlock = [
@@ -782,6 +878,8 @@ module.exports = {
   removeLegacyManagedRepoFile,
   ensureAgentsSnippet,
   ensureClaudeAgentsLink,
+  ensureMonorepoAppsSnippet,
+  detectMonorepoApps,
   ensureManagedGitignore,
   parseJsonObjectLikeFile,
   buildRepoVscodeSettings,

package/src/speckit/index.js

@@ -0,0 +1,226 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const cp = require('node:child_process');
+
+const { TOOL_NAME, SHORT_TOOL_NAME } = require('../context');
+
+const SPECIFY_BIN = 'specify';
+const SPECKIT_INSTALL_HINT =
+  'uv tool install specify-cli --from git+https://github.com/github/spec-kit.git';
+
+function whichSpecify() {
+  const result = cp.spawnSync(process.platform === 'win32' ? 'where' : 'which', [SPECIFY_BIN], {
+    encoding: 'utf8',
+  });
+  if (result.status === 0 && result.stdout && result.stdout.trim()) {
+    return result.stdout.trim().split(/\r?\n/)[0];
+  }
+  return null;
+}
+
+function specifyVersion(specifyPath) {
+  const result = cp.spawnSync(specifyPath, ['--version'], { encoding: 'utf8' });
+  if (result.status === 0 && result.stdout) {
+    return result.stdout.trim();
+  }
+  return null;
+}
+
+function isGitRepo(target) {
+  try {
+    const result = cp.spawnSync('git', ['-C', target, 'rev-parse', '--git-dir'], {
+      encoding: 'utf8',
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function listSpecKitOpenSpecScaffolds(target) {
+  const planRoot = path.join(target, 'openspec', 'plan');
+  const changesRoot = path.join(target, 'openspec', 'changes');
+  const result = { planDirs: [], specsDirs: [] };
+  if (fs.existsSync(planRoot) && fs.statSync(planRoot).isDirectory()) {
+    for (const entry of fs.readdirSync(planRoot)) {
+      if (/^agent-.*-masterplan-setup-spec-kit-/i.test(entry)) {
+        result.planDirs.push(path.join(planRoot, entry));
+      }
+    }
+  }
+  if (fs.existsSync(changesRoot) && fs.statSync(changesRoot).isDirectory()) {
+    for (const entry of fs.readdirSync(changesRoot)) {
+      if (/^agent-.*-setup-spec-kit-/i.test(entry)) {
+        const specsDir = path.join(changesRoot, entry, 'specs');
+        if (fs.existsSync(specsDir)) result.specsDirs.push(specsDir);
+      }
+    }
+  }
+  return result;
+}
+
+function pruneSpecKitScaffolds(target, { dryRun, logger }) {
+  const found = listSpecKitOpenSpecScaffolds(target);
+  const removed = [];
+  for (const dir of [...found.planDirs, ...found.specsDirs]) {
+    if (dryRun) {
+      logger(`[${TOOL_NAME}] dry-run: would prune ${path.relative(target, dir)}`);
+    } else {
+      fs.rmSync(dir, { recursive: true, force: true });
+      logger(`[${TOOL_NAME}] pruned ${path.relative(target, dir)}`);
+    }
+    removed.push(dir);
+  }
+  return removed;
+}
+
+function runSpecifyInit(target, { dryRun, logger }) {
+  const args = ['init', '--here', '--ai', 'claude', '--force', '--ignore-agent-tools'];
+  if (dryRun) {
+    logger(`[${TOOL_NAME}] dry-run: would run \`${SPECIFY_BIN} ${args.join(' ')}\` in ${target}`);
+    return { status: 'dry-run' };
+  }
+  const result = cp.spawnSync(SPECIFY_BIN, args, {
+    cwd: target,
+    stdio: 'inherit',
+  });
+  if (result.status !== 0) {
+    throw new Error(`${SPECIFY_BIN} init exited with status ${result.status}`);
+  }
+  return { status: 'ok' };
+}
+
+function isSpecKitAlreadyInstalled(target) {
+  return fs.existsSync(path.join(target, '.specify', 'integration.json'));
+}
+
+function installSpeckit({
+  target = process.cwd(),
+  dryRun = false,
+  prune = true,
+  force = false,
+  silent = false,
+  logger = console.log,
+}) {
+  const resolved = path.resolve(target);
+  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+    if (silent) {
+      logger(`[${TOOL_NAME}] ⚠️ speckit: target ${resolved} does not exist; skipping.`);
+      return { status: 'skipped', reason: 'no-target' };
+    }
+    throw new Error(`Target directory does not exist: ${resolved}`);
+  }
+  if (!isGitRepo(resolved)) {
+    logger(
+      `[${TOOL_NAME}] ⚠️ ${resolved} is not a git repo. Spec Kit will scaffold without git extension wiring.`,
+    );
+  }
+  if (!force && isSpecKitAlreadyInstalled(resolved)) {
+    logger(`[${TOOL_NAME}] ✅ Spec Kit already installed at ${resolved}/.specify (use --speckit-force to reinstall).`);
+    return { status: 'already-installed', target: resolved };
+  }
+  const specifyPath = whichSpecify();
+  if (!specifyPath) {
+    if (silent) {
+      logger(
+        `[${TOOL_NAME}] ⚠️ speckit: \`${SPECIFY_BIN}\` not on PATH; skipping speckit install. ` +
+        `Install with: ${SPECKIT_INSTALL_HINT}`,
+      );
+      return { status: 'skipped', reason: 'specify-missing' };
+    }
+    throw new Error(
+      `${SPECIFY_BIN} CLI not found on PATH. Install with:\n  ${SPECKIT_INSTALL_HINT}`,
+    );
+  }
+  const version = specifyVersion(specifyPath);
+  logger(`[${TOOL_NAME}] specify-cli: ${specifyPath}${version ? ` (${version})` : ''}`);
+  logger(`[${TOOL_NAME}] Running \`${SPECIFY_BIN} init --here --ai claude --force\` in ${resolved}`);
+
+  const initResult = runSpecifyInit(resolved, { dryRun, logger });
+
+  let pruned = [];
+  if (prune && (initResult.status === 'ok' || dryRun)) {
+    pruned = pruneSpecKitScaffolds(resolved, { dryRun, logger });
+  }
+
+  logger('');
+  logger(`[${TOOL_NAME}] ✅ Spec Kit installed. Next:`);
+  logger(`  - Start a fresh Claude session at ${resolved}`);
+  logger(`  - Use slash skills: /speckit-constitution, /speckit-specify, /speckit-plan, /speckit-tasks, /speckit-implement`);
+  logger(`  - Agent worktree flow is unchanged — run \`${SHORT_TOOL_NAME} pivot "<task>" "claude"\` to start work.`);
+
+  return { status: 'installed', specifyPath, version, dryRun, prunedScaffolds: pruned, target: resolved };
+}
+
+function printSpeckitHelp() {
+  const lines = [
+    `Usage: ${SHORT_TOOL_NAME} speckit [options]`,
+    '',
+    '  Install Spec Kit (specify-cli) SDD slash skills into the current repo.',
+    '  Runs `specify init --here --ai claude --force --ignore-agent-tools` and',
+    '  prunes the heavy auto-generated openspec/plan + specs/ scaffolds the',
+    '  specify-cli emits, so it composes cleanly with the existing gx workflow.',
+    '',
+    'Options:',
+    '  --target <path>   Run in <path> instead of cwd',
+    '  --no-prune        Keep the auto-generated openspec/plan + specs scaffolds',
+    '  --dry-run         Print actions without modifying files',
+    '  -h, --help        Show this help',
+    '',
+    'Prerequisite:',
+    `  ${SPECIFY_BIN} CLI on PATH. Install with:`,
+    `    ${SPECKIT_INSTALL_HINT}`,
+  ];
+  console.log(lines.join('\n'));
+}
+
+function runSpeckitCommand(rawArgs) {
+  const args = Array.isArray(rawArgs) ? [...rawArgs] : [];
+  let target = process.cwd();
+  let prune = true;
+  let dryRun = false;
+  let force = false;
+
+  while (args.length > 0) {
+    const arg = args.shift();
+    if (arg === '-h' || arg === '--help' || arg === 'help') {
+      printSpeckitHelp();
+      return;
+    }
+    if (arg === '--target') {
+      const next = args.shift();
+      if (!next) throw new Error('--target requires a path value');
+      target = next;
+      continue;
+    }
+    if (arg === '--no-prune') {
+      prune = false;
+      continue;
+    }
+    if (arg === '--prune') {
+      prune = true;
+      continue;
+    }
+    if (arg === '--dry-run') {
+      dryRun = true;
+      continue;
+    }
+    if (arg === '--force' || arg === '--reinstall') {
+      force = true;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  installSpeckit({ target, prune, dryRun, force });
+}
+
+module.exports = {
+  runSpeckitCommand,
+  installSpeckit,
+  pruneSpecKitScaffolds,
+  whichSpecify,
+  isSpecKitAlreadyInstalled,
+};

package/src/terminal/index.js

@@ -14,6 +14,7 @@ function normalizeBackendName(value, fallback = DEFAULT_BACKEND) {
   return normalized;
 }
 
+// Internal: build the kitty/tmux backend pair consumed by selectTerminalBackend.
 function createBackends(options = {}) {
   return {
     kitty: options.kittyBackend || kitty.createBackend(options.kitty || {}),
@@ -21,73 +22,6 @@ function createBackends(options = {}) {
   };
 }
 
-function firstText(...values) {
-  for (const value of values) {
-    if (typeof value === 'string' && value.trim().length > 0) return value.trim();
-  }
-  return '';
-}
-
-function metadataOf(target = {}) {
-  return target.metadata && typeof target.metadata === 'object' ? target.metadata : {};
-}
-
-function terminalOf(target = {}) {
-  return target.terminal && typeof target.terminal === 'object' ? target.terminal : {};
-}
-
-function tmuxOf(target = {}) {
-  return target.tmux && typeof target.tmux === 'object' ? target.tmux : {};
-}
-
-function kittyOf(target = {}) {
-  return target.kitty && typeof target.kitty === 'object' ? target.kitty : {};
-}
-
-function resolveTargetBackendName(target = {}, fallback = '') {
-  const metadata = metadataOf(target);
-  const terminal = terminalOf(target);
-  const explicit = firstText(
-    target.terminalBackend,
-    target.backend,
-    terminal.backend,
-    metadata.terminalBackend,
-    metadata['terminal.backend'],
-  );
-  if (explicit) return normalizeBackendName(explicit);
-
-  const tmux = tmuxOf(target);
-  if (firstText(target.paneId, target.tmuxPaneId, target.tmuxTarget, tmux.paneId, tmux.target, metadata.tmuxPaneId, metadata['tmux.paneId'])) {
-    return 'tmux';
-  }
-
-  const kittyTarget = kittyOf(target);
-  if (firstText(
-    target.kittyMatch,
-    target.match,
-    target.kittyWindowId,
-    target.windowId,
-    target.kittyTitle,
-    target.windowTitle,
-    terminal.match,
-    terminal.windowId,
-    terminal.title,
-    kittyTarget.match,
-    kittyTarget.windowId,
-    kittyTarget.title,
-    metadata.kittyMatch,
-    metadata['kitty.match'],
-    metadata.kittyWindowId,
-    metadata['kitty.windowId'],
-    metadata.kittyTitle,
-    metadata['kitty.title'],
-  )) {
-    return 'kitty';
-  }
-
-  return fallback ? normalizeBackendName(fallback) : '';
-}
-
 function selectTerminalBackend(value = DEFAULT_BACKEND, options = {}) {
   const name = normalizeBackendName(value);
   const backends = createBackends(options);
@@ -102,19 +36,10 @@ function selectTerminalBackend(value = DEFAULT_BACKEND, options = {}) {
   return backends[name];
 }
 
-function selectTerminalBackendForTarget(target = {}, options = {}) {
-  const name = resolveTargetBackendName(target, options.defaultBackend);
-  if (!name) return null;
-  return selectTerminalBackend(name, options);
-}
-
 module.exports = {
   DEFAULT_BACKEND,
   normalizeBackendName,
-  resolveTargetBackendName,
   selectTerminalBackend,
-  selectTerminalBackendForTarget,
-  createBackends,
   kitty,
   tmux,
 };

package/src/terminal/tmux.js

@@ -122,5 +122,4 @@ function createBackend(options = {}) {
 
 module.exports = {
   createBackend,
-  targetId,
 };

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 -->