create-ironclaws 1.0.0

package/template/src/routing.test.ts

@@ -0,0 +1,170 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+
+import { _initTestDatabase, storeChatMetadata } from './db.js';
+import { getAvailableGroups, _setRegisteredGroups } from './index.js';
+
+beforeEach(() => {
+  _initTestDatabase();
+  _setRegisteredGroups({});
+});
+
+// --- JID ownership patterns ---
+
+describe('JID ownership patterns', () => {
+  // These test the patterns that will become ownsJid() on the Channel interface
+
+  it('WhatsApp group JID: ends with @g.us', () => {
+    const jid = '12345678@g.us';
+    expect(jid.endsWith('@g.us')).toBe(true);
+  });
+
+  it('WhatsApp DM JID: ends with @s.whatsapp.net', () => {
+    const jid = '12345678@s.whatsapp.net';
+    expect(jid.endsWith('@s.whatsapp.net')).toBe(true);
+  });
+});
+
+// --- getAvailableGroups ---
+
+describe('getAvailableGroups', () => {
+  it('returns only groups, excludes DMs', () => {
+    storeChatMetadata(
+      'group1@g.us',
+      '2024-01-01T00:00:01.000Z',
+      'Group 1',
+      'whatsapp',
+      true,
+    );
+    storeChatMetadata(
+      'user@s.whatsapp.net',
+      '2024-01-01T00:00:02.000Z',
+      'User DM',
+      'whatsapp',
+      false,
+    );
+    storeChatMetadata(
+      'group2@g.us',
+      '2024-01-01T00:00:03.000Z',
+      'Group 2',
+      'whatsapp',
+      true,
+    );
+
+    const groups = getAvailableGroups();
+    expect(groups).toHaveLength(2);
+    expect(groups.map((g) => g.jid)).toContain('group1@g.us');
+    expect(groups.map((g) => g.jid)).toContain('group2@g.us');
+    expect(groups.map((g) => g.jid)).not.toContain('user@s.whatsapp.net');
+  });
+
+  it('excludes __group_sync__ sentinel', () => {
+    storeChatMetadata('__group_sync__', '2024-01-01T00:00:00.000Z');
+    storeChatMetadata(
+      'group@g.us',
+      '2024-01-01T00:00:01.000Z',
+      'Group',
+      'whatsapp',
+      true,
+    );
+
+    const groups = getAvailableGroups();
+    expect(groups).toHaveLength(1);
+    expect(groups[0].jid).toBe('group@g.us');
+  });
+
+  it('marks registered groups correctly', () => {
+    storeChatMetadata(
+      'reg@g.us',
+      '2024-01-01T00:00:01.000Z',
+      'Registered',
+      'whatsapp',
+      true,
+    );
+    storeChatMetadata(
+      'unreg@g.us',
+      '2024-01-01T00:00:02.000Z',
+      'Unregistered',
+      'whatsapp',
+      true,
+    );
+
+    _setRegisteredGroups({
+      'reg@g.us': {
+        name: 'Registered',
+        folder: 'registered',
+        trigger: '@Andy',
+        added_at: '2024-01-01T00:00:00.000Z',
+      },
+    });
+
+    const groups = getAvailableGroups();
+    const reg = groups.find((g) => g.jid === 'reg@g.us');
+    const unreg = groups.find((g) => g.jid === 'unreg@g.us');
+
+    expect(reg?.isRegistered).toBe(true);
+    expect(unreg?.isRegistered).toBe(false);
+  });
+
+  it('returns groups ordered by most recent activity', () => {
+    storeChatMetadata(
+      'old@g.us',
+      '2024-01-01T00:00:01.000Z',
+      'Old',
+      'whatsapp',
+      true,
+    );
+    storeChatMetadata(
+      'new@g.us',
+      '2024-01-01T00:00:05.000Z',
+      'New',
+      'whatsapp',
+      true,
+    );
+    storeChatMetadata(
+      'mid@g.us',
+      '2024-01-01T00:00:03.000Z',
+      'Mid',
+      'whatsapp',
+      true,
+    );
+
+    const groups = getAvailableGroups();
+    expect(groups[0].jid).toBe('new@g.us');
+    expect(groups[1].jid).toBe('mid@g.us');
+    expect(groups[2].jid).toBe('old@g.us');
+  });
+
+  it('excludes non-group chats regardless of JID format', () => {
+    // Unknown JID format stored without is_group should not appear
+    storeChatMetadata(
+      'unknown-format-123',
+      '2024-01-01T00:00:01.000Z',
+      'Unknown',
+    );
+    // Explicitly non-group with unusual JID
+    storeChatMetadata(
+      'custom:abc',
+      '2024-01-01T00:00:02.000Z',
+      'Custom DM',
+      'custom',
+      false,
+    );
+    // A real group for contrast
+    storeChatMetadata(
+      'group@g.us',
+      '2024-01-01T00:00:03.000Z',
+      'Group',
+      'whatsapp',
+      true,
+    );
+
+    const groups = getAvailableGroups();
+    expect(groups).toHaveLength(1);
+    expect(groups[0].jid).toBe('group@g.us');
+  });
+
+  it('returns empty array when no chats exist', () => {
+    const groups = getAvailableGroups();
+    expect(groups).toHaveLength(0);
+  });
+});

