@lumenflow/cli 3.21.0 → 3.22.0

package/dist/chunk-5GTOXFYR.js

@@ -0,0 +1,392 @@
+import {
+  generateEnforceWorktreeScript,
+  generateEnforcementHooks,
+  generateRequireWuScript,
+  generateWarnIncompleteScript
+} from "./chunk-EA3IVO64.js";
+import {
+  loadTemplate
+} from "./chunk-HEVS5YLD.js";
+import {
+  generateScriptsFromManifest
+} from "./chunk-KY4PGL5V.js";
+import {
+  WU_OPTIONS,
+  createWUParser,
+  runCLI
+} from "./chunk-2GXVIN57.js";
+import {
+  CLAUDE_HOOKS,
+  DIRECTORIES
+} from "./chunk-DWMLTXKQ.js";
+import {
+  LUMENFLOW_CLIENT_IDS,
+  WORKSPACE_CONFIG_FILE_NAME,
+  WORKSPACE_V2_KEYS
+} from "./chunk-V6OJGLBA.js";
+
+// src/commands/integrate.ts
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "yaml";
+var SUPPORTED_CLIENTS = [
+  LUMENFLOW_CLIENT_IDS.CLAUDE_CODE,
+  LUMENFLOW_CLIENT_IDS.CURSOR,
+  LUMENFLOW_CLIENT_IDS.CODEX_CLI
+];
+var INTEGRATE_OPTIONS = {
+  client: {
+    name: "client",
+    flags: "--client <type>",
+    description: `Client type to integrate (${SUPPORTED_CLIENTS.join(", ")})`
+  },
+  sync: {
+    name: "sync",
+    flags: "--sync",
+    description: "Re-scaffold vendor-agnostic pre-commit/CI delegators and sync package.json command aliases"
+  },
+  force: WU_OPTIONS.force
+};
+function parseIntegrateOptions() {
+  const opts = createWUParser({
+    name: "lumenflow-integrate",
+    description: "Integrate LumenFlow enforcement with AI client tools",
+    options: Object.values(INTEGRATE_OPTIONS)
+  });
+  return {
+    client: opts.client ?? LUMENFLOW_CLIENT_IDS.CLAUDE_CODE,
+    sync: opts.sync ?? false,
+    force: opts.force ?? false
+  };
+}
+var PRE_COMMIT_TEMPLATE_PATH = "core/.husky/pre-commit.template";
+var CI_TEMPLATE_PATH = "core/.github/workflows/lumenflow-ci.yml.template";
+var PROJECT_PRE_COMMIT_PATH = ".husky/pre-commit";
+var PROJECT_CI_PATH = ".github/workflows/lumenflow-ci.yml";
+function syncCoreEnforcementDelegators(projectDir) {
+  const created = [];
+  const preCommitContent = loadTemplate(PRE_COMMIT_TEMPLATE_PATH);
+  const preCommitPath = path.join(projectDir, PROJECT_PRE_COMMIT_PATH);
+  fs.mkdirSync(path.dirname(preCommitPath), { recursive: true });
+  fs.writeFileSync(preCommitPath, preCommitContent, { mode: 493 });
+  created.push(PROJECT_PRE_COMMIT_PATH);
+  const ciContent = loadTemplate(CI_TEMPLATE_PATH);
+  const ciPath = path.join(projectDir, PROJECT_CI_PATH);
+  fs.mkdirSync(path.dirname(ciPath), { recursive: true });
+  fs.writeFileSync(ciPath, ciContent, "utf-8");
+  created.push(PROJECT_CI_PATH);
+  return created;
+}
+function syncPackageJsonScripts(projectDir) {
+  const packageJsonPath = path.join(projectDir, "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    return { added: [], modified: false };
+  }
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+  if (!packageJson.scripts || typeof packageJson.scripts !== "object") {
+    packageJson.scripts = {};
+  }
+  const scripts = packageJson.scripts;
+  const manifestScripts = generateScriptsFromManifest();
+  const added = [];
+  for (const [name, command] of Object.entries(manifestScripts)) {
+    if (!(name in scripts)) {
+      scripts[name] = command;
+      added.push(name);
+    }
+  }
+  const modified = added.length > 0;
+  if (modified) {
+    fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + "\n", "utf-8");
+  }
+  return { added, modified };
+}
+function readClaudeSettings(projectDir) {
+  const settingsPath = path.join(projectDir, DIRECTORIES.CLAUDE, "settings.json");
+  if (!fs.existsSync(settingsPath)) {
+    return {
+      $schema: "https://json.schemastore.org/claude-code-settings.json",
+      permissions: {
+        allow: ["Bash", "Read", "Write", "Edit", "WebFetch", "WebSearch", "Skill"]
+      }
+    };
+  }
+  try {
+    const content = fs.readFileSync(settingsPath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return {
+      $schema: "https://json.schemastore.org/claude-code-settings.json"
+    };
+  }
+}
+function mergeHooksIntoSettings(existing, generated) {
+  const result = { ...existing };
+  if (!result.hooks) {
+    result.hooks = {};
+  }
+  if (generated.preToolUse) {
+    if (!result.hooks.PreToolUse) {
+      result.hooks.PreToolUse = [];
+    }
+    for (const newHook of generated.preToolUse) {
+      const existingIndex = result.hooks.PreToolUse.findIndex((h) => h.matcher === newHook.matcher);
+      if (existingIndex >= 0) {
+        const existing2 = result.hooks.PreToolUse[existingIndex];
+        for (const hook of newHook.hooks) {
+          const isDuplicate = existing2.hooks.some((h) => h.command === hook.command);
+          if (!isDuplicate) {
+            existing2.hooks.push(hook);
+          }
+        }
+      } else {
+        result.hooks.PreToolUse.push(newHook);
+      }
+    }
+  }
+  if (generated.stop) {
+    if (!result.hooks.Stop) {
+      result.hooks.Stop = [];
+    }
+    for (const newHook of generated.stop) {
+      const existingIndex = result.hooks.Stop.findIndex((h) => h.matcher === newHook.matcher);
+      if (existingIndex >= 0) {
+        const existing2 = result.hooks.Stop[existingIndex];
+        for (const hook of newHook.hooks) {
+          const isDuplicate = existing2.hooks.some((h) => h.command === hook.command);
+          if (!isDuplicate) {
+            existing2.hooks.push(hook);
+          }
+        }
+      } else {
+        result.hooks.Stop.push(newHook);
+      }
+    }
+  }
+  return result;
+}
+async function integrateClaudeCode(projectDir, config) {
+  const enforcement = config.enforcement;
+  const created = [];
+  if (!enforcement?.hooks) {
+    console.log("[integrate] Enforcement hooks not enabled, skipping");
+    return created;
+  }
+  const hooksDir = path.join(projectDir, DIRECTORIES.CLAUDE_HOOKS);
+  if (!fs.existsSync(hooksDir)) {
+    fs.mkdirSync(hooksDir, { recursive: true });
+    console.log("[integrate] Created hooks directory");
+  }
+  const generatedHooks = generateEnforcementHooks({
+    block_outside_worktree: enforcement.block_outside_worktree ?? false,
+    require_wu_for_edits: enforcement.require_wu_for_edits ?? false,
+    warn_on_stop_without_wu_done: enforcement.warn_on_stop_without_wu_done ?? false
+  });
+  if (enforcement.block_outside_worktree) {
+    const scriptPath = path.join(hooksDir, CLAUDE_HOOKS.SCRIPTS.ENFORCE_WORKTREE);
+    fs.writeFileSync(scriptPath, generateEnforceWorktreeScript({ projectRoot: projectDir }), {
+      mode: 493
+    });
+    console.log(`[integrate] Generated ${CLAUDE_HOOKS.SCRIPTS.ENFORCE_WORKTREE}`);
+    created.push(path.join(DIRECTORIES.CLAUDE_HOOKS, CLAUDE_HOOKS.SCRIPTS.ENFORCE_WORKTREE));
+  }
+  if (enforcement.require_wu_for_edits) {
+    const scriptPath = path.join(hooksDir, CLAUDE_HOOKS.SCRIPTS.REQUIRE_WU);
+    fs.writeFileSync(scriptPath, generateRequireWuScript(), { mode: 493 });
+    console.log(`[integrate] Generated ${CLAUDE_HOOKS.SCRIPTS.REQUIRE_WU}`);
+    created.push(path.join(DIRECTORIES.CLAUDE_HOOKS, CLAUDE_HOOKS.SCRIPTS.REQUIRE_WU));
+  }
+  if (enforcement.warn_on_stop_without_wu_done) {
+    const scriptPath = path.join(hooksDir, CLAUDE_HOOKS.SCRIPTS.WARN_INCOMPLETE);
+    fs.writeFileSync(scriptPath, generateWarnIncompleteScript(), { mode: 493 });
+    console.log(`[integrate] Generated ${CLAUDE_HOOKS.SCRIPTS.WARN_INCOMPLETE}`);
+    created.push(path.join(DIRECTORIES.CLAUDE_HOOKS, CLAUDE_HOOKS.SCRIPTS.WARN_INCOMPLETE));
+  }
+  const existingSettings = readClaudeSettings(projectDir);
+  const updatedSettings = mergeHooksIntoSettings(existingSettings, generatedHooks);
+  const settingsPath = path.join(projectDir, DIRECTORIES.CLAUDE, "settings.json");
+  fs.writeFileSync(settingsPath, JSON.stringify(updatedSettings, null, 2) + "\n", "utf-8");
+  console.log("[integrate] Updated settings.json");
+  return created;
+}
+function readWorkspaceSoftwareDeliveryConfig(projectDir) {
+  const configPath = path.join(projectDir, WORKSPACE_CONFIG_FILE_NAME);
+  if (!fs.existsSync(configPath)) {
+    return null;
+  }
+  try {
+    const content = fs.readFileSync(configPath, "utf-8");
+    const workspaceDoc = yaml.parse(content);
+    if (!workspaceDoc || typeof workspaceDoc !== "object") {
+      return null;
+    }
+    const workspace = workspaceDoc;
+    const softwareDelivery = workspace[WORKSPACE_V2_KEYS.SOFTWARE_DELIVERY];
+    if (!softwareDelivery || typeof softwareDelivery !== "object") {
+      return null;
+    }
+    return softwareDelivery;
+  } catch {
+    return null;
+  }
+}
+function readEnforcementConfig(projectDir) {
+  const softwareDelivery = readWorkspaceSoftwareDeliveryConfig(projectDir);
+  return softwareDelivery?.agents?.clients?.[LUMENFLOW_CLIENT_IDS.CLAUDE_CODE]?.enforcement ?? null;
+}
+var CURSOR_RECOVERY_RULES = `# LumenFlow Context Recovery
+
+## On Session Start
+
+When starting a new session or resuming work, always check for pending recovery context:
+
+\`\`\`bash
+# Check for recovery files
+ls .lumenflow/state/recovery-pending-*.md 2>/dev/null
+\`\`\`
+
+If recovery files exist:
+
+1. Read the recovery file contents \u2014 they contain your last checkpoint, acceptance criteria, and code paths
+2. Run \`pnpm mem:recover --wu WU-XXX\` (replace WU-XXX with the WU ID from the filename) for the latest context
+3. Continue working based on the recovery context
+
+## Context Loss Prevention
+
+Before any long operation that might lose context:
+
+\`\`\`bash
+pnpm mem:checkpoint "description of current progress" --wu WU-XXX
+\`\`\`
+
+## Recovery Command Reference
+
+| Command                                     | Purpose                            |
+| ------------------------------------------- | ---------------------------------- |
+| \`pnpm mem:recover --wu WU-XXX\`              | Generate recovery context for a WU |
+| \`pnpm wu:brief --id WU-XXX --client cursor\` | Generate full handoff prompt       |
+| \`pnpm wu:status --id WU-XXX\`                | Check WU status and location       |
+| \`pnpm mem:checkpoint\`                       | Save progress checkpoint           |
+`;
+var AGENTS_RECOVERY_SECTION = `
+---
+
+## Context Recovery (WU-2157)
+
+If you are resuming work or have lost context, check for recovery files:
+
+\`\`\`bash
+# Check for pending recovery
+ls .lumenflow/state/recovery-pending-*.md 2>/dev/null
+
+# Generate fresh recovery context
+pnpm mem:recover --wu WU-XXX
+
+# Or generate a full handoff prompt
+pnpm wu:brief --id WU-XXX --client codex-cli
+\`\`\`
+
+Recovery files contain your last checkpoint, acceptance criteria, code paths, and changed files.
+Always save checkpoints before long operations: \`pnpm mem:checkpoint "progress note" --wu WU-XXX\`
+`;
+function integrateCursor(projectDir) {
+  const created = [];
+  const rulesDir = path.join(projectDir, ".cursor", "rules");
+  if (!fs.existsSync(rulesDir)) {
+    fs.mkdirSync(rulesDir, { recursive: true });
+    console.log("[integrate] Created .cursor/rules/ directory");
+  }
+  const recoveryRulesPath = path.join(rulesDir, "lumenflow-recovery.md");
+  fs.writeFileSync(recoveryRulesPath, CURSOR_RECOVERY_RULES, "utf-8");
+  console.log("[integrate] Generated .cursor/rules/lumenflow-recovery.md");
+  created.push(".cursor/rules/lumenflow-recovery.md");
+  return created;
+}
+function integrateCodexCli(projectDir) {
+  const created = [];
+  const agentsPath = path.join(projectDir, "AGENTS.md");
+  if (!fs.existsSync(agentsPath)) {
+    console.log("[integrate] AGENTS.md not found, skipping Codex integration");
+    return created;
+  }
+  const content = fs.readFileSync(agentsPath, "utf-8");
+  if (content.includes("## Context Recovery (WU-2157)")) {
+    console.log("[integrate] AGENTS.md already contains recovery section, skipping");
+    return created;
+  }
+  fs.writeFileSync(agentsPath, content + AGENTS_RECOVERY_SECTION, "utf-8");
+  console.log("[integrate] Appended recovery section to AGENTS.md");
+  created.push("AGENTS.md");
+  return created;
+}
+async function main() {
+  const opts = parseIntegrateOptions();
+  const projectDir = process.cwd();
+  if (opts.sync) {
+    const synced = syncCoreEnforcementDelegators(projectDir);
+    for (const file of synced) {
+      console.log(`[integrate] Synced ${file}`);
+    }
+    const scriptSync = syncPackageJsonScripts(projectDir);
+    if (scriptSync.modified) {
+      console.log(
+        `[integrate] Added ${scriptSync.added.length} command alias(es): ${scriptSync.added.join(", ")}`
+      );
+    } else {
+      console.log("[integrate] package.json command aliases already up to date");
+    }
+  }
+  switch (opts.client) {
+    case LUMENFLOW_CLIENT_IDS.CLAUDE_CODE: {
+      const enforcement = readEnforcementConfig(projectDir);
+      if (!enforcement) {
+        console.log(
+          `[integrate] No enforcement config found in ${WORKSPACE_CONFIG_FILE_NAME} ${WORKSPACE_V2_KEYS.SOFTWARE_DELIVERY}.agents.clients.${LUMENFLOW_CLIENT_IDS.CLAUDE_CODE}`
+        );
+        console.log("[integrate] Add this to your workspace config to enable enforcement hooks:");
+        console.log(`
+${WORKSPACE_V2_KEYS.SOFTWARE_DELIVERY}:
+  agents:
+    clients:
+      ${LUMENFLOW_CLIENT_IDS.CLAUDE_CODE}:
+        enforcement:
+          hooks: true
+          block_outside_worktree: true
+          require_wu_for_edits: true
+          warn_on_stop_without_wu_done: true
+`);
+        return;
+      }
+      await integrateClaudeCode(projectDir, { enforcement });
+      console.log("[integrate] Claude Code integration complete");
+      break;
+    }
+    case LUMENFLOW_CLIENT_IDS.CURSOR: {
+      integrateCursor(projectDir);
+      console.log("[integrate] Cursor integration complete");
+      break;
+    }
+    case LUMENFLOW_CLIENT_IDS.CODEX_CLI: {
+      integrateCodexCli(projectDir);
+      console.log("[integrate] Codex CLI integration complete");
+      break;
+    }
+    default:
+      console.error(`[integrate] Unsupported client: ${opts.client}`);
+      console.error(`[integrate] Supported clients: ${SUPPORTED_CLIENTS.join(", ")}`);
+      process.exit(1);
+  }
+}
+if (import.meta.main) {
+  void runCLI(main);
+}
+
+export {
+  parseIntegrateOptions,
+  syncCoreEnforcementDelegators,
+  syncPackageJsonScripts,
+  integrateClaudeCode,
+  integrateCursor,
+  integrateCodexCli,
+  main
+};

package/dist/chunk-5VY6MQMC.js

@@ -0,0 +1,240 @@
+import {
+  SIGNAL_FILE_NAME,
+  SIGNAL_RECEIPTS_FILE_NAME
+} from "./chunk-OMJD6A3S.js";
+import {
+  LUMENFLOW_MEMORY_PATHS
+} from "./chunk-4N74J3UT.js";
+import {
+  MS_PER_DAY
+} from "./chunk-V6OJGLBA.js";
+import {
+  ErrorCodes,
+  createError
+} from "./chunk-RXRKBBSM.js";
+
+// ../memory/dist/signal-cleanup-core.js
+import fs from "fs/promises";
+import path from "path";
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
+var ms = require2("ms");
+var DEFAULT_SIGNAL_CLEANUP_CONFIG = {
+  ttl: 7 * MS_PER_DAY,
+  unreadTtl: 30 * MS_PER_DAY,
+  maxEntries: 500
+};
+function parseSignalTtl(ttlString) {
+  if (!ttlString || typeof ttlString !== "string") {
+    throw createError(ErrorCodes.INVALID_DURATION, "Invalid TTL format: TTL string is required");
+  }
+  const trimmed = ttlString.trim();
+  if (!trimmed) {
+    throw createError(ErrorCodes.INVALID_DURATION, "Invalid TTL format: TTL string is required");
+  }
+  const result = ms(trimmed);
+  if (result == null || result <= 0) {
+    throw createError(ErrorCodes.INVALID_DURATION, `Invalid TTL format: "${ttlString}" is not a valid duration`);
+  }
+  return result;
+}
+function isSignalExpired(signal, ttlMs, now) {
+  if (!signal.created_at) {
+    return false;
+  }
+  const createdAt = new Date(signal.created_at).getTime();
+  if (Number.isNaN(createdAt)) {
+    return false;
+  }
+  const age = now - createdAt;
+  return age > ttlMs;
+}
+function shouldRemoveSignal(signal, config, context) {
+  const { now, activeWuIds } = context;
+  if (signal.wu_id && activeWuIds.has(signal.wu_id)) {
+    return { remove: false, reason: "active-wu-protected" };
+  }
+  if (signal.read) {
+    if (isSignalExpired(signal, config.ttl, now)) {
+      return { remove: true, reason: "ttl-expired" };
+    }
+  } else {
+    if (isSignalExpired(signal, config.unreadTtl, now)) {
+      return { remove: true, reason: "unread-ttl-expired" };
+    }
+  }
+  return { remove: false, reason: "within-ttl" };
+}
+function estimateSignalBytes(signal) {
+  return JSON.stringify(signal).length + 1;
+}
+function getCompactionRatio(removedCount, totalCount) {
+  if (totalCount === 0) {
+    return 0;
+  }
+  return removedCount / totalCount;
+}
+function getSignalsPath(baseDir) {
+  return path.join(baseDir, LUMENFLOW_MEMORY_PATHS.MEMORY_DIR, SIGNAL_FILE_NAME);
+}
+function getReceiptsPath(baseDir) {
+  return path.join(baseDir, LUMENFLOW_MEMORY_PATHS.MEMORY_DIR, SIGNAL_RECEIPTS_FILE_NAME);
+}
+async function loadAllReceipts(baseDir) {
+  const receiptsPath = getReceiptsPath(baseDir);
+  try {
+    const content = await fs.readFile(receiptsPath, { encoding: "utf-8" });
+    const lines = content.split("\n").filter((line) => line.trim());
+    return lines.map((line) => JSON.parse(line));
+  } catch (err) {
+    const error = err;
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+}
+async function writeReceipts(baseDir, receipts) {
+  const receiptsPath = getReceiptsPath(baseDir);
+  const content = receipts.map((r) => JSON.stringify(r)).join("\n") + (receipts.length > 0 ? "\n" : "");
+  await fs.writeFile(receiptsPath, content, { encoding: "utf-8" });
+}
+async function loadAllSignals(baseDir) {
+  const signalsPath = getSignalsPath(baseDir);
+  try {
+    const content = await fs.readFile(signalsPath, { encoding: "utf-8" });
+    const lines = content.split("\n").filter((line) => line.trim());
+    return lines.map((line) => JSON.parse(line));
+  } catch (err) {
+    const error = err;
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+}
+async function writeSignals(baseDir, signals) {
+  const signalsPath = getSignalsPath(baseDir);
+  const content = signals.map((s) => JSON.stringify(s)).join("\n") + (signals.length > 0 ? "\n" : "");
+  await fs.writeFile(signalsPath, content, { encoding: "utf-8" });
+}
+async function defaultGetActiveWuIds() {
+  return /* @__PURE__ */ new Set();
+}
+function buildCleanupConfig(options) {
+  const { ttl, ttlMs: providedTtlMs, unreadTtl, unreadTtlMs: providedUnreadTtlMs, maxEntries } = options;
+  let ttlMs = providedTtlMs ?? DEFAULT_SIGNAL_CLEANUP_CONFIG.ttl;
+  if (ttl && !providedTtlMs) {
+    ttlMs = parseSignalTtl(ttl);
+  }
+  let unreadTtlMs = providedUnreadTtlMs ?? DEFAULT_SIGNAL_CLEANUP_CONFIG.unreadTtl;
+  if (unreadTtl && !providedUnreadTtlMs) {
+    unreadTtlMs = parseSignalTtl(unreadTtl);
+  }
+  return {
+    ttl: ttlMs,
+    unreadTtl: unreadTtlMs,
+    maxEntries: maxEntries ?? DEFAULT_SIGNAL_CLEANUP_CONFIG.maxEntries
+  };
+}
+function processSignalsForTtl(signals, config, context) {
+  const state = {
+    removedIds: [],
+    retainedIds: [],
+    retainedSignals: [],
+    bytesFreed: 0,
+    breakdown: {
+      ttlExpired: 0,
+      unreadTtlExpired: 0,
+      countLimitExceeded: 0,
+      activeWuProtected: 0
+    }
+  };
+  for (const signal of signals) {
+    const decision = shouldRemoveSignal(signal, config, context);
+    processSignalDecision(signal, decision, state);
+  }
+  return state;
+}
+function processSignalDecision(signal, decision, state) {
+  if (decision.remove) {
+    state.removedIds.push(signal.id);
+    state.bytesFreed += estimateSignalBytes(signal);
+    updateBreakdownForRemoval(decision.reason, state.breakdown);
+  } else {
+    state.retainedIds.push(signal.id);
+    state.retainedSignals.push(signal);
+    if (decision.reason === "active-wu-protected") {
+      state.breakdown.activeWuProtected++;
+    }
+  }
+}
+function updateBreakdownForRemoval(reason, breakdown) {
+  if (reason === "ttl-expired") {
+    breakdown.ttlExpired++;
+  } else if (reason === "unread-ttl-expired") {
+    breakdown.unreadTtlExpired++;
+  }
+}
+function applyCountPruning(state, maxEntries) {
+  if (state.retainedSignals.length <= maxEntries) {
+    return;
+  }
+  state.retainedSignals.sort((a, b) => {
+    const aTime = new Date(a.created_at).getTime();
+    const bTime = new Date(b.created_at).getTime();
+    return aTime - bTime;
+  });
+  const toRemove = state.retainedSignals.length - maxEntries;
+  for (let i = 0; i < toRemove; i++) {
+    const signal = state.retainedSignals[i];
+    if (!signal)
+      continue;
+    const idIndex = state.retainedIds.indexOf(signal.id);
+    if (idIndex !== -1) {
+      state.retainedIds.splice(idIndex, 1);
+    }
+    state.removedIds.push(signal.id);
+    state.bytesFreed += estimateSignalBytes(signal);
+    state.breakdown.countLimitExceeded++;
+  }
+  state.retainedSignals.splice(0, toRemove);
+}
+async function cleanupSignals(baseDir, options = {}) {
+  const { dryRun = false, now = Date.now(), getActiveWuIds = defaultGetActiveWuIds } = options;
+  const config = buildCleanupConfig(options);
+  const signals = await loadAllSignals(baseDir);
+  const activeWuIds = await getActiveWuIds();
+  const receipts = await loadAllReceipts(baseDir);
+  const receiptSignalIds = new Set(receipts.map((r) => r.signal_id));
+  for (const signal of signals) {
+    if (!signal.read && receiptSignalIds.has(signal.id)) {
+      signal.read = true;
+    }
+  }
+  const state = processSignalsForTtl(signals, config, { now, activeWuIds });
+  applyCountPruning(state, config.maxEntries);
+  const compactionRatio = getCompactionRatio(state.removedIds.length, signals.length);
+  const baseResult = {
+    success: true,
+    removedIds: state.removedIds,
+    retainedIds: state.retainedIds,
+    bytesFreed: state.bytesFreed,
+    compactionRatio,
+    breakdown: state.breakdown
+  };
+  if (dryRun) {
+    return { ...baseResult, dryRun: true };
+  }
+  if (state.removedIds.length > 0) {
+    await writeSignals(baseDir, state.retainedSignals);
+    const retainedIdSet = new Set(state.retainedIds);
+    const retainedReceipts = receipts.filter((r) => retainedIdSet.has(r.signal_id));
+    await writeReceipts(baseDir, retainedReceipts);
+  }
+  return baseResult;
+}
+
+export {
+  cleanupSignals
+};