@bonesofspring/ai-rules 0.2.25 → 0.2.27

package/bin/cli.js

@@ -2,10 +2,13 @@
 /**
  * @bonesofspring/ai-rules CLI
  */
+const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 const { cmdInitMavis, cmdCleanMavis } = require('./mavis-install');
 const { cmdInitOpencode, cmdCleanOpencode } = require('./opencode-install');
+const { seedAiLocalTeam } = require('./lib/seed-ai-local-team');
+const { assertSafeDest, resolveManagedPath } = require('./lib/safe-path');
 
 /** Single path segment: letters, digits, dot, underscore, hyphen; no separators or "..". */
 const PRESET_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
@@ -20,7 +23,7 @@ const PRESETS = {
     rulesDir: '.cursor/rules',
     commandsDir: '.cursor/commands',
     relBase: ['presets', 'cursor'],
-    optionalCursorDirs: ['agents', 'hooks', 'skills', 'team'],
+    optionalCursorDirs: ['agents', 'hooks', 'skills'],
     hooksJsonSrc: 'hooks.json',
     /** Project MCP → `.cursor/mcp.json` */
     mcpJsonSrc: 'mcp.json',
@@ -33,7 +36,7 @@ const PRESETS = {
     rulesDir: '.claude/rules',
     commandsDir: '.claude/commands',
     relBase: ['presets', 'claude'],
-    optionalClaudeDirs: ['skills', 'agents', 'hooks', 'team'],
+    optionalClaudeDirs: ['skills', 'agents', 'hooks'],
     claudeMdSrc: 'CLAUDE.md',
     /** Project MCP lives at repo root (Claude Code project scope), not under `.claude/`. */
     mcpJsonSrc: 'mcp.json',
@@ -69,8 +72,16 @@ Notes:
   (mcpServers is merged: extra local servers are kept; shipped keys update; nested env/headers
   on shipped keys are preserved unless the preset defines them. Invalid / non-object JSON is
   copied to a timestamped *.bak.* then replaced with the preset file. JSONC is not supported).
-  Cursor init copies rules, commands, agents, hooks, skills, team, hooks.json, BUGBOT.md, AGENTS.md → .cursor/AGENTS.md, MCP.md, mcp.json → .cursor/mcp.json.
-  Claude init copies rules, commands, skills, agents, hooks, team, CLAUDE.md, MCP.md, and mcp.json → .mcp.json (project root).
+  Cursor init copies rules, commands, agents, hooks, skills, hooks.json, BUGBOT.md, AGENTS.md → .cursor/AGENTS.md, MCP.md, mcp.json → .cursor/mcp.json.
+  Claude init copies rules, commands, skills, agents, hooks, CLAUDE.md, MCP.md, and mcp.json → .mcp.json (project root).
+  All init targets seed .ai.local/team/ (shared pipeline artifacts; never overwritten task slugs; not removed by clean)
+  and .ai.local/conventions.md (living gotchas; seeded from the preset template only when absent, never overwritten).
+  Because .ai.local/team/ is shared, ANY init consolidates every legacy .cursor|.claude|.mavis|.opencode/team/ into it,
+  not just the tool being installed. Consolidation is non-destructive: every non-README.md entry is migrated and copied
+  to a timestamped .ai.local/.rollback/legacy-team-<stamp>/ backup before it is removed, colliding task slugs are kept
+  side by side as <slug>__from-<tool>/, and symlinked legacy team dirs are skipped with a warning rather than followed.
+  The .rollback/ directory carries its own .gitignore so backups cannot be committed by accident; delete it once the
+  migration looks right. Your root .gitignore is never modified.
   Mavis init copies into .mavis/ (ai-rules-owned) plus REPO_AGENTS.md → <cwd>/AGENTS.md; MCP merges into .mavis/mcp.json only (never ~/.minimax/**).
   OpenCode init copies into .opencode/ plus REPO_AGENTS.md → <cwd>/AGENTS.md; MCP merges into <cwd>/opencode.json (never ~/.config/opencode/**).
   All init targets also copy REPO_AGENTS.md → <cwd>/AGENTS.md (repo-root cross-tool agents file; overwrite; all next platforms ship the same file).
@@ -102,8 +113,11 @@ Examples:
   npx @bonesofspring/ai-rules init claude --preset php-hexagonal
   npx @bonesofspring/ai-rules init claude --preset php-laravel
   npx @bonesofspring/ai-rules init mavis --preset next
+  npx @bonesofspring/ai-rules init mavis --preset nuxt
   npx @bonesofspring/ai-rules init opencode --preset next
+  npx @bonesofspring/ai-rules init opencode --preset go
   npx @bonesofspring/ai-rules init multi --preset next
+  npx @bonesofspring/ai-rules init multi --preset svelte
   npx @bonesofspring/ai-rules clean mavis
   npx @bonesofspring/ai-rules clean opencode
   npx @bonesofspring/ai-rules clean cursor
@@ -135,7 +149,7 @@ function parseArgs(argv) {
     }
     if (a === '--preset') {
       const value = argv[i + 1];
-      if (value === undefined || value.startsWith('-')) {
+      if (value === undefined || value === '' || value.startsWith('-')) {
         args.presetError =
           'Missing value for --preset (use --preset <name> or --preset=<name>)';
         continue;
@@ -157,6 +171,10 @@ function parseArgs(argv) {
       args.help = true;
       continue;
     }
+    if (a.startsWith('-') && a !== '-') {
+      args.unknownOption = a;
+      continue;
+    }
     args._.push(a);
   }
   return args;
@@ -190,6 +208,9 @@ function normalizeInitClean(parsed) {
     }
   }
 
+  if (command === 'init' && parsed.preset === undefined && positional[2] === '') {
+    parsed.presetError = 'Missing value for --preset (use --preset <name> or --preset=<name>)';
+  }
   const preset = parsed.preset || presetFromPositional;
   return { command, tool, preset };
 }
@@ -228,6 +249,14 @@ function ownKeys(object) {
   return Object.keys(object).filter((key) => Object.hasOwn(object, key));
 }
 
+/** Write via a temp file + rename so an interrupted write cannot corrupt the destination. */
+function writeFileAtomic(destAbs, content) {
+  fs.mkdirSync(path.dirname(destAbs), { recursive: true });
+  const tmp = `${destAbs}.ai-rules-tmp`;
+  fs.writeFileSync(tmp, content);
+  fs.renameSync(tmp, destAbs);
+}
+
 function backupMcpFile(mcpDestAbs) {
   const stamp = new Date().toISOString().replace(/[:.]/g, '-');
   const bak = `${mcpDestAbs}.bak.${stamp}`;
@@ -237,7 +266,9 @@ function backupMcpFile(mcpDestAbs) {
 
 function replaceMcpWithPreset(mcpFrom, mcpDestAbs, reason) {
   const bak = backupMcpFile(mcpDestAbs);
-  fs.copyFileSync(mcpFrom, mcpDestAbs);
+  const tmp = `${mcpDestAbs}.ai-rules-tmp`;
+  fs.copyFileSync(mcpFrom, tmp);
+  fs.renameSync(tmp, mcpDestAbs);
   console.warn(`${reason}; backed up to ${bak} and replaced with the preset file.`);
 }
 
@@ -315,8 +346,7 @@ function installMcpJson(mcpFrom, mcpDestAbs, destLabel) {
       `Existing ${destLabel} mcpServers was not a JSON object; backed up to ${bak} and merging as empty extras.`,
     );
   }
-  fs.mkdirSync(path.dirname(mcpDestAbs), { recursive: true });
-  fs.writeFileSync(mcpDestAbs, `${JSON.stringify(merged, null, 2)}\n`);
+  writeFileAtomic(mcpDestAbs, `${JSON.stringify(merged, null, 2)}\n`);
   if (extrasKept.length > 0) {
     console.log(
       `Merged ${path.basename(mcpFrom)} → ${destLabel} (kept extra servers: ${extrasKept.join(', ')})`,
@@ -356,6 +386,7 @@ function seedDocsSpecsIfAbsent(packageRoot, cwd) {
     console.log('Skipped docs/specs seed (directory already exists)');
     return false;
   }
+  assertSafeDest(cwd, destRoot, 'docs/specs');
   const assetsRoot = path.join(
     packageRoot,
     'presets',
@@ -384,15 +415,90 @@ function getOptionalDirs(cfg) {
   return cfg.optionalCursorDirs || cfg.optionalClaudeDirs || [];
 }
 
-function removeDirIfExists(dir) {
-  if (fs.existsSync(dir)) {
-    fs.rmSync(dir, { recursive: true, force: true });
+function sha256File(filePath) {
+  return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+
+/** Relative (forward-slash) file paths under a directory, sorted. */
+function walkFilesUnder(root) {
+  const out = [];
+  const visit = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        visit(full);
+      } else if (entry.isFile()) {
+        out.push(path.relative(root, full).split(path.sep).join('/'));
+      }
+    }
+  };
+  if (fs.existsSync(root)) {
+    visit(root);
+  }
+  return out.sort();
+}
+
+function getPackageVersion(packageRoot) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version;
+  } catch {
+    return '0.0.0';
+  }
+}
+
+/** Remove empty directories bottom-up without ever traversing a symlink. */
+function removeEmptyDirsSafe(dir) {
+  if (!dir || !fs.existsSync(dir)) {
+    return;
+  }
+  let stat;
+  try {
+    stat = fs.lstatSync(dir);
+  } catch {
+    return;
+  }
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    return;
+  }
+  for (const name of fs.readdirSync(dir)) {
+    removeEmptyDirsSafe(path.join(dir, name));
+  }
+  if (fs.readdirSync(dir).length === 0) {
+    fs.rmdirSync(dir);
+  }
+}
+
+/** Remove only the preset-shipped keys from an MCP config, keeping consumer extras. */
+function stripShippedMcpKeys(mcpAbs, shippedIds, rootKey) {
+  if (!fs.existsSync(mcpAbs) || shippedIds.length === 0) {
+    return;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(mcpAbs, 'utf8'));
+  } catch {
+    return;
+  }
+  if (!isPlainObject(parsed) || !isPlainObject(parsed[rootKey])) {
+    return;
   }
+  const next = { ...parsed[rootKey] };
+  for (const id of shippedIds) {
+    delete next[id];
+  }
+  writeFileAtomic(mcpAbs, `${JSON.stringify({ ...parsed, [rootKey]: next }, null, 2)}\n`);
 }
 
-function removeFileIfExists(filePath) {
-  if (fs.existsSync(filePath)) {
-    fs.unlinkSync(filePath);
+function readInstallManifest(cwd, toolRoot) {
+  const manifestAbs = resolveManagedPath(cwd, `${toolRoot}/.ai-rules-install.json`);
+  if (!manifestAbs || !fs.existsSync(manifestAbs)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(manifestAbs, 'utf8'));
+    return isPlainObject(parsed) && isPlainObject(parsed.managedFiles) ? parsed : null;
+  } catch {
+    return null;
   }
 }
 
@@ -568,6 +674,7 @@ function cmdInit(tool, preset, cwdOption) {
       helpers: {
         resolveTargetCwd,
         seedDocsSpecsIfAbsent,
+        seedAiLocalTeam,
         installMcpJson,
         getPackageRoot,
       },
@@ -581,6 +688,7 @@ function cmdInit(tool, preset, cwdOption) {
       helpers: {
         resolveTargetCwd,
         seedDocsSpecsIfAbsent,
+        seedAiLocalTeam,
         getPackageRoot,
       },
     });
@@ -601,19 +709,27 @@ function cmdInit(tool, preset, cwdOption) {
   const toolRoot = tool === 'cursor' ? '.cursor' : '.claude';
   const toolRootAbs = path.join(cwd, toolRoot);
 
+  // Capture existence BEFORE mkdir: rollback must only remove the tool root when
+  // this run created it, never a pre-existing consumer directory.
+  const toolRootExisted = fs.existsSync(toolRootAbs);
+  try {
+    assertSafeDest(cwd, toolRootAbs, toolRoot);
+  } catch (err) {
+    console.error(`init failed: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
   fs.mkdirSync(toolRootAbs, { recursive: true });
 
   let copiedSteps = 0;
-  // Track newly created paths so we can roll back on partial failure.
-  // Only deletes paths that did not exist before this run — never consumer files.
-  const toolRootExisted = fs.existsSync(toolRootAbs);
+  // Track paths that did not exist before this run so we can roll them back on
+  // partial failure. Directories are tracked before the copy so a mid-copy failure
+  // still removes the (newly created) directory and its partial contents.
   const createdPaths = new Set();
   const docsSpecsDir = path.join(cwd, 'docs', 'specs');
   const docsSpecsExisted = fs.existsSync(docsSpecsDir);
 
   const trackDir = (dir) => {
-    if (!fs.existsSync(dir)) return;
-    createdPaths.add(dir);
+    if (!fs.existsSync(dir)) createdPaths.add(dir);
   };
 
   try {
@@ -711,6 +827,94 @@ function cmdInit(tool, preset, cwdOption) {
       }
       copiedSteps++;
     }
+
+    const teamSrc = path.join(base, 'team');
+    const teamDest = path.join(cwd, '.ai.local', 'team');
+    const teamExisted = fs.existsSync(teamDest);
+    const teamResult = seedAiLocalTeam({ cwd, presetTeamSrc: teamSrc });
+    if (teamResult.created && !teamExisted) {
+      createdPaths.add(teamDest);
+    }
+    if (teamResult.created || teamResult.migrated || teamResult.refreshed) {
+      copiedSteps++;
+    }
+
+    // Write the ownership manifest so `clean` only ever deletes files this tool
+    // installed and left unchanged. Without it, clean is fail-safe (no deletions).
+    const prior = readInstallManifest(cwd, toolRoot);
+    const manifestRel = `${toolRoot}/.ai-rules-install.json`;
+    const manifestAbs = path.join(cwd, manifestRel);
+    const managedFiles = {};
+    for (const rel of walkFilesUnder(toolRootAbs)) {
+      const relFromCwd = `${toolRoot}/${rel}`;
+      if (relFromCwd === manifestRel) {
+        continue;
+      }
+      managedFiles[relFromCwd] = sha256File(path.join(toolRootAbs, rel));
+    }
+    if (cfg.mcpJsonDest) {
+      const mcpAbs = path.join(cwd, cfg.mcpJsonDest);
+      if (fs.existsSync(mcpAbs)) {
+        managedFiles[cfg.mcpJsonDest] = sha256File(mcpAbs);
+      }
+    }
+    for (const destRel of Object.values(cfg.repoRootFiles || {})) {
+      const abs = path.join(cwd, destRel);
+      if (fs.existsSync(abs)) {
+        managedFiles[destRel] = sha256File(abs);
+      }
+    }
+
+    // Prune files owned by a previous install that the preset no longer ships.
+    // Only unchanged, tool-root files are removed; shared AGENTS.md is left alone.
+    if (prior) {
+      for (const [rel, priorHash] of Object.entries(prior.managedFiles)) {
+        if (rel in managedFiles || !rel.startsWith(`${toolRoot}/`)) {
+          continue;
+        }
+        const abs = resolveManagedPath(cwd, rel);
+        if (!abs || !fs.existsSync(abs) || !fs.lstatSync(abs).isFile()) {
+          continue;
+        }
+        if (sha256File(abs) === priorHash) {
+          fs.unlinkSync(abs);
+          console.log(`Pruned stale managed file ${rel}`);
+        }
+      }
+    }
+
+    let shippedMcpServerIds = [];
+    if (cfg.mcpJsonSrc) {
+      const mcpFrom = path.join(base, cfg.mcpJsonSrc);
+      if (fs.existsSync(mcpFrom)) {
+        try {
+          const parsed = JSON.parse(fs.readFileSync(mcpFrom, 'utf8'));
+          if (isPlainObject(parsed.mcpServers)) {
+            shippedMcpServerIds = ownKeys(parsed.mcpServers);
+          }
+        } catch {
+          shippedMcpServerIds = [];
+        }
+      }
+    }
+    const managedDirectories = [cfg.rulesDir, cfg.commandsDir];
+    for (const name of getOptionalDirs(cfg)) {
+      managedDirectories.push(`${toolRoot}/${name}`);
+    }
+    const manifest = {
+      schemaVersion: 1,
+      packageVersion: getPackageVersion(packageRoot),
+      platform: tool,
+      preset: presetName,
+      installedAt: new Date().toISOString(),
+      managedFiles,
+      managedDirectories,
+      shippedMcpServerIds,
+    };
+    if (!fs.existsSync(manifestAbs)) {
+      createdPaths.add(manifestAbs);
+    }
+    writeFileAtomic(manifestAbs, `${JSON.stringify(manifest, null, 2)}\n`);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     rollbackInit(createdPaths, toolRootExisted, toolRootAbs);
@@ -788,47 +992,82 @@ function cmdClean(tool, cwdOption) {
   }
   const cwd = resolveTargetCwd(cwdOption);
   const toolRoot = tool === 'cursor' ? '.cursor' : '.claude';
-  const removedParts = [cfg.rulesDir, cfg.commandsDir];
-
-  removeDirIfExists(path.join(cwd, cfg.rulesDir));
-  removeDirIfExists(path.join(cwd, cfg.commandsDir));
-
-  const optionalDirs = getOptionalDirs(cfg);
-  for (const name of optionalDirs) {
-    removeDirIfExists(path.join(cwd, toolRoot, name));
-    removedParts.push(`${toolRoot}/${name}`);
+  const manifestRel = `${toolRoot}/.ai-rules-install.json`;
+  const manifestAbs = resolveManagedPath(cwd, manifestRel);
+  if (!manifestAbs || !fs.existsSync(manifestAbs)) {
+    console.error(`clean ${tool}: missing ${manifestRel}; nothing removed (fail-safe).`);
+    process.exit(1);
   }
-
-  if (cfg.claudeMdSrc) {
-    removeFileIfExists(path.join(cwd, toolRoot, 'CLAUDE.md'));
-    removedParts.push(`${toolRoot}/CLAUDE.md`);
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestAbs, 'utf8'));
+  } catch {
+    console.error(`clean ${tool}: invalid ${manifestRel}; nothing removed (fail-safe).`);
+    process.exit(1);
+  }
+  if (!isPlainObject(manifest) || manifest.platform !== tool || !isPlainObject(manifest.managedFiles)) {
+    console.error(`clean ${tool}: install manifest is not a ${tool} ownership record; nothing removed.`);
+    process.exit(1);
   }
 
-  if (cfg.hooksJsonSrc) {
-    removeFileIfExists(path.join(cwd, toolRoot, 'hooks.json'));
-    removedParts.push(`${toolRoot}/hooks.json`);
+  const preserved = [];
+  for (const [rel, installedHash] of Object.entries(manifest.managedFiles)) {
+    if (rel === manifestRel) {
+      continue;
+    }
+    // Never delete outside the target or through a symlink, even if the manifest says so.
+    const abs = resolveManagedPath(cwd, rel);
+    if (!abs) {
+      console.warn(`Ignored unsafe manifest entry ${rel} (outside target or symlinked)`);
+      continue;
+    }
+    if (!fs.existsSync(abs)) {
+      continue;
+    }
+    if (!fs.lstatSync(abs).isFile()) {
+      console.warn(`Ignored non-file manifest entry ${rel}`);
+      continue;
+    }
+    if (rel === 'AGENTS.md' && otherToolInstallPresent(cwd, toolRoot)) {
+      console.log('Kept shared AGENTS.md (another tool install is still present)');
+      continue;
+    }
+    if (sha256File(abs) === installedHash) {
+      fs.unlinkSync(abs);
+    } else {
+      preserved.push(rel);
+      console.warn(`Preserved modified managed file ${rel}`);
+    }
   }
 
-  if (cfg.mcpJsonDest) {
-    removeFileIfExists(path.join(cwd, cfg.mcpJsonDest));
-    removedParts.push(cfg.mcpJsonDest);
+  if (cfg.mcpJsonDest && preserved.includes(cfg.mcpJsonDest) && Array.isArray(manifest.shippedMcpServerIds)) {
+    const mcpAbs = resolveManagedPath(cwd, cfg.mcpJsonDest);
+    if (mcpAbs) {
+      stripShippedMcpKeys(mcpAbs, manifest.shippedMcpServerIds, 'mcpServers');
+    }
   }
 
-  for (const name of cfg.toolRootFiles || []) {
-    removeFileIfExists(path.join(cwd, toolRoot, name));
-    removedParts.push(`${toolRoot}/${name}`);
+  for (const dirRel of [...(manifest.managedDirectories || [])].sort((a, b) => b.length - a.length)) {
+    const dirAbs = resolveManagedPath(cwd, dirRel);
+    if (dirAbs) {
+      removeEmptyDirsSafe(dirAbs);
+    }
   }
 
-  for (const destRel of Object.values(cfg.repoRootFiles || {})) {
-    if (destRel === 'AGENTS.md' && otherToolInstallPresent(cwd, toolRoot)) {
-      console.log('Kept shared AGENTS.md (another tool install is still present)');
-      continue;
+  fs.unlinkSync(manifestAbs);
+  const toolRootAbs = resolveManagedPath(cwd, toolRoot);
+  if (toolRootAbs) {
+    removeEmptyDirsSafe(toolRootAbs);
+    if (fs.existsSync(toolRootAbs) && fs.readdirSync(toolRootAbs).length === 0) {
+      fs.rmdirSync(toolRootAbs);
     }
-    removeFileIfExists(path.join(cwd, destRel));
-    removedParts.push(destRel);
   }
 
-  console.log(`Removed ${removedParts.join(', ')} (if present)`);
+  console.log(
+    preserved.length > 0
+      ? `clean ${tool}: removed unchanged managed files; preserved ${preserved.join(', ')}`
+      : `clean ${tool}: removed unchanged managed files`,
+  );
 }
 
 function main() {
@@ -844,6 +1083,10 @@ function main() {
     process.exit(0);
   }
 
+  if (parsed.unknownOption) {
+    console.error(`Unknown option: ${parsed.unknownOption}`);
+    process.exit(1);
+  }
   if (parsed.presetError) {
     console.error(parsed.presetError);
     process.exit(1);

package/bin/lib/safe-path.js

@@ -0,0 +1,93 @@
+/**
+ * Path-safety helpers shared by the installers.
+ *
+ * Two threats are handled:
+ *   1. A destination path (from the CLI, the platform contract, or an install
+ *      manifest) escaping the resolved `--cwd` via `..` or an absolute path.
+ *   2. A destination path traversing a symlinked component, which would make a
+ *      write or `rmSync` operate outside the install scope.
+ */
+const fs = require('fs');
+const path = require('path');
+
+function lstatOrNull(target) {
+  try {
+    return fs.lstatSync(target);
+  } catch {
+    return null;
+  }
+}
+
+/** True when `target` is itself a symlink (dangling links included). */
+function isSymlink(target) {
+  const stat = lstatOrNull(target);
+  return Boolean(stat && stat.isSymbolicLink());
+}
+
+/**
+ * Resolve `target` under `cwd` and refuse it when it escapes or traverses an
+ * existing symlink. Missing components are allowed: the caller creates them.
+ *
+ * @param {string} cwd  Target project directory (already resolved).
+ * @param {string} target  Absolute or relative destination path.
+ * @param {string} label  Human-readable name used in error messages.
+ * @returns {string} The resolved absolute path.
+ */
+function assertSafeDest(cwd, target, label) {
+  const root = path.resolve(cwd);
+  const resolved = path.resolve(root, target);
+  const rel = path.relative(root, resolved);
+  if (rel === '') {
+    return resolved;
+  }
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error(`${label} escapes the target directory: ${resolved}`);
+  }
+  let current = root;
+  for (const part of rel.split(path.sep)) {
+    current = path.join(current, part);
+    if (isSymlink(current)) {
+      throw new Error(`${label} is a symlink; refusing to write through it: ${current}`);
+    }
+    if (!fs.existsSync(current)) {
+      break;
+    }
+  }
+  return resolved;
+}
+
+/** `mkdir -p` after {@link assertSafeDest}. */
+function safeMkdir(cwd, dir, label) {
+  assertSafeDest(cwd, dir, label);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Resolve a manifest entry (relative path) under `cwd`. Returns `null` when the
+ * entry is absolute, escapes `cwd`, is empty, or traverses a symlink.
+ */
+function resolveManagedPath(cwd, rel) {
+  if (typeof rel !== 'string' || rel === '' || path.isAbsolute(rel)) {
+    return null;
+  }
+  const root = path.resolve(cwd);
+  const resolved = path.resolve(root, rel);
+  const relative = path.relative(root, resolved);
+  if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative)) {
+    return null;
+  }
+  let current = root;
+  for (const part of relative.split(path.sep)) {
+    current = path.join(current, part);
+    if (isSymlink(current)) {
+      return null;
+    }
+    if (!fs.existsSync(current)) {
+      break;
+    }
+  }
+  return resolved;
+}
+
+module.exports = { assertSafeDest, safeMkdir, resolveManagedPath, isSymlink, lstatOrNull };