@imdeadpool/guardex 7.0.41 → 7.1.0

package/src/scaffold/agent-worktree-prep.js

@@ -0,0 +1,213 @@
+'use strict';
+
+// Prepares a freshly-created agent worktree for monorepos that have `apps/*`
+// packages. Two jobs:
+//
+//   1. Symlink the root's `apps/<pkg>/.env` (and friends) into the worktree
+//      so backend / storefront / etc. can boot with the same secrets without
+//      asking the user to copy gitignored env files manually.
+//
+//   2. Pick a free port per app and write it into the worktree's
+//      `apps/<pkg>/.env.local` (which both Vite and Medusa's loadEnv read with
+//      higher precedence than `.env`). This stops agent dev servers from
+//      colliding with whatever's running in the root worktree on the default
+//      port.
+//
+// Both jobs are best-effort: if `apps/` doesn't exist, or there are no env
+// files / no package.json in a subfolder, we silently skip — non-monorepo
+// repos see no change.
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ENV_FILE_CANDIDATES = [
+  '.env',
+  '.env.local',
+  '.env.development',
+  '.env.development.local',
+  '.env.production',
+  '.env.production.local',
+];
+
+// Port pool by detected app role. Storefronts get the Vite/Next range,
+// backends get the Medusa range, everything else gets a generic mid-range.
+const PORT_POOLS = {
+  storefront: 5174,
+  backend: 9101,
+  default: 8100,
+};
+
+function detectAppPackages(repoRoot) {
+  const appsRoot = path.join(repoRoot, 'apps');
+  let stat;
+  try {
+    stat = fs.statSync(appsRoot);
+  } catch {
+    return [];
+  }
+  if (!stat.isDirectory()) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(appsRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .filter((name) => fs.existsSync(path.join(appsRoot, name, 'package.json')));
+}
+
+function inferAppRole(appName) {
+  const n = appName.toLowerCase();
+  if (n.includes('storefront') || n.includes('frontend') || n.includes('web')) {
+    return 'storefront';
+  }
+  if (n.includes('backend') || n.includes('api') || n.includes('server')) {
+    return 'backend';
+  }
+  return 'default';
+}
+
+function isPortFree(port) {
+  // Use `lsof` if available — it's on macOS and most Linux distros. Fall
+  // back to assuming free when lsof isn't installed (e.g. minimal Alpine
+  // CI image); the dev server will fail loudly if it isn't.
+  const probe = spawnSync('lsof', ['-iTCP:' + port, '-sTCP:LISTEN', '-t'], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 2000,
+  });
+  if (probe.error) return true;
+  const out = (probe.stdout && probe.stdout.toString().trim()) || '';
+  return out === '';
+}
+
+function pickFreePort(start) {
+  for (let p = start; p < start + 200; p++) {
+    if (isPortFree(p)) return p;
+  }
+  return null;
+}
+
+function symlinkAppEnvFiles(repoRoot, worktreePath, appName) {
+  const operations = [];
+  const rootAppDir = path.join(repoRoot, 'apps', appName);
+  const wtAppDir = path.join(worktreePath, 'apps', appName);
+  if (!fs.existsSync(wtAppDir)) {
+    return operations;
+  }
+  for (const candidate of ENV_FILE_CANDIDATES) {
+    const rootEnv = path.join(rootAppDir, candidate);
+    const wtEnv = path.join(wtAppDir, candidate);
+    if (!fs.existsSync(rootEnv)) continue;
+    // Don't overwrite an existing file/symlink in the worktree.
+    let alreadyExists = false;
+    try {
+      fs.lstatSync(wtEnv);
+      alreadyExists = true;
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+    }
+    if (alreadyExists) {
+      operations.push({
+        status: 'unchanged',
+        file: `apps/${appName}/${candidate}`,
+        note: 'already present in worktree',
+      });
+      continue;
+    }
+    try {
+      fs.symlinkSync(rootEnv, wtEnv);
+      operations.push({
+        status: 'linked',
+        file: `apps/${appName}/${candidate}`,
+        note: `→ ${path.relative(worktreePath, rootEnv)}`,
+      });
+    } catch (err) {
+      operations.push({
+        status: 'failed',
+        file: `apps/${appName}/${candidate}`,
+        note: `symlink failed: ${err.message}`,
+      });
+    }
+  }
+  return operations;
+}
+
+function assignAgentPort(repoRoot, worktreePath, appName, takenPorts) {
+  const wtAppDir = path.join(worktreePath, 'apps', appName);
+  if (!fs.existsSync(wtAppDir)) {
+    return { status: 'skipped', file: `apps/${appName}`, note: 'no app dir in worktree' };
+  }
+  const role = inferAppRole(appName);
+  const base = PORT_POOLS[role] || PORT_POOLS.default;
+  let port = pickFreePort(base);
+  // Bump past anything we've already assigned this run.
+  while (port !== null && takenPorts.has(port)) {
+    port = pickFreePort(port + 1);
+  }
+  if (port === null) {
+    return {
+      status: 'failed',
+      file: `apps/${appName}/.env.local`,
+      note: 'no free port found in pool',
+    };
+  }
+  takenPorts.add(port);
+
+  const envLocalPath = path.join(wtAppDir, '.env.local');
+  let existing = '';
+  try {
+    existing = fs.readFileSync(envLocalPath, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+
+  // If a .env.local already exists, replace the PORT= line if present,
+  // otherwise append. Keep everything else the user might have added.
+  const portLine = `PORT=${port}`;
+  let next;
+  if (/^PORT=/m.test(existing)) {
+    next = existing.replace(/^PORT=.*$/m, portLine);
+  } else {
+    const sep = existing.length === 0 || existing.endsWith('\n') ? '' : '\n';
+    next = `${existing}${sep}${portLine}\n`;
+    // Header on fresh files so the user knows what wrote this.
+    if (existing.length === 0) {
+      next = `# Written by gitguardex on worktree creation — agent dev server port.\n${portLine}\n`;
+    }
+  }
+  fs.writeFileSync(envLocalPath, next, 'utf8');
+  return {
+    status: 'wrote',
+    file: `apps/${appName}/.env.local`,
+    note: `PORT=${port} (${role} pool)`,
+  };
+}
+
+function prepareAgentWorktree(repoRoot, worktreePath) {
+  if (!repoRoot || !worktreePath) return [];
+  if (repoRoot === worktreePath) return [];
+  if (!fs.existsSync(worktreePath)) return [];
+  const apps = detectAppPackages(repoRoot);
+  if (apps.length === 0) return [];
+
+  const operations = [];
+  const takenPorts = new Set();
+  for (const appName of apps) {
+    operations.push(...symlinkAppEnvFiles(repoRoot, worktreePath, appName));
+    operations.push(assignAgentPort(repoRoot, worktreePath, appName, takenPorts));
+  }
+  return operations;
+}
+
+module.exports = {
+  detectAppPackages,
+  inferAppRole,
+  isPortFree,
+  pickFreePort,
+  symlinkAppEnvFiles,
+  assignAgentPort,
+  prepareAgentWorktree,
+};

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,96 @@ 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) {
+  const claudePath = path.join(repoRoot, 'CLAUDE.md');
+  try {
+    fs.lstatSync(claudePath);
+    return { status: 'unchanged', file: 'CLAUDE.md', note: 'existing path preserved' };
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+
+  if (!dryRun) {
+    fs.symlinkSync('AGENTS.md', claudePath);
+  }
+
+  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) {
@@ -763,6 +877,9 @@ module.exports = {
   installUserLevelAsset,
   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,
+};