@bx-h/meta-flow 0.1.0

package/src/cli/commands/uninstall.js

@@ -0,0 +1,56 @@
+import { parseOptions, helpRequested } from "../lib/args.js";
+import { uninstallAgents } from "../lib/agents.js";
+import { createLogger } from "../lib/logger.js";
+import { uninstallMarketplace } from "../lib/marketplace.js";
+import { uninstallPlugin } from "../lib/plugin.js";
+import { resolveTargets } from "../lib/paths.js";
+
+export function uninstallHelp() {
+  return `Usage: meta-flow uninstall --scope repo|user [options]
+
+Options:
+  --target <path>   Target repo path for repo scope. Defaults to cwd.
+  --dry-run         Print planned removals without deleting files.
+  --yes             Confirm removal.
+  --keep-tasks      Keep .meta-flow/tasks. This is the default.
+  --verbose         Print detailed actions.`;
+}
+
+export async function runUninstall(argv = []) {
+  if (helpRequested(argv)) {
+    console.log(uninstallHelp());
+    return 0;
+  }
+  const { options } = parseOptions(argv, {
+    scope: "string",
+    target: "string"
+  });
+  const scope = options.scope || "repo";
+  const targets = resolveTargets({ scope, target: options.target });
+  const dryRun = Boolean(options.dryRun);
+  const logger = createLogger({ verbose: options.verbose });
+
+  console.log("Meta Flow uninstall plan:");
+  console.log(`- scope: ${targets.scope}`);
+  console.log(`- target: ${targets.target}`);
+  console.log(`- remove plugin: ${targets.pluginTarget}`);
+  console.log(`- update marketplace: ${targets.marketplaceTarget}`);
+  console.log(`- remove marked agents: ${targets.agentsTarget}`);
+  console.log(`- keep tasks: ${targets.tasksTarget}`);
+
+  if (!dryRun && !options.yes) {
+    throw new Error("Refusing to delete files without --yes. Re-run with --dry-run first or add --yes.");
+  }
+
+  const pluginResult = await uninstallPlugin(targets, { dryRun, logger });
+  if (pluginResult.skipped) {
+    logger.warn(`plugin target is not a confirmed meta-flow plugin; skipped: ${targets.pluginTarget}`);
+  }
+  await uninstallMarketplace(targets, { dryRun, logger });
+  const agentResult = await uninstallAgents(targets, { dryRun, logger });
+  for (const skipped of agentResult.skipped) {
+    logger.warn(`agent file has no meta-flow marker; skipped: ${skipped}`);
+  }
+  console.log("Uninstall complete. User task data was not deleted.");
+  return 0;
+}

package/src/cli/commands/verify.js

