harness-everything 0.3.6 → 0.4.0

package/repo-docs/SKILL.md

@@ -4,7 +4,7 @@ description: Generate or update precise, reader-oriented README.md and AGENTS.md
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.3.4
+  version: 0.4.0
 ---
 
 # Repo Docs (Automated Project Documentation Generation & Smart Merging)
@@ -37,10 +37,6 @@ Merges codebase scan facts and bespoke notes into `README.md`/`AGENTS.md`.
 3. Pick a template below; else built-in structure.
 4. Draft: `README.md` = user journey; `AGENTS.md` = conventions, build/test commands.
 5. [Summarize] Verify commands run; mark doubts `// TODO: Pending confirmation`; ask (`grill-me`).
-6. Write to root; if protected, `.github/AGENTS.md`/`docs/README.md`.
+6. Write to root; if protected, `<workspace>/.github/AGENTS.md`/`<workspace>/docs/README.md`.
 
-## `repo-docs/templates/`
-
-readme-template.md · product-readme-template.md · multi-skills-readme-template.md · single-skill-readme-template.md · knowledge-readme-template.md · agents-template.md · product-agents-template.md · skills-agents-template.md · knowledge-agents-template.md · manual-recon.md
-
-Deep dive: references/process-guide.md
+Deep dive: <this-skill-dir>/references/process-guide.md

package/rewrite-commits/SKILL.md

@@ -4,7 +4,7 @@ description: "Rewrite past Git history to comply with Angular Style conventions.
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.3.4
+  version: 0.4.0
 ---
 
 # Rewrite Commits
@@ -34,4 +34,4 @@ metadata:
 2. `[Think] & [Try]` Create a temp branch. Never run bare interactive `git rebase -i`; prefer `git reset --soft HEAD~<N>` plus structured commits, or Node.js scripting (no hardcoded `sed -i`). Messages MUST follow Angular Style per the `git-commit` skill.
 3. `[Summarize]` Run `git log --oneline` for confirmation. On merge conflict, run `git rebase --abort`, STOP, and hand over to human decision or trigger `zoom-out`.
 
-Deep dive: references/workflow.md
+Deep dive: <this-skill-dir>/references/workflow.md

