@bonesofspring/ai-rules 0.2.26 → 0.2.28

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+### OpenCode re-init picks up preset rules; Claude ships `settings.json`
+
+- `init opencode` merges `opencode.json` by **unioning** preset `instructions` paths and **filling missing** `permission.bash` keys. Consumer extra paths and same-key overrides stay, including on re-init. An empty `instructions` array no longer blocks the preset list.
+- Claude presets now include `presets/claude/<stack>/settings.json` (harness `permissions.deny` / `ask`). `init claude` copies it to `.claude/settings.json` and overwrites that file on re-init.
+
+### Over-abstraction guardrails + aligned always-on budget
+
+- **Shared core** `quality/code-quality-and-refactoring` gains an **Over-abstraction guardrails** section: no unnecessary constants, no invented one-off utilities (Rule of Three), decompose over conditionals. Propagated to all 10 stacks (Cursor + Claude; Mavis / OpenCode regenerated).
+- **UI rules** add a **Conditional rendering** section (decompose branches into child components, early returns for loading/empty/error, no nested ternaries): `react-ui` (next, with Incorrect/Correct pair), `vue-ui` (nuxt), `svelte-ui` (svelte), `compose-ui` (android-kotlin), `swiftui-ui` (ios-swift). Backend stacks get the stack-agnostic bullet from shared core.
+- **Token budget raised and aligned** across platforms: Cursor / Claude / Mavis / OpenCode always-on count is now **3–5** (was Cursor ≤4, Claude exactly 3, Mavis/OpenCode ≤4); session-start body cap is **200** lines (stretch **170**) and combined Mavis/OpenCode entry cap is **200** nonempty lines (was 140/170). Enforced by `check-preset-token-budget.sh`, `check-{mavis,opencode}-token-budget.mjs`, `test-{mavis,opencode}-context-budget.mjs`; policy in `preset-token-budget` / `preset-pr-checklist`, `docs/PRESET-CONTRIBUTION.md`, and every `build-verifier` / `rules/README.md`.
+- Consumers: re-run `npx @bonesofspring/ai-rules init <tool|multi> --preset <stack>` to pick up the new rule bodies and policy text.
+
 ### Shared `.ai.local/team/` pipelines (breaking)
 
 - `/task` artifacts (`pipeline.json`, `status.json`, `metrics.json`, receipts) now live at **`.ai.local/team/tasks/<slug>/`**, shared across Cursor, Claude, Mavis, and OpenCode (including `init multi`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Volchenkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -46,7 +46,7 @@ npx @bonesofspring/ai-rules init multi --preset nuxt
 
 Help: `ai-rules --help`.
 
-Skills of note: `write-adr` (all); `spec-authoring` / `/spec-start`; `mockup-review` and `ux-design` on UI stacks; `react-performance` (next), `vue-performance` (nuxt), `svelte-performance` (svelte).
+Skills of note: `write-adr` (all except `mcp-ts`); `spec-authoring` / `/spec-start`; `mockup-review` and `ux-design` on UI stacks; `react-performance` (next), `vue-performance` (nuxt), `svelte-performance` (svelte).
 
 ## Product specs and OpenSpec
 

package/bin/cli.js

@@ -2,11 +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._-]*$/;
@@ -71,7 +73,7 @@ Notes:
   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, 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).
+  Claude init copies rules, commands, skills, agents, hooks, CLAUDE.md, settings.json (harness-level denials), 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,
@@ -147,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;
@@ -169,6 +171,10 @@ function parseArgs(argv) {
       args.help = true;
       continue;
     }
+    if (a.startsWith('-') && a !== '-') {
+      args.unknownOption = a;
+      continue;
+    }
     args._.push(a);
   }
   return args;
@@ -202,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 };
 }
@@ -240,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}`;
@@ -249,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.`);
 }
 
@@ -327,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(', ')})`,
@@ -368,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',
@@ -396,22 +415,97 @@ 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;
   }
 }
 
 /** Markers that mean a tool install is still present (directory leftovers do not count). */
 const TOOL_INSTALL_MARKERS = {
   '.cursor': ['.cursor/AGENTS.md', '.cursor/hooks.json', '.cursor/rules'],
-  '.claude': ['.claude/CLAUDE.md', '.claude/rules'],
+  '.claude': ['.claude/CLAUDE.md', '.claude/rules', '.claude/settings.json'],
   '.mavis': ['.mavis/.ai-rules-install.json', '.mavis/AGENTS.md'],
   '.opencode': ['.opencode/.ai-rules-install.json', '.opencode/AGENTS.md'],
 };
@@ -615,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 {
@@ -679,6 +781,17 @@ function cmdInit(tool, preset, cwdOption) {
       }
     }
 
+    if (tool === 'claude') {
+      const settingsFrom = path.join(base, 'settings.json');
+      if (fs.existsSync(settingsFrom)) {
+        const destAbs = path.join(toolRootAbs, 'settings.json');
+        fs.copyFileSync(settingsFrom, destAbs);
+        createdPaths.add(destAbs);
+        console.log(`Copied settings.json → ${toolRoot}/settings.json`);
+        copiedSteps++;
+      }
+    }
+
     if (cfg.mcpJsonSrc && cfg.mcpJsonDest) {
       const mcpFrom = path.join(base, cfg.mcpJsonSrc);
       if (fs.existsSync(mcpFrom)) {
@@ -736,6 +849,83 @@ function cmdInit(tool, preset, cwdOption) {
     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);
@@ -813,47 +1003,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() {
@@ -869,6 +1094,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 };