@@ -0,0 +1,197 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { installAgents, validateAgentTemplates } from "../lib/agents.js";
+import { runDoctor } from "./doctor.js";
+import { runInstall } from "./install.js";
+import { runUninstall } from "./uninstall.js";
+import { validatePlugin } from "../lib/plugin.js";
+import { packageRoot, pluginSource, sampleTaskRoot } from "../lib/paths.js";
+
+export async function runVerify(argv = []) {
+  const lintOnly = argv.includes("--lint-only");
+  const checks = [];
+  checks.push(await checkPackageJson());
+  checks.push(await checkNoForbiddenSourcePatterns());
+  if (lintOnly) {
+    report(checks);
+    return checks.some((check) => check.level === "FAIL") ? 1 : 0;
+  }
+  checks.push(await checkPlugin());
+  checks.push(await checkAgents());
+  checks.push(await checkPythonHelp());
+  checks.push(await checkSampleTask());
+  checks.push(await checkDryRun());
+  checks.push(await checkInstallUninstallSimulation());
+  report(checks);
+  return checks.some((check) => check.level === "FAIL") ? 1 : 0;
+}
+
+async function checkPackageJson() {
+  const packageJson = JSON.parse(await fs.readFile(path.join(packageRoot, "package.json"), "utf8"));
+  const errors = [];
+  if (packageJson.name !== "@bx-h/meta-flow") errors.push("unexpected package name");
+  if (packageJson.scripts?.postinstall) errors.push("postinstall must not exist");
+  if (packageJson.bin?.["meta-flow"] !== "bin/meta-flow.js") errors.push("bin meta-flow is invalid");
+  if (packageJson.type !== "module") errors.push("type must be module");
+  return result("package.json", errors);
+}
+
+async function checkNoForbiddenSourcePatterns() {
+  const files = await collectJsFiles(path.join(packageRoot, "src"));
+  files.push(path.join(packageRoot, "bin", "meta-flow.js"));
+  const errors = [];
+  for (const filePath of files) {
+    const text = await fs.readFile(filePath, "utf8");
+    if (/\beval\s*\(/.test(text)) errors.push(`dynamic eval found in ${filePath}`);
+    if (/https?:\/\/.+exec/i.test(text)) errors.push(`suspicious remote execution pattern in ${filePath}`);
+  }
+  return result("no eval or remote execution patterns", errors);
+}
+
+async function checkPlugin() {
+  const plugin = await validatePlugin();
+  return result("plugin manifest and skill", plugin.errors);
+}
+
+async function checkAgents() {
+  const results = await validateAgentTemplates();
+  const errors = results
+    .filter((item) => item.missing.length)
+    .map((item) => `${path.basename(item.filePath)} missing ${item.missing.join(", ")}`);
+  return result("agent TOML required fields", errors);
+}
+
+async function checkPythonHelp() {
+  const scripts = [
+    "new_task.py",
+    "validate_goal_contract.py",
+    "aggregate_reviews.py",
+    "validate_adjudication.py",
+    "validate_milestone_plan.py",
+    "validate_task_list.py",
+    "validate_task_verification.py",
+    "status.py"
+  ];
+  const python = resolvePython();
+  const errors = [];
+  for (const script of scripts) {
+    const run = spawnSync(python, [path.join(pluginSource, "scripts", script), "--help"], pythonOptions());
+    if (run.status !== 0) {
+      errors.push(`${script} --help failed: ${run.stderr || run.stdout}`);
+    }
+  }
+  return result("Python script --help", errors);
+}
+
+async function checkSampleTask() {
+  const python = resolvePython();
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "meta-flow-verify-"));
+  const runs = [
+    [path.join(pluginSource, "scripts", "validate_goal_contract.py"), path.join(sampleTaskRoot, "goal-contract.json")],
+    [
+      path.join(pluginSource, "scripts", "aggregate_reviews.py"),
+      "--reviews-dir",
+      path.join(sampleTaskRoot, "reviews"),
+      "--output",
+      path.join(tmp, "review-aggregate.json"),
+      "--task-id",
+      "sample-health-check"
+    ],
+    [path.join(pluginSource, "scripts", "validate_adjudication.py"), path.join(sampleTaskRoot, "adjudication-report.json")],
+    [path.join(pluginSource, "scripts", "validate_milestone_plan.py"), path.join(sampleTaskRoot, "milestone-plan.json")],
+    [path.join(pluginSource, "scripts", "validate_task_list.py"), path.join(sampleTaskRoot, "milestones", "M1", "task-list.json")],
+    [
+      path.join(pluginSource, "scripts", "validate_task_verification.py"),
+      path.join(sampleTaskRoot, "milestones", "M1", "tasks", "T1", "verification-report.json")
+    ]
+  ];
+  const errors = [];
+  for (const args of runs) {
+    const run = spawnSync(python, args, pythonOptions());
+    if (run.status !== 0) {
+      errors.push(`${path.basename(args[0])} failed: ${run.stderr || run.stdout}`);
+    }
+  }
+  return result("sample-task validation", errors);
+}
+
+async function checkDryRun() {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "meta-flow-dry-run-"));
+  await runInstall(["--scope", "repo", "--target", tmp, "--dry-run"]);
+  const entries = await fs.readdir(tmp);
+  return result("install --dry-run does not write", entries.length ? [`dry-run wrote files: ${entries.join(", ")}`] : []);
+}
+
+async function checkInstallUninstallSimulation() {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "meta-flow-install-"));
+  const errors = [];
+  const installCode = await runInstall(["--scope", "repo", "--target", tmp, "--yes"]);
+  if (installCode !== 0) errors.push("install returned non-zero");
+  const secondInstallCode = await runInstall(["--scope", "repo", "--target", tmp, "--yes"]);
+  if (secondInstallCode !== 0) errors.push("second install returned non-zero");
+  const marketplace = JSON.parse(await fs.readFile(path.join(tmp, ".agents", "plugins", "marketplace.json"), "utf8"));
+  const entries = marketplace.plugins.filter((plugin) => plugin.name === "meta-flow");
+  if (entries.length !== 1) errors.push(`marketplace has ${entries.length} meta-flow entries`);
+  const doctorCode = await runDoctor(["--scope", "repo", "--target", tmp]);
+  if (doctorCode !== 0) errors.push("doctor returned non-zero after install");
+  const uninstallCode = await runUninstall(["--scope", "repo", "--target", tmp, "--yes"]);
+  if (uninstallCode !== 0) errors.push("uninstall returned non-zero");
+  return result("repo install/doctor/uninstall simulation", errors);
+}
+
+async function collectJsFiles(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await collectJsFiles(full));
+    } else if (entry.isFile() && entry.name.endsWith(".js")) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+function resolvePython() {
+  const python3 = spawnSync("python3", ["--version"], pythonOptions());
+  return python3.status === 0 ? "python3" : "python";
+}
+
+function pythonOptions() {
+  return {
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      PYTHONDONTWRITEBYTECODE: "1"
+    }
+  };
+}
+
+function result(title, errors) {
+  return errors.length ? { level: "FAIL", title, errors } : { level: "PASS", title, errors: [] };
+}
+
+function report(checks) {
+  for (const check of checks) {
+    if (check.level === "PASS") {
+      console.log(`PASS: ${check.title}`);
+    } else {
+      console.error(`FAIL: ${check.title}`);
+      for (const error of check.errors) console.error(`  - ${error}`);
+    }
+  }
+}
+
+const thisFile = fileURLToPath(import.meta.url);
+if (process.argv[1] === thisFile) {
+  runVerify(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+  }).catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/src/cli/index.js

