slack-cleaner 0.1.0

package/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.json]
+insert_final_newline = false

package/.env.example

@@ -0,0 +1,15 @@
+# Copy to .env and set one token.
+# Token resolution order:
+# 1) --token CLI flag
+# 2) SLACK_USER_TOKEN
+# 3) SLACK_BOT_TOKEN
+# 4) SLACK_TOKEN
+
+# Use a user token (xoxp-...) for deleting user-authored messages when required.
+SLACK_USER_TOKEN=
+
+# Or use a bot token (xoxb-...) if scopes and ownership allow deletion.
+SLACK_BOT_TOKEN=
+
+# Generic fallback token (used only if the vars above are empty).
+SLACK_TOKEN=

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "printWidth": 100,
+  "singleQuote": true,
+  "semi": true,
+  "trailingComma": "es5",
+  "arrowParens": "always"
+}

package/README.md

@@ -0,0 +1,128 @@
+# slack-cleaner-node
+
+`slack-cleaner-node` is a flag-driven Node.js CLI for safely finding and deleting Slack messages across channels, groups, and conversations, with dry-run by default, rich text-pattern matching, and retry-aware rate limiting.
+
+## Safety model
+
+- Default mode is **dry-run**.
+- Use `--perform` to actually delete messages.
+- Use `--limit` to cap deletions while validating filters.
+
+## Install
+
+```bash
+npm install
+npm link
+```
+
+Then run:
+
+```bash
+slack-cleaner --help
+```
+
+## Slack token and scopes
+
+Use a token that can read history and delete the target messages.
+
+This CLI auto-loads a `.env` file from your current working directory.
+
+Create it from the example:
+
+```bash
+cp .env.example .env
+```
+
+Set token in `.env` or shell env vars:
+
+```bash
+export SLACK_BOT_TOKEN='xoxb-...'
+# or
+export SLACK_USER_TOKEN='xoxp-...'
+# or
+export SLACK_TOKEN='xoxp-...'
+```
+
+Or pass directly:
+
+```bash
+slack-cleaner --token xoxp-...
+```
+
+Typical scopes you will need depend on conversation types, for example:
+
+- `channels:history`, `groups:history`, `im:history`, `mpim:history`
+- `chat:write`
+- `users:read`
+- conversation listing scopes where needed
+
+## Usage
+
+```bash
+slack-cleaner --token xoxp-... [targets] [filters] [options]
+```
+
+### Targets
+
+- `--channel <name[,name]>` public channels
+- `--group <name[,name]>` private channels
+- `--conversation <id[,id]>` direct conversation IDs
+
+At least one target flag is required.
+
+### Filters
+
+- `--user <username|user_id[,..]>` only messages by users
+- `--message-type <user|bot>` filter by type
+- `--pattern <regex>` regex on message text, attachments, block text, and related textual fields
+- `--after <date>` oldest date (ISO format supported)
+- `--before <date>` newest date
+
+### Execution
+
+- `--perform` execute deletions
+- `--limit <n>` max matched messages to preview/delete
+- `--rate-limit-ms <ms>` minimum delay between Slack API calls (default `250`)
+- `--max-retries <n>` retries on 429/5xx/network failures (default `6`)
+- `--verbose` detailed logs
+
+## Examples
+
+Dry-run messages from a user in `#general` after Jan 1, 2024:
+
+```bash
+slack-cleaner --channel general --user alice --after 2024-01-01
+```
+
+Delete up to 50 bot messages matching `deploy failed` in a private channel:
+
+```bash
+slack-cleaner --group ops-alerts --message-type bot --pattern "deploy failed" --limit 50 --perform
+```
+
+Delete from known conversation ID with a slower API cadence:
+
+```bash
+slack-cleaner --conversation C12345678 --rate-limit-ms 800 --perform
+```
+
+Delete with more aggressive retry policy:
+
+```bash
+slack-cleaner --channel general --perform --max-retries 10
+```
+
+## Notes
+
+- Slack may refuse deletes for messages your token cannot remove.
+- When multiple tokens are configured, delete attempts can fall back to secondary tokens on permission-related delete errors.
+- Requests use retry with backoff and `Retry-After` when Slack responds with HTTP 429.
+- If you still hit limits, increase `--rate-limit-ms` or reduce scope per run.
+- During `--perform`, TTY terminals show a self-updating progress line instead of one log line per deleted message.
+- Live progress includes `retries_total=<n>`, `retries_429=<n>`, and retry wait countdown `wait=<seconds>s`.
+- Each run prints `Rate limit retries: <n>` and `Total retries: <n>` at the end.
+
+## Credits
+
+- Inspired by [`slack_cleaner2`](https://github.com/sgratzl/slack_cleaner2) by [@sgratzl](https://github.com/sgratzl).
+- Built with implementation assistance from OpenAI Codex (GPT 5.3).

package/bin/slack-cleaner.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { run } = require('../src/cli');
+
+run(process.argv.slice(2)).catch((error) => {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "slack-cleaner",
+  "version": "0.1.0",
+  "description": "Flag-based Slack message cleaner CLI for Node.js",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "src/cli.js",
+  "bin": {
+    "slack-cleaner": "bin/slack-cleaner.js"
+  },
+  "scripts": {
+    "start": "node bin/slack-cleaner.js --help",
+    "lint": "find src bin test -name '*.js' -print0 | xargs -0 -n1 node --check",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "slack",
+    "cleanup",
+    "cli",
+    "messages"
+  ],
+  "directories": {
+    "test": "test"
+  },
+  "devDependencies": {},
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mcdado/slack-cleaner-node.git"
+  },
+  "author": "David Gasperoni <mcdado@gmail.com>",
+  "bugs": {
+    "url": "https://github.com/mcdado/slack-cleaner-node/issues"
+  },
+  "homepage": "https://github.com/mcdado/slack-cleaner-node#readme"
+}

package/src/cli/args.js

@@ -0,0 +1,150 @@
+/** @typedef {import('../types').ParsedArgs} ParsedArgs */
+
+/**
+ * @param {string[]} argv
+ * @returns {ParsedArgs}
+ */
+function parseArgs(argv) {
+  /** @type {ParsedArgs} */
+  const args = {
+    help: false,
+    token: undefined,
+    channelNames: [],
+    groupNames: [],
+    conversationIds: [],
+    users: [],
+    messageType: undefined,
+    pattern: undefined,
+    before: undefined,
+    after: undefined,
+    perform: false,
+    rateLimitMs: 250,
+    maxRetries: 6,
+    limit: 0,
+    verbose: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    switch (arg) {
+      case '--help':
+      case '-h':
+        args.help = true;
+        break;
+      case '--token':
+        args.token = requireValue(argv, ++i, '--token');
+        break;
+      case '--channel':
+        args.channelNames.push(...splitCsv(requireValue(argv, ++i, '--channel')));
+        break;
+      case '--group':
+        args.groupNames.push(...splitCsv(requireValue(argv, ++i, '--group')));
+        break;
+      case '--conversation':
+        args.conversationIds.push(...splitCsv(requireValue(argv, ++i, '--conversation')));
+        break;
+      case '--user':
+        args.users.push(...splitCsv(requireValue(argv, ++i, '--user')));
+        break;
+      case '--message-type': {
+        const value = requireValue(argv, ++i, '--message-type');
+        if (!['user', 'bot'].includes(value)) {
+          throw new Error('--message-type must be one of: user, bot');
+        }
+        args.messageType = value;
+        break;
+      }
+      case '--pattern':
+        args.pattern = requireValue(argv, ++i, '--pattern');
+        break;
+      case '--before':
+        args.before = parseDate(requireValue(argv, ++i, '--before'), '--before');
+        break;
+      case '--after':
+        args.after = parseDate(requireValue(argv, ++i, '--after'), '--after');
+        break;
+      case '--perform':
+        args.perform = true;
+        break;
+      case '--rate-limit-ms':
+        args.rateLimitMs = parseInteger(
+          requireValue(argv, ++i, '--rate-limit-ms'),
+          '--rate-limit-ms'
+        );
+        break;
+      case '--max-retries':
+        args.maxRetries = parseInteger(requireValue(argv, ++i, '--max-retries'), '--max-retries');
+        break;
+      case '--limit':
+        args.limit = parseInteger(requireValue(argv, ++i, '--limit'), '--limit');
+        break;
+      case '--verbose':
+        args.verbose = true;
+        break;
+      default:
+        throw new Error(`Unknown flag: ${arg}`);
+    }
+  }
+
+  return args;
+}
+
+/**
+ * @param {string} raw
+ * @param {string} flag
+ * @returns {Date}
+ */
+function parseDate(raw, flag) {
+  const date = new Date(raw);
+  if (Number.isNaN(date.getTime())) {
+    throw new Error(`Invalid date for ${flag}: ${raw}`);
+  }
+  return date;
+}
+
+/**
+ * @param {string} raw
+ * @param {string} flag
+ * @returns {number}
+ */
+function parseInteger(raw, flag) {
+  const value = Number.parseInt(raw, 10);
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`Invalid numeric value for ${flag}: ${raw}`);
+  }
+  return value;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {number} index
+ * @param {string} flag
+ * @returns {string}
+ */
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (!value || value.startsWith('--')) {
+    throw new Error(`Missing value for ${flag}`);
+  }
+  return value;
+}
+
+/**
+ * @param {string} value
+ * @returns {string[]}
+ */
+function splitCsv(value) {
+  return value
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+module.exports = {
+  parseArgs,
+  parseDate,
+  parseInteger,
+  requireValue,
+  splitCsv,
+};

package/src/cli/help.js

@@ -0,0 +1,34 @@
+function printHelp() {
+  console.log(`slack-cleaner (Node.js)\n
+Usage:
+  slack-cleaner --token xoxp-... [targets] [filters] [options]
+
+Targets:
+  --channel <name[,name]>         Public channel name(s)
+  --group <name[,name]>           Private channel name(s)
+  --conversation <id[,id]>        Conversation ID(s) (e.g. C123, G123, D123)
+
+Filters:
+  --user <username|user_id[,..]>  Keep only messages by these users
+  --message-type <user|bot>       Filter by message author type
+  --pattern <regex>               Regex for message text, attachments, and blocks
+  --after <date>                  Oldest message date (ISO-8601)
+  --before <date>                 Newest message date (ISO-8601)
+
+Execution:
+  --perform                       Actually delete messages (default is dry-run)
+  --limit <n>                     Limit number of matched messages to delete/preview
+  --rate-limit-ms <ms>            Minimum delay between Slack API calls (default: 250)
+  --max-retries <n>               Retries for 429/5xx/network errors (default: 6)
+  --verbose                       Show detailed output
+  -h, --help                      Show this help
+
+Environment:
+  The CLI auto-loads .env in the current working directory.
+  SLACK_USER_TOKEN, SLACK_BOT_TOKEN, or SLACK_TOKEN can be used instead of --token.
+`);
+}
+
+module.exports = {
+  printHelp,
+};

package/src/cli.js

@@ -0,0 +1,149 @@
+/* eslint-disable no-console */
+const path = require('node:path');
+
+require('./types');
+
+const { loadDotEnv, resolveTokens } = require('./config/env');
+const { parseArgs } = require('./cli/args');
+const { printHelp } = require('./cli/help');
+const { createSlackApi } = require('./slack/client');
+const { fetchUsers } = require('./slack/users');
+const { resolveConversations } = require('./slack/conversations');
+const { resolveUserFilters } = require('./domain/filters');
+const { createMessageMatcher } = require('./domain/matcher');
+const { collectMatches, deleteMatches } = require('./domain/cleanup');
+const { printPreview } = require('./output/preview');
+const { createDeletionProgressReporter } = require('./output/progress');
+
+/**
+ * @param {string[]} argv
+ * @returns {Promise<void>}
+ */
+async function run(argv) {
+  loadDotEnv(path.resolve(process.cwd(), '.env'));
+
+  const args = parseArgs(argv);
+  const tokens = resolveTokens(args.token);
+  args.token = tokens[0];
+
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  if (!args.token) {
+    throw new Error('Missing --token. Use --help for usage.');
+  }
+
+  if (
+    args.channelNames.length === 0 &&
+    args.groupNames.length === 0 &&
+    args.conversationIds.length === 0
+  ) {
+    throw new Error('Specify at least one target with --channel, --group, or --conversation.');
+  }
+
+  const api = createSlackApi(args.token, {
+    minRequestIntervalMs: args.rateLimitMs,
+    maxRetries: args.maxRetries,
+    verbose: args.verbose,
+  });
+  const deleteApis = tokens.map((token) =>
+    createSlackApi(token, {
+      minRequestIntervalMs: args.rateLimitMs,
+      maxRetries: args.maxRetries,
+      verbose: args.verbose,
+    })
+  );
+  const reportRetrySummary = () => {
+    const { rateLimitRetries, totalRetries } = getAggregateRetryStats(deleteApis);
+    console.log(`Rate limit retries: ${rateLimitRetries}`);
+    console.log(`Total retries: ${totalRetries}`);
+  };
+
+  const auth = await api('auth.test');
+  if (!auth.ok) {
+    throw new Error(auth.error || 'Unable to authenticate with Slack token.');
+  }
+
+  if (args.verbose) {
+    console.log(`Authenticated as ${auth.user} (${auth.user_id}) in ${auth.team}`);
+  }
+
+  const users = await fetchUsers(api);
+  const conversations = await resolveConversations(api, args, users);
+
+  if (conversations.length === 0) {
+    console.log('No matching conversations found.');
+    reportRetrySummary();
+    return;
+  }
+
+  const userFilterIds = resolveUserFilters(args.users, users);
+  const matcher = createMessageMatcher(args, userFilterIds);
+  const { matches, totalScanned } = await collectMatches(api, conversations, matcher, args);
+
+  console.log(`Conversations scanned: ${conversations.length}`);
+  console.log(`Messages scanned: ${totalScanned}`);
+  console.log(`Matched messages: ${matches.length}`);
+
+  if (!args.perform) {
+    printPreview(matches, args.limit);
+    console.log('Dry-run mode: no messages deleted. Use --perform to execute deletions.');
+    reportRetrySummary();
+    return;
+  }
+
+  const toDelete = args.limit > 0 ? matches.slice(0, args.limit) : matches;
+  if (toDelete.length === 0) {
+    console.log('No messages to delete.');
+    reportRetrySummary();
+    return;
+  }
+
+  const reporter = createDeletionProgressReporter(toDelete.length);
+  for (const deleteApi of deleteApis) {
+    if (typeof deleteApi.setRetryObserver === 'function') {
+      deleteApi.setRetryObserver((seconds) => reporter.setRetryWaitSeconds(seconds));
+    }
+  }
+
+  let deleted = 0;
+  let failed = 0;
+  try {
+    ({ deleted, failed } = await deleteMatches(deleteApis, toDelete, reporter));
+  } finally {
+    for (const deleteApi of deleteApis) {
+      if (typeof deleteApi.setRetryObserver === 'function') {
+        deleteApi.setRetryObserver(null);
+      }
+    }
+  }
+
+  console.log(`Deleted messages: ${deleted}/${toDelete.length} (${failed} failed)`);
+  reportRetrySummary();
+}
+
+/**
+ * @param {Array<import('./types').SlackApiFn>} apis
+ * @returns {{rateLimitRetries: number, totalRetries: number}}
+ */
+function getAggregateRetryStats(apis) {
+  let rateLimitRetries = 0;
+  let totalRetries = 0;
+
+  for (const api of apis) {
+    const stats =
+      typeof api.getStats === 'function'
+        ? api.getStats()
+        : { rateLimitRetries: 0, totalRetries: 0 };
+    rateLimitRetries += stats.rateLimitRetries || 0;
+    totalRetries += stats.totalRetries || 0;
+  }
+
+  return { rateLimitRetries, totalRetries };
+}
+
+module.exports = {
+  run,
+};

package/src/config/env.js

@@ -0,0 +1,111 @@
+const fs = require('node:fs');
+
+/**
+ * Loads .env style key/value pairs into process.env if keys are not already set.
+ * @param {string} filePath
+ */
+function loadDotEnv(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const lines = raw.split(/\r?\n/);
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue;
+    }
+
+    const separator = trimmed.indexOf('=');
+    if (separator <= 0) {
+      continue;
+    }
+
+    const key = normalizeEnvKey(trimmed.slice(0, separator).trim());
+    const value = stripQuotes(trimmed.slice(separator + 1).trim());
+
+    if (!key) {
+      continue;
+    }
+
+    if (process.env[key] === undefined) {
+      process.env[key] = value;
+    }
+  }
+}
+
+/**
+ * @param {string | undefined} cliToken
+ * @returns {string | undefined}
+ */
+function resolveToken(cliToken) {
+  return resolveTokens(cliToken)[0];
+}
+
+/**
+ * Returns ordered, unique token candidates:
+ * 1) CLI token
+ * 2) SLACK_USER_TOKEN
+ * 3) SLACK_BOT_TOKEN
+ * 4) SLACK_TOKEN
+ * @param {string | undefined} cliToken
+ * @returns {string[]}
+ */
+function resolveTokens(cliToken) {
+  const candidates = [
+    cliToken,
+    process.env.SLACK_USER_TOKEN,
+    process.env.SLACK_BOT_TOKEN,
+    process.env.SLACK_TOKEN,
+  ];
+  const ordered = [];
+  const seen = new Set();
+
+  for (const candidate of candidates) {
+    if (typeof candidate !== 'string') {
+      continue;
+    }
+
+    const normalized = candidate.trim();
+    if (!normalized || seen.has(normalized)) {
+      continue;
+    }
+
+    seen.add(normalized);
+    ordered.push(normalized);
+  }
+
+  return ordered;
+}
+
+/**
+ * @param {string} key
+ * @returns {string}
+ */
+function normalizeEnvKey(key) {
+  return key.replace(/^export\s+/, '').trim();
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function stripQuotes(value) {
+  if (value.length >= 2) {
+    const starts = value[0];
+    const ends = value[value.length - 1];
+    if ((starts === '"' && ends === '"') || (starts === "'" && ends === "'")) {
+      return value.slice(1, -1);
+    }
+  }
+
+  return value;
+}
+
+module.exports = {
+  loadDotEnv,
+  resolveToken,
+  resolveTokens,
+};