discoclaw 0.1.0

package/dist/tasks/task-lifecycle.test.js

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { isDirectTaskLifecycleActive, withDirectTaskLifecycle, withTaskLifecycleLock, } from './task-lifecycle.js';
+describe('task lifecycle lock', () => {
+    it('serializes lifecycle work for the same task id', async () => {
+        const events = [];
+        let releaseFirst;
+        const firstGate = new Promise((resolve) => {
+            releaseFirst = resolve;
+        });
+        const first = withTaskLifecycleLock('ws-001', async () => {
+            events.push('first:start');
+            await firstGate;
+            events.push('first:end');
+        });
+        await Promise.resolve();
+        const second = withTaskLifecycleLock('ws-001', async () => {
+            events.push('second:start');
+            events.push('second:end');
+        });
+        await Promise.resolve();
+        expect(events).toEqual(['first:start']);
+        releaseFirst();
+        await Promise.all([first, second]);
+        expect(events).toEqual(['first:start', 'first:end', 'second:start', 'second:end']);
+    });
+    it('tracks direct action ownership only while work is active', async () => {
+        expect(isDirectTaskLifecycleActive('ws-002')).toBe(false);
+        await withDirectTaskLifecycle('ws-002', async () => {
+            expect(isDirectTaskLifecycleActive('ws-002')).toBe(true);
+            await Promise.resolve();
+            expect(isDirectTaskLifecycleActive('ws-002')).toBe(true);
+        });
+        expect(isDirectTaskLifecycleActive('ws-002')).toBe(false);
+    });
+});

package/dist/tasks/task-sync-apply-plan.js

@@ -0,0 +1,95 @@
+import { getThreadIdFromTask } from './thread-helpers.js';
+function hasLabel(task, label) {
+    return (task.labels ?? []).includes(label);
+}
+function operationKey(phase, taskId) {
+    return `task-sync:${phase}:${taskId}`;
+}
+/**
+ * Stage: ingest
+ * Copy list shape while preserving task object references.
+ */
+export function ingestTaskSyncSnapshot(allTasks) {
+    return [...allTasks];
+}
+/**
+ * Stage: normalize
+ * Split tasks into deterministic phase buckets from the ingested snapshot.
+ */
+export function normalizeTaskSyncBuckets(allTasks) {
+    const tasksMissingRef = allTasks.filter((task) => !getThreadIdFromTask(task) &&
+        task.status !== 'closed' &&
+        !hasLabel(task, 'no-thread'));
+    const needsBlockedTasks = allTasks.filter((task) => task.status === 'open' && (task.labels ?? []).some((l) => /^(waiting|blocked)-/.test(l)));
+    const tasksWithRef = allTasks.filter((task) => getThreadIdFromTask(task) && task.status !== 'closed');
+    const closedTasks = allTasks.filter((task) => task.status === 'closed' && Boolean(getThreadIdFromTask(task)));
+    return { tasksMissingRef, needsBlockedTasks, tasksWithRef, closedTasks };
+}
+/**
+ * Stage: diff
+ * Build an idempotent operation plan from normalized buckets.
+ */
+export function planTaskSyncOperations(buckets) {
+    const operations = [];
+    const seen = new Set();
+    const pushOps = (phase, tasks) => {
+        for (const task of tasks) {
+            const key = operationKey(phase, task.id);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            operations.push({ phase, taskId: task.id, key });
+        }
+    };
+    pushOps('phase1', buckets.tasksMissingRef);
+    pushOps('phase2', buckets.needsBlockedTasks);
+    pushOps('phase3', buckets.tasksWithRef);
+    pushOps('phase4', buckets.closedTasks);
+    return operations;
+}
+export function operationTaskIdSet(operations, phase) {
+    const ids = new Set();
+    for (const operation of operations) {
+        if (operation.phase === phase)
+            ids.add(operation.taskId);
+    }
+    return ids;
+}
+/**
+ * Stage: apply dispatch
+ * Ordered task IDs for a given phase, preserving diff-plan sequence.
+ */
+export function operationTaskIdList(operations, phase) {
+    const ids = [];
+    for (const operation of operations) {
+        if (operation.phase === phase)
+            ids.push(operation.taskId);
+    }
+    return ids;
+}
+const DEFAULT_PHASE_ORDER = ['phase1', 'phase2', 'phase3', 'phase4'];
+/**
+ * Stage: apply plan
+ * Build ordered phase dispatch inputs directly from diff-plan operations.
+ */
+export function planTaskApplyPhases(operations, phaseOrder = DEFAULT_PHASE_ORDER) {
+    const phases = [];
+    for (const phase of phaseOrder) {
+        phases.push({
+            phase,
+            taskIds: operationTaskIdList(operations, phase),
+        });
+    }
+    return phases;
+}
+/**
+ * Stage: compose (stages 2-4)
+ * Build diff operations, phase dispatch plans, and task lookup from a task snapshot.
+ */
+export function planTaskSyncApplyExecution(allTasks) {
+    const normalized = normalizeTaskSyncBuckets(allTasks);
+    const operations = planTaskSyncOperations(normalized);
+    const phasePlans = planTaskApplyPhases(operations);
+    const tasksById = new Map(allTasks.map((task) => [task.id, task]));
+    return { tasksById, operations, phasePlans };
+}