@@ -0,0 +1,53 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { runDoctor, doctorHelp } from "./commands/doctor.js";
+import { runInstall, installHelp } from "./commands/install.js";
+import { runPrintPaths, printPathsHelp } from "./commands/print_paths.js";
+import { runUninstall, uninstallHelp } from "./commands/uninstall.js";
+import { runVerify } from "./commands/verify.js";
+import { packageRoot } from "./lib/paths.js";
+
+const COMMANDS = {
+  install: { run: runInstall, help: installHelp },
+  uninstall: { run: runUninstall, help: uninstallHelp },
+  doctor: { run: runDoctor, help: doctorHelp },
+  verify: { run: runVerify, help: () => "Usage: meta-flow verify" },
+  "print-paths": { run: runPrintPaths, help: printPathsHelp }
+};
+
+export async function main(argv = []) {
+  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+    printHelp();
+    return 0;
+  }
+  if (argv.includes("--version")) {
+    const packageJson = JSON.parse(await fs.readFile(path.join(packageRoot, "package.json"), "utf8"));
+    console.log(packageJson.version);
+    return 0;
+  }
+  const [command, ...rest] = argv;
+  const entry = COMMANDS[command];
+  if (!entry) {
+    throw new Error(`Unknown command: ${command}\n\n${topHelp()}`);
+  }
+  return entry.run(rest);
+}
+
+function printHelp() {
+  console.log(topHelp());
+}
+
+function topHelp() {
+  return `Usage: meta-flow <command> [options]
+
+Commands:
+  install       Install plugin, agents, marketplace entry, and config.
+  uninstall     Remove managed plugin and marked agents.
+  doctor        Check installed state.
+  verify        Verify package structure and installer behavior.
+  print-paths   Print repo/user scope target paths.
+
+Global:
+  --help        Show help.
+  --version     Show package version.`;
+}

package/src/cli/lib/agents.js