package/scripts/build-openai-submission.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+const SKILLS_ROOT = path.join(ROOT, 'plugins', 'harness-everything', 'skills');
+const DEFAULT_OUTPUT = path.join(ROOT, 'dist', 'openai-submission', 'harness-everything-skills.zip');
+
+function parseArgs(argv) {
+  let output = DEFAULT_OUTPUT;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--output') {
+      if (!argv[i + 1]) throw new Error('--output requires a path');
+      output = path.resolve(argv[++i]);
+    } else {
+      throw new Error(`unknown argument: ${argv[i]}`);
+    }
+  }
+  return { output };
+}
+
+function filesUnder(root, base = root, out = []) {
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const full = path.join(root, entry.name);
+    if (entry.isDirectory()) filesUnder(full, base, out);
+    else if (entry.isFile()) out.push(path.relative(base, full).replace(/\\/g, '/'));
+  }
+  return out.sort();
+}
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) c = (c & 1) ? (0xedb88320 ^ (c >>> 1)) : (c >>> 1);
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(buffer) {
+  let c = 0xffffffff;
+  for (const byte of buffer) c = CRC_TABLE[(c ^ byte) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function zipStored(entries) {
+  const localParts = [];
+  const centralParts = [];
+  let offset = 0;
+
+  for (const entry of entries) {
+    const name = Buffer.from(entry.name, 'utf8');
+    const data = entry.data;
+    const crc = crc32(data);
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(0x0800, 6);
+    local.writeUInt16LE(0, 8);
+    local.writeUInt16LE(0, 10);
+    local.writeUInt16LE(33, 12); // 1980-01-01, 00:00:00
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(data.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(name.length, 26);
+    local.writeUInt16LE(0, 28);
+
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(0x02014b50, 0);
+    central.writeUInt16LE(0x0314, 4); // ZIP 2.0, Unix creator
+    central.writeUInt16LE(20, 6);
+    central.writeUInt16LE(0x0800, 8);
+    central.writeUInt16LE(0, 10);
+    central.writeUInt16LE(0, 12);
+    central.writeUInt16LE(33, 14);
+    central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(data.length, 20);
+    central.writeUInt32LE(data.length, 24);
+    central.writeUInt16LE(name.length, 28);
+    central.writeUInt16LE(0, 30);
+    central.writeUInt16LE(0, 32);
+    central.writeUInt16LE(0, 34);
+    central.writeUInt16LE(0, 36);
+    const mode = entry.name.endsWith('.sh') ? 0o100755 : 0o100644;
+    central.writeUInt32LE((mode << 16) >>> 0, 38);
+    central.writeUInt32LE(offset, 42);
+
+    localParts.push(local, name, data);
+    centralParts.push(central, name);
+    offset += local.length + name.length + data.length;
+  }
+
+  const centralDirectory = Buffer.concat(centralParts);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(0, 4);
+  end.writeUInt16LE(0, 6);
+  end.writeUInt16LE(entries.length, 8);
+  end.writeUInt16LE(entries.length, 10);
+  end.writeUInt32LE(centralDirectory.length, 12);
+  end.writeUInt32LE(offset, 16);
+  end.writeUInt16LE(0, 20);
+
+  return Buffer.concat([...localParts, centralDirectory, end]);
+}
+
+function sha256(buffer) {
+  return crypto.createHash('sha256').update(buffer).digest('hex');
+}
+
+function build(output) {
+  if (!fs.existsSync(SKILLS_ROOT)) throw new Error(`packaged skills not found: ${SKILLS_ROOT}`);
+  const relativeFiles = filesUnder(SKILLS_ROOT);
+  if (relativeFiles.length === 0) throw new Error('no packaged skill files found');
+
+  const entries = relativeFiles.map(relative => {
+    const data = fs.readFileSync(path.join(SKILLS_ROOT, relative));
+    return { name: `skills/${relative}`, data };
+  });
+  const zip = zipStored(entries);
+  fs.mkdirSync(path.dirname(output), { recursive: true });
+  fs.writeFileSync(output, zip);
+
+  const manifest = {
+    format: 'harness-openai-skill-bundle-manifest-v1',
+    source: 'plugins/harness-everything/skills',
+    file_count: entries.length,
+    bundle_sha256: sha256(zip),
+    files: entries.map(entry => ({
+      path: entry.name,
+      bytes: entry.data.length,
+      sha256: sha256(entry.data)
+    }))
+  };
+  const manifestPath = output.replace(/\.zip$/i, '') + '.manifest.json';
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  console.log(`OpenAI skill bundle: ${output}`);
+  console.log(`Files: ${manifest.file_count}`);
+  console.log(`SHA256: ${manifest.bundle_sha256}`);
+  console.log(`Manifest: ${manifestPath}`);
+  return { output, manifestPath, manifest };
+}
+
+if (require.main === module) {
+  try {
+    const { output } = parseArgs(process.argv.slice(2));
+    build(output);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = { build, crc32, filesUnder, zipStored };

package/scripts/installer.js

@@ -26,7 +26,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const { getWorkspaceRoot, getUserPromptsDir } = require('./lib/workspace');
+const { getWorkspaceRoot, getWorkspaceStateDir, getUserPromptsDir } = require('./lib/workspace');
 const { interactiveSelect, interactiveSingleSelect, askQuestion } = require('./lib/prompts');
 const advisory = require('./lib/advisory-text');
 const claudeHooks = require('./lib/claude-hooks');
@@ -35,7 +35,12 @@ const skills = require('./lib/skills');
 const { ensureWorkspaceGitignorePatterns, removeWorkspaceExcludePatterns, cleanEmptyDirs } = require('./lib/gitignore');
 
 const userHome = require('os').homedir();
-const workspaceRoot = getWorkspaceRoot();
+const detectedWorkspaceRoot = getWorkspaceRoot();
+// Global installs are valid outside a repository, but the module still needs
+// a non-null path while it evaluates local-detection helpers. Keep this
+// fallback private to global mode; main() rejects non-global work from a
+// directory whose workspace identity cannot be resolved.
+const workspaceRoot = detectedWorkspaceRoot || path.resolve(process.cwd());
 const harnessSourceDir = path.resolve(__dirname, '..');
 const packageVersion = require(path.join(harnessSourceDir, 'package.json')).version;
 
@@ -65,7 +70,16 @@ async function main() {
   // workspace - skill installation is an explicit user choice, never a
   // side effect of a background repair.
   const hasNoSkillsFlag = args.includes('--no-skills');
+  if (!detectedWorkspaceRoot && !hasGlobalFlag) {
+    throw new Error('cannot install locally outside a git workspace; pass --global for a user-wide install');
+  }
   const hasAnyPlatformFlag = hasClaudeFlag || hasCursorFlag || hasCopilotFlag || hasCodexFlag || hasContinueFlag || hasHermesFlag || hasAllFlag;
+  // #49: default 'auto' tries a junction (Windows) / symlink (elsewhere) into
+  // one canonical per-scope copy and silently falls back to an independent
+  // physical copy per target if that fails. --copy/--symlink override the
+  // auto-detection explicitly - --symlink surfaces a link failure as an
+  // error instead of silently falling back, since the user asked for it.
+  const linkMode = args.includes('--copy') ? 'copy' : args.includes('--symlink') ? 'symlink' : 'auto';
   
   let requestedSkills = ['add', 'skill', 'skills'].includes(command)
     ? args.slice(3).filter(arg => !arg.startsWith('-'))
@@ -263,7 +277,8 @@ async function main() {
     }
 
     console.log(`\nInstalling Harness skills:`);
-    skills.installSkillsToTargets({ chosenSkills, targetDirs, harnessSourceDir, packageVersion });
+    const canonicalDir = skills.getCanonicalSkillsDir({ isGlobal, workspaceRoot, userHome });
+    skills.installSkillsToTargets({ chosenSkills, targetDirs, harnessSourceDir, packageVersion, canonicalDir, linkMode });
 
     // Claude Code discovers named agents from .claude/agents/, not from a
     // nested skill directory. Keep the source copies in fable-mode for plugin
@@ -297,6 +312,16 @@ async function main() {
       if (targets.continue) patternsToIgnore.push('.continue/harness-everything/', '.continue/skills/');
     }
 
+    // The local canonical skills store (#49) is new territory - .agents/
+    // wasn't previously a Harness-owned local directory - so it needs its
+    // own ignore pattern rather than relying on any platform's own list.
+    if (chosenSkills.length > 0 && linkMode !== 'copy') {
+      const canonicalDir = skills.getCanonicalSkillsDir({ isGlobal: false, workspaceRoot, userHome });
+      if (fs.existsSync(canonicalDir)) {
+        patternsToIgnore.push('.agents/skills/');
+      }
+    }
+
     ensureWorkspaceGitignorePatterns(workspaceRoot, patternsToIgnore);
   }
 
@@ -339,7 +364,29 @@ async function runUninstall({ hasYesFlag, args, isInteractive }) {
   let removeGlobal = false;
   let removeSkills = false;
 
-  const runInteractively = isInteractive && !hasYesFlag;
+  const hasLocalFlag = args.includes('--local');
+  const hasGlobalUninstallFlag = args.includes('--global') || args.includes('-g');
+  const hasSkillsUninstallFlag = args.includes('--skills');
+  // #48: any explicit scope flag wins over the interactive menu, even with a
+  // TTY attached - so `uninstall --local --global --skills` actually does
+  // what it says instead of being silently swapped for the checkbox menu
+  // (where only -y previously had that effect). Only a truly bare `uninstall`
+  // (no flags at all) still goes interactive when a TTY is available.
+  const hasAnyScopeFlag = hasYesFlag || hasLocalFlag || hasGlobalUninstallFlag || hasSkillsUninstallFlag;
+  const runInteractively = isInteractive && !hasAnyScopeFlag;
+
+  if (!runInteractively && !hasAnyScopeFlag) {
+    // #48: no flags AND no interactive terminal to fall back on - this used
+    // to silently do nothing while still printing "UNINSTALL COMPLETE!".
+    // Fail loudly instead so a non-TTY invocation (npx in some shells/CI/
+    // piped input) never looks like a successful no-op.
+    console.error("\n❌ No scope specified and no interactive terminal detected.");
+    console.error("   Pass flags to say what to remove, e.g.:");
+    console.error("     uninstall --local --skills");
+    console.error("     uninstall --local --global --skills -y");
+    console.error("   ...or run this command in an interactive terminal to use the menu.");
+    process.exit(1);
+  }
 
   if (runInteractively) {
     const choices = [];
@@ -385,7 +432,7 @@ async function runUninstall({ hasYesFlag, args, isInteractive }) {
         const chosenSkillsToRemove = await interactiveSelect(selectSkillItems);
         for (const item of chosenSkillsToRemove) {
           if (item.checked) {
-            skills.removeSkill(item._entry);
+            skills.removeSkill(item._entry, { workspaceRoot, userHome });
             console.log(`  ✅ Removed skill: ${item.name}`);
             cleanEmptyDirs(item._entry.parentPath, [workspaceRoot, userHome]);
           }
@@ -393,10 +440,6 @@ async function runUninstall({ hasYesFlag, args, isInteractive }) {
       }
     }
   } else {
-    const hasLocalFlag = args.includes('--local');
-    const hasGlobalUninstallFlag = args.includes('--global') || args.includes('-g');
-    const hasSkillsUninstallFlag = args.includes('--skills');
-
     if (hasYesFlag) {
       // -y auto-confirms local (cwd-scoped, obviously "this project") but
       // must NEVER auto-confirm global (~/.agents, ~/.claude, etc.) just
@@ -432,6 +475,11 @@ async function runUninstall({ hasYesFlag, args, isInteractive }) {
       }
 
       if (typeof platform.getStateDir === 'function') {
+        // Legacy per-workspace state dir (pre-#42) - almost always already
+        // gone by the time uninstall runs, since the first hook invocation
+        // after the fix migrates it into the global home below. Kept as a
+        // no-op-in-the-common-case safety net for a workspace that was
+        // never actually used since upgrading.
         const stateDir = platform.getStateDir(workspaceRoot);
         if (fs.existsSync(stateDir)) {
           fs.rmSync(stateDir, { recursive: true, force: true });
@@ -440,6 +488,16 @@ async function runUninstall({ hasYesFlag, args, isInteractive }) {
       }
     }
 
+    // Runtime state for this workspace now lives outside it entirely, under
+    // ~/.agents/harness-everything/workspaces/<key>/ (issue #42) - remove
+    // this workspace's slice of it too, so uninstalling doesn't leave an
+    // orphaned global state dir behind.
+    const globalWorkspaceStateDir = getWorkspaceStateDir(workspaceRoot);
+    if (fs.existsSync(globalWorkspaceStateDir)) {
+      fs.rmSync(globalWorkspaceStateDir, { recursive: true, force: true });
+      console.log(`  ✅ Removed global runtime state for this workspace (${globalWorkspaceStateDir})`);
+    }
+
     // One-time migration cleanup: earlier versions used a self-invented
     // top-level .harness/ directory for Claude's manifest + skill copies.
     const legacyHarnessDir = path.join(workspaceRoot, '.harness');
@@ -513,8 +571,11 @@ async function runUninstall({ hasYesFlag, args, isInteractive }) {
     console.log("Uninstalling all detected skills...");
     console.log("-------------------------------------------------");
     for (const skill of skillsToRemove) {
-      if (fs.existsSync(skill.dirPath)) {
-        skills.removeSkill(skill);
+      // pathPresent (not bare existsSync) so a dangling link - its canonical
+      // target already gone - still gets its manifest row cleaned up instead
+      // of being silently skipped forever.
+      if (skills.pathPresent(skill.dirPath)) {
+        skills.removeSkill(skill, { workspaceRoot, userHome });
         console.log(`  ✅ Removed skill: ${skill.id} (${skill.scope})`);
         cleanEmptyDirs(skill.parentPath, [workspaceRoot, userHome]);
       }
@@ -536,6 +597,20 @@ async function runUninstall({ hasYesFlag, args, isInteractive }) {
   }
   cleanEmptyDirs(path.join(workspaceRoot, '.claude'), [workspaceRoot, userHome]);
 
+  // Canonical skills store (#49) - removeSkill() above already deletes each
+  // now-unreferenced canonical copy as its last link goes; this just tidies
+  // up the now-empty .agents/skills/ (and .agents/ itself, if nothing else
+  // put anything there). Runs here rather than inside the removeLocal/
+  // removeGlobal blocks above because skill removal itself happens later,
+  // in the removeSkills block below those - running any earlier would find
+  // the directory still populated.
+  if (removeLocal) {
+    cleanEmptyDirs(skills.getCanonicalSkillsDir({ isGlobal: false, workspaceRoot, userHome }), [workspaceRoot, userHome]);
+  }
+  if (removeGlobal) {
+    cleanEmptyDirs(skills.getCanonicalSkillsDir({ isGlobal: true, workspaceRoot, userHome }), [userHome]);
+  }
+
   console.log("\n🎉 UNINSTALL COMPLETE! Harness OS has been removed.");
   console.log("=================================================");
 }

package/scripts/lib/advisory-text.js

@@ -1,7 +1,6 @@
 // Prompt-injection-only guidance for platforms with no hook/execution
 // mechanism (Cursor, Copilot, Codex, Continue, Hermes). Single source of
-// truth for the advisory block - it used to be duplicated verbatim inside
-// installer.js's top level and again inside main().
+// truth for the advisory block.
 const fs = require('fs');
 const path = require('path');
 
@@ -37,13 +36,25 @@ const advisoryInstructions = [
   ``
 ].join('\n');
 
+function hasHarnessMarker(content) {
+  return typeof content === 'string' && content.includes(MARKER);
+}
+
+function assertHarnessOwnedOrAbsent(targetFile, label) {
+  if (!fs.existsSync(targetFile)) return;
+  const content = fs.readFileSync(targetFile, 'utf8');
+  if (!hasHarnessMarker(content)) {
+    throw new Error(`Refusing to overwrite pre-existing non-Harness ${label}: ${targetFile}`);
+  }
+}
+
 function injectAdvisoryText(targetFile, header, label) {
   const dir = path.dirname(targetFile);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 
   if (fs.existsSync(targetFile)) {
     const content = fs.readFileSync(targetFile, 'utf8');
-    if (!content.includes(MARKER)) {
+    if (!hasHarnessMarker(content)) {
       fs.appendFileSync(targetFile, advisoryInstructions, 'utf8');
       console.log(`  ✅ Augmented existing ${label} with Harness guidance (advisory-only)`);
     }
@@ -61,11 +72,8 @@ function removeAdvisoryText(targetFile) {
     if (markerIndex !== -1) {
       let cleanContent = content;
       const hashMarkerIndex = content.lastIndexOf('#', markerIndex);
-      if (hashMarkerIndex !== -1) {
-        cleanContent = content.substring(0, hashMarkerIndex).trim() + '\n';
-      } else {
-        cleanContent = content.substring(0, markerIndex).trim() + '\n';
-      }
+      if (hashMarkerIndex !== -1) cleanContent = content.substring(0, hashMarkerIndex).trim() + '\n';
+      else cleanContent = content.substring(0, markerIndex).trim() + '\n';
 
       const lines = cleanContent.trim().split('\n').map(l => l.trim()).filter(l => l !== '');
       if (lines.length === 0 || (lines.length === 1 && (lines[0] === '# Cursor Project Rules' || lines[0] === '# AGENTS.md' || lines[0] === '# Copilot Instructions' || lines[0] === '# .hermes.md'))) {
@@ -81,17 +89,13 @@ function removeAdvisoryText(targetFile) {
   }
 }
 
-// Continue.dev reads project rules as individual Markdown files (with YAML
-// frontmatter) from a `.continue/rules/` folder rather than one shared file,
-// so - unlike the shared-file platforms above - Harness gets its own
-// dedicated `harness.md` rule file instead of appending into an arbitrary
-// pre-existing one.
+// Continue gets a dedicated rule file. If a user already owns that exact
+// path, do not replace it just because Harness chose the same filename.
 function installContinueRule(targetFile, label) {
   const dir = path.dirname(targetFile);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-  if (fs.existsSync(targetFile) && fs.readFileSync(targetFile, 'utf8').includes(MARKER)) {
-    return;
-  }
+  assertHarnessOwnedOrAbsent(targetFile, label);
+  if (fs.existsSync(targetFile) && hasHarnessMarker(fs.readFileSync(targetFile, 'utf8'))) return;
   const content = [
     `---`,
     `name: Harness OS Guidance`,
@@ -108,7 +112,7 @@ function removeContinueRule(targetFile) {
   if (!fs.existsSync(targetFile)) return;
   try {
     const content = fs.readFileSync(targetFile, 'utf8');
-    if (content.includes(MARKER)) {
+    if (hasHarnessMarker(content)) {
       fs.unlinkSync(targetFile);
       console.log(`  ✅ Removed Harness rule file: ${targetFile}`);
     }
@@ -138,6 +142,7 @@ function buildCodexGlobalContent() {
     `---`,
     `# AGENTS.md`,
     ``,
+    `# ${MARKER}`,
     `This file is advisory only - this platform has no hook/execution mechanism to`,
     `enforce it mechanically (unlike Claude Code's hook-based circuit breaker). Treat`,
     `these as strong defaults, not guarantees.`,
@@ -158,10 +163,12 @@ function buildCodexGlobalContent() {
 module.exports = {
   MARKER,
   advisoryInstructions,
+  hasHarnessMarker,
+  assertHarnessOwnedOrAbsent,
   injectAdvisoryText,
   removeAdvisoryText,
   installContinueRule,
   removeContinueRule,
   buildCopilotGlobalContent,
   buildCodexGlobalContent,
-};
+};

package/scripts/lib/execution-contract.js

@@ -0,0 +1,70 @@
+const path = require('path');
+
+function normalizeCommand(command) {
+  if (Array.isArray(command)) {
+    return command.map((part) => String(part));
+  }
+  if (typeof command !== 'string') return null;
+  return command.trim().replace(/\s+/g, ' ');
+}
+
+function commandsEqual(actual, expected) {
+  const left = normalizeCommand(actual);
+  const right = normalizeCommand(expected);
+  if (Array.isArray(left) || Array.isArray(right)) {
+    return Array.isArray(left) && Array.isArray(right) &&
+      left.length === right.length && left.every((part, index) => part === right[index]);
+  }
+  return left !== null && left === right;
+}
+
+function commandTokens(command) {
+  if (typeof command !== 'string') return [];
+  return command.match(/"[^"]*"|'[^']*'|\S+/g) || [];
+}
+
+function commandMatches(actual, expected) {
+  if (commandsEqual(actual, expected)) return true;
+  if (typeof actual !== 'string' || typeof expected !== 'string') return false;
+  const target = expected.trim();
+  if (!target || /\s/.test(target) || !/\.(?:c?js|mjs|py|sh|ps1|bat|cmd)$/i.test(target)) return false;
+  const expectedName = path.basename(target.replace(/\\/g, '/')).toLowerCase();
+  const tokens = commandTokens(actual).map((token) => token.replace(/^['"]|['"]$/g, ''));
+  if (tokens.length < 2) return false;
+  const launcher = path.basename(tokens[0].replace(/\\/g, '/')).toLowerCase();
+  if (!new Set(['node', 'node.exe', 'bun', 'bun.exe', 'deno', 'deno.exe', 'python', 'python.exe', 'python3', 'python3.exe', 'ruby', 'ruby.exe']).has(launcher)) return false;
+  return tokens.slice(1).some((token) => path.basename(token.replace(/\\/g, '/')).toLowerCase() === expectedName);
+}
+
+function normalizeRepoPath(value) {
+  if (typeof value !== 'string') return null;
+  const normalized = value.replace(/\\/g, '/').replace(/^\.\//, '');
+  const segments = normalized.split('/');
+  if (!normalized || normalized === '.' || path.posix.isAbsolute(normalized) || /^[A-Za-z]:\//.test(normalized) || segments.includes('..')) return null;
+  return normalized;
+}
+
+function extractPatchPaths(patchText) {
+  if (typeof patchText !== 'string') return [];
+  const paths = [];
+  const marker = /^\*\*\* (?:Update File|Add File|Delete File|Move to):\s*(.+?)\s*$/gm;
+  for (const match of patchText.matchAll(marker)) {
+    if (!paths.includes(match[1])) paths.push(match[1]);
+  }
+  return paths;
+}
+
+function patchPathsAuthorized(patchText, allowedPaths) {
+  const paths = extractPatchPaths(patchText).map(normalizeRepoPath);
+  const allowed = new Set(Array.from(allowedPaths || []).map(normalizeRepoPath));
+  return paths.length > 0 && paths.every((candidate) => candidate && allowed.has(candidate));
+}
+
+module.exports = {
+  commandMatches,
+  commandsEqual,
+  extractPatchPaths,
+  normalizeCommand,
+  normalizeRepoPath,
+  patchPathsAuthorized,
+};