package/dist/tasks/task-sync-apply-types.js

@@ -0,0 +1,12 @@
+export function createTaskSyncApplyCounters() {
+    return {
+        threadsCreated: 0,
+        emojisUpdated: 0,
+        starterMessagesUpdated: 0,
+        threadsArchived: 0,
+        statusesUpdated: 0,
+        tagsUpdated: 0,
+        warnings: 0,
+        closesDeferred: 0,
+    };
+}

package/dist/tasks/task-sync-apply.js

@@ -0,0 +1,319 @@
+import { planTaskReconcileFromThreadSources, } from './task-sync-pipeline.js';
+import { withTaskLifecycleLock } from './task-lifecycle.js';
+import { closeTaskThread, createTaskThread, ensureUnarchived, findExistingThreadForTask, isTaskThreadAlreadyClosed, isThreadArchived, updateTaskStarterMessage, updateTaskThreadName, updateTaskThreadTags, } from './thread-ops.js';
+import { extractShortIdFromThreadName, getThreadIdFromTask, shortTaskId, } from './thread-helpers.js';
+function sleep(ms) {
+    const n = ms ?? 0;
+    if (n <= 0)
+        return Promise.resolve();
+    return new Promise((r) => setTimeout(r, n));
+}
+export function createTaskSyncApplyCounters() {
+    return {
+        threadsCreated: 0,
+        emojisUpdated: 0,
+        starterMessagesUpdated: 0,
+        threadsArchived: 0,
+        statusesUpdated: 0,
+        tagsUpdated: 0,
+        warnings: 0,
+        closesDeferred: 0,
+    };
+}
+async function applyPhase1CreateMissingThreads(ctx, tasksById, plannedTaskIds) {
+    for (const taskId of plannedTaskIds) {
+        const task = tasksById.get(taskId);
+        if (!task)
+            continue;
+        await withTaskLifecycleLock(task.id, async () => {
+            const latestTask = ctx.store.get(task.id) ?? task;
+            if (getThreadIdFromTask(latestTask) ||
+                latestTask.status === 'closed' ||
+                (latestTask.labels ?? []).includes('no-thread')) {
+                return;
+            }
+            try {
+                const existing = await findExistingThreadForTask(ctx.forum, latestTask.id, { archivedLimit: ctx.archivedDedupeLimit });
+                if (existing) {
+                    try {
+                        ctx.taskService.update(latestTask.id, { externalRef: `discord:${existing}` });
+                        ctx.log?.info({ taskId: latestTask.id, threadId: existing }, 'task-sync:phase1 external-ref backfilled');
+                    }
+                    catch (err) {
+                        ctx.log?.warn({ err, taskId: latestTask.id, threadId: existing }, 'task-sync:phase1 external-ref backfill failed');
+                        ctx.counters.warnings++;
+                    }
+                    return;
+                }
+                const threadId = await createTaskThread(ctx.forum, latestTask, ctx.tagMap, ctx.mentionUserId);
+                try {
+                    ctx.taskService.update(latestTask.id, { externalRef: `discord:${threadId}` });
+                }
+                catch (err) {
+                    ctx.log?.warn({ err, taskId: latestTask.id }, 'task-sync:phase1 external-ref update failed');
+                    ctx.counters.warnings++;
+                }
+                ctx.counters.threadsCreated++;
+                ctx.log?.info({ taskId: latestTask.id, threadId }, 'task-sync:phase1 thread created');
+            }
+            catch (err) {
+                ctx.log?.warn({ err, taskId: latestTask.id }, 'task-sync:phase1 failed');
+                ctx.counters.warnings++;
+            }
+        });
+        await sleep(ctx.throttleMs);
+    }
+}
+async function applyPhase2FixBlockedStatus(ctx, tasksById, plannedTaskIds) {
+    for (const taskId of plannedTaskIds) {
+        const task = tasksById.get(taskId);
+        if (!task)
+            continue;
+        try {
+            ctx.taskService.update(task.id, { status: 'blocked' });
+            task.status = 'blocked';
+            ctx.counters.statusesUpdated++;
+            ctx.log?.info({ taskId: task.id }, 'task-sync:phase2 status updated to blocked');
+        }
+        catch (err) {
+            ctx.log?.warn({ err, taskId: task.id }, 'task-sync:phase2 failed');
+            ctx.counters.warnings++;
+        }
+        await sleep(ctx.throttleMs);
+    }
+}
+async function applyPhase3SyncActiveThreads(ctx, tasksById, plannedTaskIds) {
+    for (const taskId of plannedTaskIds) {
+        const task = tasksById.get(taskId);
+        if (!task)
+            continue;
+        await withTaskLifecycleLock(task.id, async () => {
+            const latestTask = ctx.store.get(task.id) ?? task;
+            const threadId = getThreadIdFromTask(latestTask);
+            if (!threadId || latestTask.status === 'closed') {
+                return;
+            }
+            if (await isThreadArchived(ctx.client, threadId)) {
+                return;
+            }
+            try {
+                await ensureUnarchived(ctx.client, threadId);
+            }
+            catch { }
+            try {
+                const changed = await updateTaskThreadName(ctx.client, threadId, latestTask);
+                if (changed) {
+                    ctx.counters.emojisUpdated++;
+                    ctx.log?.info({ taskId: latestTask.id, threadId }, 'task-sync:phase3 name updated');
+                }
+            }
+            catch (err) {
+                ctx.log?.warn({ err, taskId: latestTask.id, threadId }, 'task-sync:phase3 failed');
+                ctx.counters.warnings++;
+            }
+            try {
+                const starterChanged = await updateTaskStarterMessage(ctx.client, threadId, latestTask, ctx.mentionUserId);
+                if (starterChanged) {
+                    ctx.counters.starterMessagesUpdated++;
+                    ctx.log?.info({ taskId: latestTask.id, threadId }, 'task-sync:phase3 starter updated');
+                }
+            }
+            catch (err) {
+                ctx.log?.warn({ err, taskId: latestTask.id, threadId }, 'task-sync:phase3 starter update failed');
+                ctx.counters.warnings++;
+            }
+            try {
+                const tagChanged = await updateTaskThreadTags(ctx.client, threadId, latestTask, ctx.tagMap);
+                if (tagChanged) {
+                    ctx.counters.tagsUpdated++;
+                    ctx.log?.info({ taskId: latestTask.id, threadId }, 'task-sync:phase3 tags updated');
+                }
+            }
+            catch (err) {
+                ctx.log?.warn({ err, taskId: latestTask.id, threadId }, 'task-sync:phase3 tag update failed');
+                ctx.counters.warnings++;
+            }
+        });
+        await sleep(ctx.throttleMs);
+    }
+}
+async function applyPhase4ArchiveClosedThreads(ctx, tasksById, plannedTaskIds) {
+    for (const taskId of plannedTaskIds) {
+        const task = tasksById.get(taskId);
+        if (!task)
+            continue;
+        await withTaskLifecycleLock(task.id, async () => {
+            const latestTask = ctx.store.get(task.id) ?? task;
+            const threadId = getThreadIdFromTask(latestTask);
+            if (!threadId || latestTask.status !== 'closed') {
+                return;
+            }
+            try {
+                if (await isTaskThreadAlreadyClosed(ctx.client, threadId, latestTask, ctx.tagMap)) {
+                    return;
+                }
+                if (ctx.hasInFlightForChannel(threadId)) {
+                    ctx.counters.closesDeferred++;
+                    ctx.log?.info({ taskId: latestTask.id, threadId }, 'task-sync:phase4 close deferred (in-flight reply active)');
+                    return;
+                }
+                await closeTaskThread(ctx.client, threadId, latestTask, ctx.tagMap, ctx.log);
+                ctx.counters.threadsArchived++;
+                ctx.log?.info({ taskId: latestTask.id, threadId }, 'task-sync:phase4 archived');
+            }
+            catch (err) {
+                ctx.log?.warn({ err, taskId: latestTask.id, threadId }, 'task-sync:phase4 failed');
+                ctx.counters.warnings++;
+            }
+        });
+        await sleep(ctx.throttleMs);
+    }
+}
+const PHASE_EXECUTORS = {
+    phase1: applyPhase1CreateMissingThreads,
+    phase2: applyPhase2FixBlockedStatus,
+    phase3: applyPhase3SyncActiveThreads,
+    phase4: applyPhase4ArchiveClosedThreads,
+};
+async function applyReconcileOrphanThread(ctx, operation, state) {
+    state.orphanThreadsFound++;
+    ctx.log?.info({ threadId: operation.thread.id, threadName: operation.thread.name, shortId: operation.shortId }, 'task-sync:phase5 orphan thread detected');
+}
+async function applyReconcileCollision(ctx, operation) {
+    ctx.log?.info({ threadId: operation.thread.id, shortId: operation.shortId, count: operation.collisionCount }, 'task-sync:phase5 short-id collision, skipping');
+}
+async function applyReconcileSkipMismatch(ctx, operation) {
+    ctx.log?.info({ taskId: operation.task?.id, threadId: operation.thread.id, existingThreadId: operation.existingThreadId }, 'task-sync:phase5 external_ref points to different thread, skipping');
+}
+async function applyReconcileArchiveActiveClosed(ctx, operation, state) {
+    const task = operation.task;
+    if (!task)
+        return;
+    if (ctx.hasInFlightForChannel(operation.thread.id)) {
+        ctx.counters.closesDeferred++;
+        ctx.log?.info({ taskId: task.id, threadId: operation.thread.id }, 'task-sync:phase5 close deferred (in-flight reply active)');
+        return;
+    }
+    if (!operation.existingThreadId) {
+        try {
+            ctx.taskService.update(task.id, { externalRef: `discord:${operation.thread.id}` });
+            ctx.log?.info({ taskId: task.id, threadId: operation.thread.id }, 'task-sync:phase5 external_ref backfilled');
+        }
+        catch (err) {
+            ctx.log?.warn({ err, taskId: task.id, threadId: operation.thread.id }, 'task-sync:phase5 external_ref backfill failed');
+            ctx.counters.warnings++;
+        }
+    }
+    try {
+        await closeTaskThread(ctx.client, operation.thread.id, task, ctx.tagMap, ctx.log);
+        state.threadsReconciled++;
+        ctx.log?.info({ taskId: task.id, threadId: operation.thread.id }, 'task-sync:phase5 reconciled (archived)');
+    }
+    catch (err) {
+        ctx.log?.warn({ err, taskId: task.id, threadId: operation.thread.id }, 'task-sync:phase5 archive failed');
+        ctx.counters.warnings++;
+    }
+}
+async function applyReconcileArchivedClosed(ctx, operation, state) {
+    const task = operation.task;
+    if (!task)
+        return;
+    try {
+        const alreadyClosed = await isTaskThreadAlreadyClosed(ctx.client, operation.thread.id, task, ctx.tagMap);
+        if (!alreadyClosed) {
+            if (ctx.hasInFlightForChannel(operation.thread.id)) {
+                ctx.counters.closesDeferred++;
+                ctx.log?.info({ taskId: task.id, threadId: operation.thread.id }, 'task-sync:phase5 close deferred (in-flight reply active)');
+            }
+            else {
+                ctx.log?.info({ taskId: task.id, threadId: operation.thread.id }, 'task-sync:phase5 archived thread is stale, unarchiving to reconcile');
+                await closeTaskThread(ctx.client, operation.thread.id, task, ctx.tagMap, ctx.log);
+                state.threadsReconciled++;
+                ctx.log?.info({ taskId: task.id, threadId: operation.thread.id }, 'task-sync:phase5 reconciled (re-archived)');
+            }
+        }
+    }
+    catch (err) {
+        ctx.log?.warn({ err, taskId: task.id, threadId: operation.thread.id }, 'task-sync:phase5 archived reconcile failed');
+        ctx.counters.warnings++;
+    }
+}
+const RECONCILE_EXECUTORS = {
+    orphan: applyReconcileOrphanThread,
+    collision: applyReconcileCollision,
+    skip_external_ref_mismatch: applyReconcileSkipMismatch,
+    archive_active_closed: applyReconcileArchiveActiveClosed,
+    reconcile_archived_closed: applyReconcileArchivedClosed,
+};
+async function fetchPhase5ThreadSources(ctx) {
+    let activeThreads;
+    try {
+        const fetchedActive = await ctx.forum.threads.fetchActive();
+        activeThreads = fetchedActive.threads;
+    }
+    catch (err) {
+        ctx.log?.warn({ err }, 'task-sync:phase5 failed to fetch active threads');
+        ctx.counters.warnings++;
+        return null;
+    }
+    let archivedThreads = new Map();
+    try {
+        const fetchedArchived = await ctx.forum.threads.fetchArchived();
+        archivedThreads = new Map(fetchedArchived.threads);
+    }
+    catch (err) {
+        ctx.log?.warn({ err }, 'task-sync:phase5 failed to fetch archived threads');
+        ctx.counters.warnings++;
+    }
+    return { activeThreads, archivedThreads };
+}
+async function planPhase5ReconcileOperations(ctx, allTasks) {
+    const threadSources = await fetchPhase5ThreadSources(ctx);
+    if (!threadSources)
+        return null;
+    return planTaskReconcileFromThreadSources({
+        tasks: allTasks,
+        archivedThreads: threadSources.archivedThreads.values(),
+        activeThreads: threadSources.activeThreads.values(),
+        shortIdOfTaskId: shortTaskId,
+        shortIdFromThreadName: extractShortIdFromThreadName,
+        threadIdFromTask: getThreadIdFromTask,
+    });
+}
+async function applyPhase5ReconcileOperations(ctx, operations, state) {
+    for (const operation of operations) {
+        await RECONCILE_EXECUTORS[operation.action](ctx, operation, state);
+        await sleep(ctx.throttleMs);
+    }
+}
+async function applyPhase5ReconcileThreads(ctx, allTasks) {
+    const reconcileState = {
+        threadsReconciled: 0,
+        orphanThreadsFound: 0,
+    };
+    const plannedReconcileOps = await planPhase5ReconcileOperations(ctx, allTasks);
+    if (!plannedReconcileOps) {
+        return {
+            threadsReconciled: reconcileState.threadsReconciled,
+            orphanThreadsFound: reconcileState.orphanThreadsFound,
+        };
+    }
+    await applyPhase5ReconcileOperations(ctx, plannedReconcileOps, reconcileState);
+    return {
+        threadsReconciled: reconcileState.threadsReconciled,
+        orphanThreadsFound: reconcileState.orphanThreadsFound,
+    };
+}
+export async function applyTaskSyncExecutionPlan(ctx, applyPlan) {
+    for (const phasePlan of applyPlan.phasePlans) {
+        if (phasePlan.taskIds.length === 0)
+            continue;
+        await PHASE_EXECUTORS[phasePlan.phase](ctx, applyPlan.tasksById, phasePlan.taskIds);
+    }
+}
+export async function runTaskSyncReconcilePhase(ctx, allTasks, opts) {
+    if (opts?.skipPhase5) {
+        return { threadsReconciled: 0, orphanThreadsFound: 0 };
+    }
+    return applyPhase5ReconcileThreads(ctx, allTasks);
+}