@@ -0,0 +1,89 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  AGENT_HEADER,
+  backupIfExists,
+  hasMetaFlowMarker,
+  pathExists,
+  removeFileSafe,
+  writeTextSafe
+} from "./fs_safe.js";
+import { agentTemplatesSource } from "./paths.js";
+
+export const AGENT_FILES = [
+  "questioner.toml",
+  "researcher-proposer.toml",
+  "product-reviewer.toml",
+  "technical-reviewer.toml",
+  "risk-reviewer.toml",
+  "verification-reviewer.toml",
+  "adjudicator.toml",
+  "proposal-summarizer.toml",
+  "planner.toml",
+  "direction-evaluator.toml",
+  "task-decomposer.toml",
+  "executor.toml",
+  "result-verifier.toml",
+  "final-summarizer.toml"
+];
+
+export async function installAgents(targets, options = {}) {
+  const { dryRun = false, force = false, logger } = options;
+  const installed = [];
+  const conflicts = [];
+
+  for (const fileName of AGENT_FILES) {
+    const source = path.join(agentTemplatesSource, fileName);
+    const target = path.join(targets.agentsTarget, fileName);
+    const sourceText = await fs.readFile(source, "utf8");
+    const targetExists = await pathExists(target);
+    if (targetExists && !(await hasMetaFlowMarker(target))) {
+      if (!force) {
+        conflicts.push(target);
+        continue;
+      }
+      await backupIfExists(target, { dryRun, logger });
+    }
+    await writeTextSafe(target, `${AGENT_HEADER}${sourceText.replace(/^# Installed by meta-flow\.[\s\S]*?developer_instructions/m, "developer_instructions")}`, { dryRun, logger });
+    installed.push(target);
+  }
+
+  return { installed, conflicts };
+}
+
+export async function uninstallAgents(targets, options = {}) {
+  const removed = [];
+  const skipped = [];
+  for (const fileName of AGENT_FILES) {
+    const target = path.join(targets.agentsTarget, fileName);
+    if (!(await pathExists(target))) {
+      continue;
+    }
+    if (!(await hasMetaFlowMarker(target))) {
+      skipped.push(target);
+      continue;
+    }
+    await removeFileSafe(targets.agentsTarget, target, options);
+    removed.push(target);
+  }
+  return { removed, skipped };
+}
+
+export async function validateAgentTemplate(filePath) {
+  const text = await fs.readFile(filePath, "utf8");
+  const missing = [];
+  for (const key of ["name", "description", "developer_instructions"]) {
+    if (!new RegExp(`^\\s*${key}\\s*=`, "m").test(text)) {
+      missing.push(key);
+    }
+  }
+  return { filePath, missing };
+}
+
+export async function validateAgentTemplates(root = agentTemplatesSource) {
+  const results = [];
+  for (const fileName of AGENT_FILES) {
+    results.push(await validateAgentTemplate(path.join(root, fileName)));
+  }
+  return results;
+}

package/src/cli/lib/args.js