package/template/src/sender-allowlist.test.ts

@@ -0,0 +1,216 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  isSenderAllowed,
+  isTriggerAllowed,
+  loadSenderAllowlist,
+  SenderAllowlistConfig,
+  shouldDropMessage,
+} from './sender-allowlist.js';
+
+let tmpDir: string;
+
+function cfgPath(name = 'sender-allowlist.json'): string {
+  return path.join(tmpDir, name);
+}
+
+function writeConfig(config: unknown, name?: string): string {
+  const p = cfgPath(name);
+  fs.writeFileSync(p, JSON.stringify(config));
+  return p;
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'allowlist-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe('loadSenderAllowlist', () => {
+  it('returns allow-all defaults when file is missing', () => {
+    const cfg = loadSenderAllowlist(cfgPath());
+    expect(cfg.default.allow).toBe('*');
+    expect(cfg.default.mode).toBe('trigger');
+    expect(cfg.logDenied).toBe(true);
+  });
+
+  it('loads allow=* config', () => {
+    const p = writeConfig({
+      default: { allow: '*', mode: 'trigger' },
+      chats: {},
+      logDenied: false,
+    });
+    const cfg = loadSenderAllowlist(p);
+    expect(cfg.default.allow).toBe('*');
+    expect(cfg.logDenied).toBe(false);
+  });
+
+  it('loads allow=[] (deny all)', () => {
+    const p = writeConfig({
+      default: { allow: [], mode: 'trigger' },
+      chats: {},
+    });
+    const cfg = loadSenderAllowlist(p);
+    expect(cfg.default.allow).toEqual([]);
+  });
+
+  it('loads allow=[list]', () => {
+    const p = writeConfig({
+      default: { allow: ['alice', 'bob'], mode: 'drop' },
+      chats: {},
+    });
+    const cfg = loadSenderAllowlist(p);
+    expect(cfg.default.allow).toEqual(['alice', 'bob']);
+    expect(cfg.default.mode).toBe('drop');
+  });
+
+  it('per-chat override beats default', () => {
+    const p = writeConfig({
+      default: { allow: '*', mode: 'trigger' },
+      chats: { 'group-a': { allow: ['alice'], mode: 'drop' } },
+    });
+    const cfg = loadSenderAllowlist(p);
+    expect(cfg.chats['group-a'].allow).toEqual(['alice']);
+    expect(cfg.chats['group-a'].mode).toBe('drop');
+  });
+
+  it('returns allow-all on invalid JSON', () => {
+    const p = cfgPath();
+    fs.writeFileSync(p, '{ not valid json }}}');
+    const cfg = loadSenderAllowlist(p);
+    expect(cfg.default.allow).toBe('*');
+  });
+
+  it('returns allow-all on invalid schema', () => {
+    const p = writeConfig({ default: { oops: true } });
+    const cfg = loadSenderAllowlist(p);
+    expect(cfg.default.allow).toBe('*');
+  });
+
+  it('rejects non-string allow array items', () => {
+    const p = writeConfig({
+      default: { allow: [123, null, true], mode: 'trigger' },
+      chats: {},
+    });
+    const cfg = loadSenderAllowlist(p);
+    expect(cfg.default.allow).toBe('*'); // falls back to default
+  });
+
+  it('skips invalid per-chat entries', () => {
+    const p = writeConfig({
+      default: { allow: '*', mode: 'trigger' },
+      chats: {
+        good: { allow: ['alice'], mode: 'trigger' },
+        bad: { allow: 123 },
+      },
+    });
+    const cfg = loadSenderAllowlist(p);
+    expect(cfg.chats['good']).toBeDefined();
+    expect(cfg.chats['bad']).toBeUndefined();
+  });
+});
+
+describe('isSenderAllowed', () => {
+  it('allow=* allows any sender', () => {
+    const cfg: SenderAllowlistConfig = {
+      default: { allow: '*', mode: 'trigger' },
+      chats: {},
+      logDenied: true,
+    };
+    expect(isSenderAllowed('g1', 'anyone', cfg)).toBe(true);
+  });
+
+  it('allow=[] denies any sender', () => {
+    const cfg: SenderAllowlistConfig = {
+      default: { allow: [], mode: 'trigger' },
+      chats: {},
+      logDenied: true,
+    };
+    expect(isSenderAllowed('g1', 'anyone', cfg)).toBe(false);
+  });
+
+  it('allow=[list] allows exact match only', () => {
+    const cfg: SenderAllowlistConfig = {
+      default: { allow: ['alice', 'bob'], mode: 'trigger' },
+      chats: {},
+      logDenied: true,
+    };
+    expect(isSenderAllowed('g1', 'alice', cfg)).toBe(true);
+    expect(isSenderAllowed('g1', 'eve', cfg)).toBe(false);
+  });
+
+  it('uses per-chat entry over default', () => {
+    const cfg: SenderAllowlistConfig = {
+      default: { allow: '*', mode: 'trigger' },
+      chats: { g1: { allow: ['alice'], mode: 'trigger' } },
+      logDenied: true,
+    };
+    expect(isSenderAllowed('g1', 'bob', cfg)).toBe(false);
+    expect(isSenderAllowed('g2', 'bob', cfg)).toBe(true);
+  });
+});
+
+describe('shouldDropMessage', () => {
+  it('returns false for trigger mode', () => {
+    const cfg: SenderAllowlistConfig = {
+      default: { allow: '*', mode: 'trigger' },
+      chats: {},
+      logDenied: true,
+    };
+    expect(shouldDropMessage('g1', cfg)).toBe(false);
+  });
+
+  it('returns true for drop mode', () => {
+    const cfg: SenderAllowlistConfig = {
+      default: { allow: '*', mode: 'drop' },
+      chats: {},
+      logDenied: true,
+    };
+    expect(shouldDropMessage('g1', cfg)).toBe(true);
+  });
+
+  it('per-chat mode override', () => {
+    const cfg: SenderAllowlistConfig = {
+      default: { allow: '*', mode: 'trigger' },
+      chats: { g1: { allow: '*', mode: 'drop' } },
+      logDenied: true,
+    };
+    expect(shouldDropMessage('g1', cfg)).toBe(true);
+    expect(shouldDropMessage('g2', cfg)).toBe(false);
+  });
+});
+
+describe('isTriggerAllowed', () => {
+  it('allows trigger for allowed sender', () => {
+    const cfg: SenderAllowlistConfig = {
+      default: { allow: ['alice'], mode: 'trigger' },
+      chats: {},
+      logDenied: false,
+    };
+    expect(isTriggerAllowed('g1', 'alice', cfg)).toBe(true);
+  });
+
+  it('denies trigger for disallowed sender', () => {
+    const cfg: SenderAllowlistConfig = {
+      default: { allow: ['alice'], mode: 'trigger' },
+      chats: {},
+      logDenied: false,
+    };
+    expect(isTriggerAllowed('g1', 'eve', cfg)).toBe(false);
+  });
+
+  it('logs when logDenied is true', () => {
+    const cfg: SenderAllowlistConfig = {
+      default: { allow: ['alice'], mode: 'trigger' },
+      chats: {},
+      logDenied: true,
+    };
+    isTriggerAllowed('g1', 'eve', cfg);
+    // Logger.debug is called — we just verify no crash; logger is a real pino instance
+  });
+});