package/dist/tasks/task-sync-cli.js

@@ -0,0 +1,89 @@
+import { TaskDiscordClientCtor, TaskDiscordGatewayIntentBits } from './discord-types.js';
+import { loadTagMap } from './tag-map.js';
+import { runTaskSync } from './task-sync-engine.js';
+import { resolveTaskDataLoadPath, resolveTaskDataPath } from './path-defaults.js';
+function env(name) {
+    const v = (process.env[name] ?? '').trim();
+    if (!v)
+        throw new Error(`${name} is required`);
+    return v;
+}
+function envOpt(name) {
+    const v = (process.env[name] ?? '').trim();
+    return v || undefined;
+}
+export function parseArgInt(args, name) {
+    const idx = args.indexOf(name);
+    if (idx < 0)
+        return undefined;
+    const v = args[idx + 1];
+    if (!v)
+        throw new Error(`${name} requires a value`);
+    const n = Number(v);
+    if (!Number.isFinite(n))
+        throw new Error(`${name} must be a number`);
+    return n;
+}
+/**
+ * Core sync execution — separated from Discord login/teardown so it can be
+ * unit-tested with mocked dependencies.
+ */
+export async function runTaskSyncWithStore(opts) {
+    return runTaskSync({
+        client: opts.client,
+        guild: opts.guild,
+        forumId: opts.forumId,
+        tagMap: opts.tagMap,
+        store: opts.store,
+        throttleMs: opts.throttleMs ?? 250,
+        archivedDedupeLimit: opts.archivedDedupeLimit ?? 200,
+        mentionUserId: opts.mentionUserId,
+    });
+}
+export async function runTaskSyncCliMain() {
+    const args = process.argv.slice(2);
+    const discordToken = env('DISCORD_TOKEN');
+    const guildId = env('DISCORD_GUILD_ID');
+    const forumId = env('DISCOCLAW_TASKS_FORUM');
+    const dataDir = envOpt('DISCOCLAW_DATA_DIR');
+    const tagMapPath = envOpt('DISCOCLAW_TASKS_TAG_MAP')
+        ?? resolveTaskDataPath(dataDir, 'tag-map.json');
+    const tasksPath = envOpt('DISCOCLAW_TASKS_PATH')
+        ?? await resolveTaskDataLoadPath(dataDir, 'tasks.jsonl')
+        ?? resolveTaskDataPath(dataDir, 'tasks.jsonl');
+    const throttleMs = parseArgInt(args, '--throttle-ms') ?? 250;
+    const archivedLimit = parseArgInt(args, '--archived-limit') ?? 200;
+    const { TaskStore: TaskStoreImpl } = await import('./store.js');
+    const store = new TaskStoreImpl(tasksPath ? { persistPath: tasksPath } : {});
+    if (tasksPath)
+        await store.load();
+    const client = new TaskDiscordClientCtor({ intents: [TaskDiscordGatewayIntentBits.Guilds] });
+    await client.login(discordToken);
+    await new Promise((resolve) => client.once('ready', () => resolve()));
+    try {
+        const guild = await client.guilds.fetch(guildId);
+        const tagMap = tagMapPath ? await loadTagMap(tagMapPath) : {};
+        const mentionUserId = envOpt('DISCOCLAW_TASKS_MENTION_USER');
+        const sidebarRaw = envOpt('DISCOCLAW_TASKS_SIDEBAR');
+        const sidebarEnabled = sidebarRaw === '1' || sidebarRaw?.toLowerCase() === 'true';
+        const sidebarMentionUserId = sidebarEnabled ? mentionUserId : undefined;
+        const result = await runTaskSyncWithStore({
+            client,
+            guild,
+            forumId,
+            tagMap,
+            store,
+            throttleMs,
+            archivedDedupeLimit: archivedLimit,
+            mentionUserId: sidebarMentionUserId,
+        });
+        process.stdout.write(JSON.stringify(result) + '\n');
+    }
+    finally {
+        client.destroy();
+    }
+}
+export const runSyncWithStore = runTaskSyncWithStore;
+if (import.meta.url === new URL(process.argv[1] ?? '', 'file:').href) {
+    await runTaskSyncCliMain();
+}