@@ -0,0 +1,49 @@
+export function parseOptions(argv, schema = {}) {
+  const options = {};
+  const rest = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) {
+      rest.push(token);
+      continue;
+    }
+    if (token === "--") {
+      rest.push(...argv.slice(index + 1));
+      break;
+    }
+
+    const [rawName, inlineValue] = token.slice(2).split("=", 2);
+    const negated = rawName.startsWith("no-");
+    const name = toCamel(negated ? rawName.slice(3) : rawName);
+    const kind = schema[name] || "boolean";
+
+    if (negated) {
+      options[name] = false;
+      continue;
+    }
+    if (kind === "boolean") {
+      options[name] = inlineValue === undefined ? true : inlineValue !== "false";
+      continue;
+    }
+    if (inlineValue !== undefined) {
+      options[name] = inlineValue;
+      continue;
+    }
+    if (index + 1 >= argv.length) {
+      throw new Error(`Missing value for --${rawName}`);
+    }
+    options[name] = argv[index + 1];
+    index += 1;
+  }
+
+  return { options, rest };
+}
+
+export function toCamel(value) {
+  return value.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
+export function helpRequested(argv) {
+  return argv.includes("--help") || argv.includes("-h");
+}

package/src/cli/lib/codex_config.js

@@ -0,0 +1,106 @@
+import fs from "node:fs/promises";
+import { backupIfExists, pathExists, writeTextSafe } from "./fs_safe.js";
+
+const DEFAULT_AGENTS_CONFIG = "[agents]\nmax_threads = 6\nmax_depth = 1\n";
+
+function sectionBounds(lines, sectionName) {
+  const header = `[${sectionName}]`;
+  const start = lines.findIndex((line) => line.trim() === header);
+  if (start < 0) {
+    return null;
+  }
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (/^\s*\[[^\]]+\]\s*$/.test(lines[index])) {
+      end = index;
+      break;
+    }
+  }
+  return { start, end };
+}
+
+function setOrInsert(lines, bounds, key, value) {
+  const pattern = new RegExp(`^\\s*${key}\\s*=`);
+  for (let index = bounds.start + 1; index < bounds.end; index += 1) {
+    if (pattern.test(lines[index])) {
+      lines[index] = `${key} = ${value}`;
+      return { changed: true, existed: true };
+    }
+  }
+  lines.splice(bounds.end, 0, `${key} = ${value}`);
+  bounds.end += 1;
+  return { changed: true, existed: false };
+}
+
+export async function patchCodexConfig(filePath, { force = false, dryRun = false, backup = false, logger } = {}) {
+  if (!(await pathExists(filePath))) {
+    await writeTextSafe(filePath, DEFAULT_AGENTS_CONFIG, { dryRun, logger });
+    return { changed: true, warnings: [] };
+  }
+
+  const content = await fs.readFile(filePath, "utf8");
+  const lines = content.split(/\r?\n/);
+  const warnings = [];
+  let changed = false;
+  let bounds = sectionBounds(lines, "agents");
+
+  if (!bounds) {
+    if (lines.at(-1) !== "") {
+      lines.push("");
+    }
+    lines.push("[agents]", "max_threads = 6", "max_depth = 1");
+    changed = true;
+  } else {
+    const section = lines.slice(bounds.start + 1, bounds.end).join("\n");
+    if (/^\s*max_threads\s*=/m.test(section)) {
+      if (force) {
+        setOrInsert(lines, bounds, "max_threads", "6");
+        changed = true;
+      } else {
+        warnings.push("config already contains [agents].max_threads; leaving it unchanged");
+      }
+    } else {
+      setOrInsert(lines, bounds, "max_threads", "6");
+      changed = true;
+    }
+
+    bounds = sectionBounds(lines, "agents");
+    const refreshed = lines.slice(bounds.start + 1, bounds.end).join("\n");
+    if (/^\s*max_depth\s*=/m.test(refreshed)) {
+      if (force) {
+        setOrInsert(lines, bounds, "max_depth", "1");
+        changed = true;
+      } else {
+        warnings.push("config already contains [agents].max_depth; leaving it unchanged");
+      }
+    } else {
+      setOrInsert(lines, bounds, "max_depth", "1");
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    if (force || backup) {
+      await backupIfExists(filePath, { dryRun, logger });
+    }
+    await writeTextSafe(filePath, `${lines.join("\n").replace(/\n*$/, "")}\n`, { dryRun, logger });
+  }
+
+  return { changed, warnings };
+}
+
+export async function inspectCodexConfig(filePath) {
+  if (!(await pathExists(filePath))) {
+    return { exists: false, hasAgents: false, hasMaxThreads: false, hasMaxDepth: false };
+  }
+  const content = await fs.readFile(filePath, "utf8");
+  const lines = content.split(/\r?\n/);
+  const bounds = sectionBounds(lines, "agents");
+  const section = bounds ? lines.slice(bounds.start + 1, bounds.end).join("\n") : "";
+  return {
+    exists: true,
+    hasAgents: Boolean(bounds),
+    hasMaxThreads: /^\s*max_threads\s*=/m.test(section),
+    hasMaxDepth: /^\s*max_depth\s*=/m.test(section)
+  };
+}

package/src/cli/lib/fs_safe.js

@@ -0,0 +1,142 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export const META_FLOW_MARKER = "# Installed by meta-flow.";
+export const AGENT_HEADER = `${META_FLOW_MARKER}
+# Source: https://github.com/bx-h/meta-flow
+# Do not edit unless you know what you are doing.
+`;
+
+export async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function ensureInside(parent, child) {
+  const resolvedParent = path.resolve(parent);
+  const resolvedChild = path.resolve(child);
+  const relative = path.relative(resolvedParent, resolvedChild);
+  if (relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))) {
+    return resolvedChild;
+  }
+  throw new Error(`Unsafe path outside ${resolvedParent}: ${resolvedChild}`);
+}
+
+export async function readJsonOrDefault(filePath, defaultValue) {
+  if (!(await pathExists(filePath))) {
+    return structuredClone(defaultValue);
+  }
+  try {
+    return JSON.parse(await fs.readFile(filePath, "utf8"));
+  } catch (error) {
+    throw new Error(`Invalid JSON at ${filePath}: ${error.message}`);
+  }
+}
+
+export async function writeJsonPretty(filePath, value, { dryRun = false, logger } = {}) {
+  if (dryRun) {
+    logger?.info(`DRY-RUN write JSON ${filePath}`);
+    return;
+  }
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+export function backupPath(filePath, timestamp = timestampForBackup()) {
+  return `${filePath}.bak.${timestamp}`;
+}
+
+export function timestampForBackup(date = new Date()) {
+  return date.toISOString().replace(/[-:]/g, "").replace(/\..+$/, "Z");
+}
+
+export async function backupIfExists(filePath, { dryRun = false, logger } = {}) {
+  if (!(await pathExists(filePath))) {
+    return null;
+  }
+  const backup = backupPath(filePath);
+  if (dryRun) {
+    logger?.info(`DRY-RUN backup ${filePath} -> ${backup}`);
+    return backup;
+  }
+  await copyPath(filePath, backup);
+  return backup;
+}
+
+export async function hasMetaFlowMarker(filePath) {
+  if (!(await pathExists(filePath))) {
+    return false;
+  }
+  const head = await fs.readFile(filePath, "utf8");
+  return head.slice(0, 512).includes(META_FLOW_MARKER);
+}
+
+export async function copyDirSafe(src, dest, { dryRun = false, logger } = {}) {
+  if (dryRun) {
+    logger?.info(`DRY-RUN copy directory ${src} -> ${dest}`);
+    return;
+  }
+  await fs.mkdir(dest, { recursive: true });
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDirSafe(from, to, { dryRun, logger });
+    } else if (entry.isFile()) {
+      await fs.mkdir(path.dirname(to), { recursive: true });
+      await fs.copyFile(from, to);
+    }
+  }
+}
+
+export async function copyPath(src, dest) {
+  const stat = await fs.stat(src);
+  if (stat.isDirectory()) {
+    await fs.mkdir(dest, { recursive: true });
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+      await copyPath(path.join(src, entry.name), path.join(dest, entry.name));
+    }
+    return;
+  }
+  await fs.mkdir(path.dirname(dest), { recursive: true });
+  await fs.copyFile(src, dest);
+}
+
+export async function removeDirSafe(parent, target, { dryRun = false, logger } = {}) {
+  const safeTarget = ensureInside(parent, target);
+  if (!(await pathExists(safeTarget))) {
+    return;
+  }
+  if (dryRun) {
+    logger?.info(`DRY-RUN remove directory ${safeTarget}`);
+    return;
+  }
+  await fs.rm(safeTarget, { recursive: true, force: true });
+}
+
+export async function removeFileSafe(parent, target, { dryRun = false, logger } = {}) {
+  const safeTarget = ensureInside(parent, target);
+  if (!(await pathExists(safeTarget))) {
+    return;
+  }
+  if (dryRun) {
+    logger?.info(`DRY-RUN remove file ${safeTarget}`);
+    return;
+  }
+  await fs.rm(safeTarget, { force: true });
+}
+
+export async function writeTextSafe(filePath, content, { dryRun = false, logger } = {}) {
+  if (dryRun) {
+    logger?.info(`DRY-RUN write ${filePath}`);
+    return;
+  }
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, content, "utf8");
+}