package/template/src/sender-allowlist.ts

@@ -0,0 +1,128 @@
+import fs from 'fs';
+
+import { SENDER_ALLOWLIST_PATH } from './config.js';
+import { logger } from './logger.js';
+
+export interface ChatAllowlistEntry {
+  allow: '*' | string[];
+  mode: 'trigger' | 'drop';
+}
+
+export interface SenderAllowlistConfig {
+  default: ChatAllowlistEntry;
+  chats: Record<string, ChatAllowlistEntry>;
+  logDenied: boolean;
+}
+
+const DEFAULT_CONFIG: SenderAllowlistConfig = {
+  default: { allow: '*', mode: 'trigger' },
+  chats: {},
+  logDenied: true,
+};
+
+function isValidEntry(entry: unknown): entry is ChatAllowlistEntry {
+  if (!entry || typeof entry !== 'object') return false;
+  const e = entry as Record<string, unknown>;
+  const validAllow =
+    e.allow === '*' ||
+    (Array.isArray(e.allow) && e.allow.every((v) => typeof v === 'string'));
+  const validMode = e.mode === 'trigger' || e.mode === 'drop';
+  return validAllow && validMode;
+}
+
+export function loadSenderAllowlist(
+  pathOverride?: string,
+): SenderAllowlistConfig {
+  const filePath = pathOverride ?? SENDER_ALLOWLIST_PATH;
+
+  let raw: string;
+  try {
+    raw = fs.readFileSync(filePath, 'utf-8');
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return DEFAULT_CONFIG;
+    logger.warn(
+      { err, path: filePath },
+      'sender-allowlist: cannot read config',
+    );
+    return DEFAULT_CONFIG;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    logger.warn({ path: filePath }, 'sender-allowlist: invalid JSON');
+    return DEFAULT_CONFIG;
+  }
+
+  const obj = parsed as Record<string, unknown>;
+
+  if (!isValidEntry(obj.default)) {
+    logger.warn(
+      { path: filePath },
+      'sender-allowlist: invalid or missing default entry',
+    );
+    return DEFAULT_CONFIG;
+  }
+
+  const chats: Record<string, ChatAllowlistEntry> = {};
+  if (obj.chats && typeof obj.chats === 'object') {
+    for (const [jid, entry] of Object.entries(
+      obj.chats as Record<string, unknown>,
+    )) {
+      if (isValidEntry(entry)) {
+        chats[jid] = entry;
+      } else {
+        logger.warn(
+          { jid, path: filePath },
+          'sender-allowlist: skipping invalid chat entry',
+        );
+      }
+    }
+  }
+
+  return {
+    default: obj.default as ChatAllowlistEntry,
+    chats,
+    logDenied: obj.logDenied !== false,
+  };
+}
+
+function getEntry(
+  chatJid: string,
+  cfg: SenderAllowlistConfig,
+): ChatAllowlistEntry {
+  return cfg.chats[chatJid] ?? cfg.default;
+}
+
+export function isSenderAllowed(
+  chatJid: string,
+  sender: string,
+  cfg: SenderAllowlistConfig,
+): boolean {
+  const entry = getEntry(chatJid, cfg);
+  if (entry.allow === '*') return true;
+  return entry.allow.includes(sender);
+}
+
+export function shouldDropMessage(
+  chatJid: string,
+  cfg: SenderAllowlistConfig,
+): boolean {
+  return getEntry(chatJid, cfg).mode === 'drop';
+}
+
+export function isTriggerAllowed(
+  chatJid: string,
+  sender: string,
+  cfg: SenderAllowlistConfig,
+): boolean {
+  const allowed = isSenderAllowed(chatJid, sender, cfg);
+  if (!allowed && cfg.logDenied) {
+    logger.debug(
+      { chatJid, sender },
+      'sender-allowlist: trigger denied for sender',
+    );
+  }
+  return allowed;
+}