package/dist/tasks/task-sync-cli.test.js

@@ -0,0 +1,70 @@
+import { describe, expect, it, vi } from 'vitest';
+import { parseArgInt, runSyncWithStore, runTaskSyncWithStore } from './task-sync-cli.js';
+vi.mock('./task-sync-engine.js', () => {
+    const runTaskSync = vi.fn().mockResolvedValue({ created: 0, updated: 0, closed: 0 });
+    return { runTaskSync };
+});
+// task-sync-cli.ts uses an import.meta.url guard so that main() does NOT run
+// when the module is imported (only when invoked as a script). This lets us
+// import and test the exported helpers without triggering Discord connections
+// or env-var validation.
+describe('parseArgInt', () => {
+    it('keeps runSyncWithStore as an alias for runTaskSyncWithStore', () => {
+        expect(runSyncWithStore).toBe(runTaskSyncWithStore);
+    });
+    it('returns undefined when the flag is not in args', () => {
+        expect(parseArgInt(['--foo', '1'], '--bar')).toBeUndefined();
+    });
+    it('returns undefined for an empty args array', () => {
+        expect(parseArgInt([], '--throttle-ms')).toBeUndefined();
+    });
+    it('parses a positive integer', () => {
+        expect(parseArgInt(['--throttle-ms', '500'], '--throttle-ms')).toBe(500);
+    });
+    it('parses zero', () => {
+        expect(parseArgInt(['--throttle-ms', '0'], '--throttle-ms')).toBe(0);
+    });
+    it('parses a negative integer', () => {
+        expect(parseArgInt(['--limit', '-1'], '--limit')).toBe(-1);
+    });
+    it('parses a decimal value', () => {
+        expect(parseArgInt(['--throttle-ms', '2.5'], '--throttle-ms')).toBe(2.5);
+    });
+    it('finds the flag among mixed args', () => {
+        expect(parseArgInt(['--archived-limit', '200', '--throttle-ms', '100'], '--throttle-ms')).toBe(100);
+    });
+    it('returns the value for the first occurrence when the flag appears more than once', () => {
+        expect(parseArgInt(['--limit', '10', '--limit', '20'], '--limit')).toBe(10);
+    });
+    it('throws when the flag is present but no value follows', () => {
+        expect(() => parseArgInt(['--throttle-ms'], '--throttle-ms')).toThrow('--throttle-ms requires a value');
+    });
+    it('throws when the value is a non-numeric string', () => {
+        expect(() => parseArgInt(['--limit', 'abc'], '--limit')).toThrow('--limit must be a number');
+    });
+    it('throws when the value is "NaN"', () => {
+        expect(() => parseArgInt(['--limit', 'NaN'], '--limit')).toThrow('must be a number');
+    });
+    it('throws when the value is "Infinity"', () => {
+        expect(() => parseArgInt(['--limit', 'Infinity'], '--limit')).toThrow('must be a number');
+    });
+});
+describe('runSyncWithStore', () => {
+    it('passes store through to runTaskSync', async () => {
+        const { runTaskSync } = await import('./task-sync-engine.js');
+        const { TaskStore } = await import('./store.js');
+        const store = new TaskStore();
+        const fakeClient = {};
+        const fakeGuild = {};
+        await runSyncWithStore({
+            client: fakeClient,
+            guild: fakeGuild,
+            forumId: 'forum-123',
+            tagMap: {},
+            store,
+            throttleMs: 100,
+            archivedDedupeLimit: 50,
+        });
+        expect(runTaskSync).toHaveBeenCalledWith(expect.objectContaining({ store }));
+    });
+});