package/template/src/task-scheduler.test.ts

@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { _initTestDatabase, createTask, getTaskById } from './db.js';
+import {
+  _resetSchedulerLoopForTests,
+  computeNextRun,
+  startSchedulerLoop,
+} from './task-scheduler.js';
+
+describe('task scheduler', () => {
+  beforeEach(() => {
+    _initTestDatabase();
+    _resetSchedulerLoopForTests();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('pauses due tasks with invalid group folders to prevent retry churn', async () => {
+    createTask({
+      id: 'task-invalid-folder',
+      group_folder: '../../outside',
+      chat_jid: 'bad@g.us',
+      prompt: 'run',
+      schedule_type: 'once',
+      schedule_value: '2026-02-22T00:00:00.000Z',
+      context_mode: 'isolated',
+      next_run: new Date(Date.now() - 60_000).toISOString(),
+      status: 'active',
+      created_at: '2026-02-22T00:00:00.000Z',
+    });
+
+    const enqueueTask = vi.fn(
+      (_groupJid: string, _taskId: string, fn: () => Promise<void>) => {
+        void fn();
+      },
+    );
+
+    startSchedulerLoop({
+      registeredGroups: () => ({}),
+      getSessions: () => ({}),
+      queue: { enqueueTask } as any,
+      onProcess: () => {},
+      sendMessage: async () => {},
+    });
+
+    await vi.advanceTimersByTimeAsync(10);
+
+    const task = getTaskById('task-invalid-folder');
+    expect(task?.status).toBe('paused');
+  });
+
+  it('computeNextRun anchors interval tasks to scheduled time to prevent drift', () => {
+    const scheduledTime = new Date(Date.now() - 2000).toISOString(); // 2s ago
+    const task = {
+      id: 'drift-test',
+      group_folder: 'test',
+      chat_jid: 'test@g.us',
+      prompt: 'test',
+      schedule_type: 'interval' as const,
+      schedule_value: '60000', // 1 minute
+      context_mode: 'isolated' as const,
+      next_run: scheduledTime,
+      last_run: null,
+      last_result: null,
+      status: 'active' as const,
+      created_at: '2026-01-01T00:00:00.000Z',
+    };
+
+    const nextRun = computeNextRun(task);
+    expect(nextRun).not.toBeNull();
+
+    // Should be anchored to scheduledTime + 60s, NOT Date.now() + 60s
+    const expected = new Date(scheduledTime).getTime() + 60000;
+    expect(new Date(nextRun!).getTime()).toBe(expected);
+  });
+
+  it('computeNextRun returns null for once-tasks', () => {
+    const task = {
+      id: 'once-test',
+      group_folder: 'test',
+      chat_jid: 'test@g.us',
+      prompt: 'test',
+      schedule_type: 'once' as const,
+      schedule_value: '2026-01-01T00:00:00.000Z',
+      context_mode: 'isolated' as const,
+      next_run: new Date(Date.now() - 1000).toISOString(),
+      last_run: null,
+      last_result: null,
+      status: 'active' as const,
+      created_at: '2026-01-01T00:00:00.000Z',
+    };
+
+    expect(computeNextRun(task)).toBeNull();
+  });
+
+  it('computeNextRun skips missed intervals without infinite loop', () => {
+    // Task was due 10 intervals ago (missed)
+    const ms = 60000;
+    const missedBy = ms * 10;
+    const scheduledTime = new Date(Date.now() - missedBy).toISOString();
+
+    const task = {
+      id: 'skip-test',
+      group_folder: 'test',
+      chat_jid: 'test@g.us',
+      prompt: 'test',
+      schedule_type: 'interval' as const,
+      schedule_value: String(ms),
+      context_mode: 'isolated' as const,
+      next_run: scheduledTime,
+      last_run: null,
+      last_result: null,
+      status: 'active' as const,
+      created_at: '2026-01-01T00:00:00.000Z',
+    };
+
+    const nextRun = computeNextRun(task);
+    expect(nextRun).not.toBeNull();
+    // Must be in the future
+    expect(new Date(nextRun!).getTime()).toBeGreaterThan(Date.now());
+    // Must be aligned to the original schedule grid
+    const offset =
+      (new Date(nextRun!).getTime() - new Date(scheduledTime).getTime()) % ms;
+    expect(offset).toBe(0);
+  });
+});