discoclaw 0.1.0

package/dist/discord/channel-context.js

@@ -0,0 +1,181 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+// pa-safety.md is retired from runtime loading: ROOT_POLICY now inlines the
+// injection-defence rules as an immutable preamble in every prompt.
+const PA_CONTEXT_MODULES = ['pa.md'];
+function parseChannelIndexMarkdown(md, channelsDir) {
+    // Parse rows like:
+    // | #gallery | 1234567890123456789 | `discord/gallery.md` | ... |
+    // We only need channel name + id + context file hint.
+    const out = new Map();
+    const lines = md.split(/\r?\n/);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('|'))
+            continue;
+        const cells = trimmed
+            .split('|')
+            .map((c) => c.trim())
+            .filter((c) => c.length > 0);
+        if (cells.length < 2)
+            continue;
+        const chanCell = cells[0] ?? '';
+        const idCell = cells[1] ?? '';
+        if (!chanCell.startsWith('#'))
+            continue;
+        if (!/^\d{17,20}$/.test(idCell))
+            continue;
+        const channelName = chanCell.replace(/^#+/, '').trim();
+        const channelId = idCell;
+        let contextPath = path.join(channelsDir, `${channelName}.md`);
+        const ctxCell = cells[2] ?? '';
+        // Prefer explicit context file mapping when present.
+        if (ctxCell && ctxCell !== '—' && ctxCell !== '-') {
+            const unquoted = ctxCell.replace(/`/g, '').trim();
+            const base = path.basename(unquoted);
+            if (base && base.toLowerCase().endsWith('.md')) {
+                contextPath = path.join(channelsDir, base);
+            }
+        }
+        out.set(channelId, { channelId, channelName, contextPath });
+    }
+    return out;
+}
+async function fileExists(p) {
+    try {
+        await fs.stat(p);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT')
+            return false;
+        throw err;
+    }
+}
+async function writeFileIfMissing(p, body) {
+    if (await fileExists(p))
+        return false;
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    await fs.writeFile(p, body, 'utf8');
+    return true;
+}
+function channelFileNameFromName(name) {
+    const safe = name.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
+    return (safe || 'channel') + '.md';
+}
+function channelContextTemplate(args) {
+    return [
+        `# #${args.channelName} Context`,
+        `Channel ID: ${args.channelId}`,
+        '',
+        'Channel-specific notes:',
+        '-',
+        '',
+    ].join('\n');
+}
+async function ensureDiscordIndexExists(indexPath) {
+    if (await fileExists(indexPath))
+        return;
+    await fs.mkdir(path.dirname(indexPath), { recursive: true });
+    const body = [
+        '# DISCORD.md - Channel Context Index',
+        '',
+        '| Channel | ID | Context File | Purpose |',
+        '|---------|----|--------------|---------|',
+        '',
+    ].join('\n');
+    await fs.writeFile(indexPath, body, 'utf8');
+}
+export async function ensureIndexedDiscordChannelContext(args) {
+    const existing = args.ctx.byChannelId.get(args.channelId);
+    if (existing)
+        return existing;
+    const channelName = (args.channelName ?? '').trim() || `channel-${args.channelId}`;
+    const fileName = channelFileNameFromName(channelName === `channel-${args.channelId}`
+        ? `channel-${args.channelId}`
+        : channelName);
+    const contextPath = path.join(args.ctx.channelsDir, fileName);
+    await ensureDiscordIndexExists(args.ctx.indexPath);
+    const row = `| #${channelName} | ${args.channelId} | \`discord/channels/${fileName}\` | — |`;
+    await fs.appendFile(args.ctx.indexPath, row + '\n', 'utf8');
+    const entry = { channelId: args.channelId, channelName, contextPath };
+    args.ctx.byChannelId.set(args.channelId, entry);
+    const didCreate = await writeFileIfMissing(contextPath, channelContextTemplate({
+        channelName,
+        channelId: args.channelId,
+    }));
+    if (didCreate) {
+        args.log?.info({ channelId: args.channelId, contextPath }, 'discord:context created placeholder for new channel');
+    }
+    return entry;
+}
+export async function validatePaContextModules(contextModulesDir) {
+    for (const mod of PA_CONTEXT_MODULES) {
+        const p = path.join(contextModulesDir, mod);
+        try {
+            await fs.access(p);
+        }
+        catch {
+            throw new Error(`Required PA context module not found: ${p}. ` +
+                `Ensure .context/${mod} exists in the repo root.`);
+        }
+    }
+}
+export async function loadDiscordChannelContext(opts) {
+    const contentDir = opts.contentDir;
+    const indexPath = path.join(contentDir, 'discord', 'DISCORD.md');
+    const channelsDir = path.join(contentDir, 'discord', 'channels');
+    const dmContextPath = path.join(channelsDir, 'dm.md');
+    const paContextFiles = PA_CONTEXT_MODULES.map((f) => path.join(opts.contextModulesDir, f));
+    await writeFileIfMissing(dmContextPath, channelContextTemplate({
+        channelName: 'dm',
+        channelId: 'dm',
+    }));
+    let md = '';
+    try {
+        md = await fs.readFile(indexPath, 'utf8');
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'ENOENT')
+            throw err;
+        opts.log?.warn({ indexPath }, 'discord:context index missing; using fallback only');
+        md = '';
+    }
+    const byChannelId = md ? parseChannelIndexMarkdown(md, channelsDir) : new Map();
+    // Guarantee that every indexed channel has a context file (create placeholders for missing).
+    let created = 0;
+    for (const entry of byChannelId.values()) {
+        const didCreate = await writeFileIfMissing(entry.contextPath, channelContextTemplate({
+            channelName: entry.channelName,
+            channelId: entry.channelId,
+        }));
+        if (didCreate)
+            created++;
+    }
+    if (created > 0) {
+        opts.log?.info({ created, channelsDir }, 'discord:context bootstrapped missing channel context files');
+    }
+    return {
+        contentDir,
+        indexPath,
+        paContextFiles,
+        channelsDir,
+        byChannelId,
+        dmContextPath,
+    };
+}
+export function resolveDiscordChannelContext(args) {
+    const ctx = args.ctx;
+    if (!ctx)
+        return { channelId: args.channelId };
+    if (args.isDm) {
+        return { channelId: args.channelId, channelName: 'dm', contextPath: ctx.dmContextPath };
+    }
+    const id = (args.threadParentId && args.threadParentId.trim()) ? args.threadParentId : args.channelId;
+    const hit = ctx.byChannelId.get(id);
+    if (hit)
+        return { channelId: id, channelName: hit.channelName, contextPath: hit.contextPath };
+    return { channelId: id, channelName: 'unknown' };
+}

package/dist/discord/defer-scheduler.js

@@ -0,0 +1,45 @@
+export class DeferScheduler {
+    activeCount = 0;
+    maxDelaySeconds;
+    maxConcurrent;
+    jobHandler;
+    constructor(opts) {
+        this.maxDelaySeconds = opts.maxDelaySeconds;
+        this.maxConcurrent = opts.maxConcurrent;
+        this.jobHandler = opts.jobHandler;
+    }
+    schedule(job) {
+        const delaySeconds = job.action.delaySeconds;
+        if (!Number.isFinite(delaySeconds)) {
+            return { ok: false, error: 'delaySeconds must be a number' };
+        }
+        if (delaySeconds <= 0) {
+            return { ok: false, error: 'delaySeconds must be greater than zero' };
+        }
+        if (delaySeconds > this.maxDelaySeconds) {
+            return {
+                ok: false,
+                error: `delaySeconds cannot exceed ${this.maxDelaySeconds} seconds`,
+            };
+        }
+        if (this.activeCount >= this.maxConcurrent) {
+            return {
+                ok: false,
+                error: `Maximum of ${this.maxConcurrent} deferred actions are already scheduled`,
+            };
+        }
+        this.activeCount++;
+        const runsAt = new Date(Date.now() + delaySeconds * 1000);
+        const delayMs = delaySeconds * 1000;
+        const invokeHandler = async () => {
+            try {
+                await Promise.resolve(this.jobHandler({ action: job.action, context: job.context, runsAt }));
+            }
+            finally {
+                this.activeCount = Math.max(0, this.activeCount - 1);
+            }
+        };
+        setTimeout(invokeHandler, delayMs);
+        return { ok: true, runsAt, delaySeconds };
+    }
+}

package/dist/discord/destructive-confirmation.js

@@ -0,0 +1,128 @@
+import crypto from 'node:crypto';
+const CONFIRM_TTL_MS = 10 * 60_000;
+const DESTRUCTIVE_ACTION_TYPES = new Set([
+    'channelDelete',
+    'forumTagDelete',
+    'deleteMessage',
+    'bulkDelete',
+    'eventDelete',
+    'timeout',
+    'kick',
+    'ban',
+]);
+const pendingByToken = new Map();
+const tokenByKey = new Map();
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return '[' + value.map((v) => stableStringify(v)).join(',') + ']';
+    }
+    const entries = Object.entries(value)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => JSON.stringify(k) + ':' + stableStringify(v));
+    return '{' + entries.join(',') + '}';
+}
+function actionFingerprint(action) {
+    return crypto
+        .createHash('sha256')
+        .update(stableStringify(action))
+        .digest('hex')
+        .slice(0, 12);
+}
+function makeKey(sessionKey, userId, fingerprint) {
+    return `${sessionKey}:${userId}:${fingerprint}`;
+}
+function randomToken() {
+    return crypto.randomBytes(4).toString('hex');
+}
+function uniqueRandomToken() {
+    let token = randomToken();
+    while (pendingByToken.has(token))
+        token = randomToken();
+    return token;
+}
+function purgeExpired(now = Date.now()) {
+    for (const [token, pending] of pendingByToken) {
+        if (pending.expiresAt > now)
+            continue;
+        pendingByToken.delete(token);
+        tokenByKey.delete(makeKey(pending.sessionKey, pending.userId, pending.actionFingerprint));
+    }
+}
+export function isDestructiveActionType(type) {
+    return DESTRUCTIVE_ACTION_TYPES.has(type);
+}
+export function requestDestructiveConfirmation(action, sessionKey, userId) {
+    purgeExpired();
+    const now = Date.now();
+    const fingerprint = actionFingerprint(action);
+    const key = makeKey(sessionKey, userId, fingerprint);
+    const existingToken = tokenByKey.get(key);
+    if (existingToken) {
+        const existing = pendingByToken.get(existingToken);
+        if (existing && existing.expiresAt > now) {
+            return existing;
+        }
+        tokenByKey.delete(key);
+        if (existingToken)
+            pendingByToken.delete(existingToken);
+    }
+    const token = uniqueRandomToken();
+    const pending = {
+        token,
+        sessionKey,
+        userId,
+        action,
+        actionType: action.type,
+        actionFingerprint: fingerprint,
+        createdAt: now,
+        expiresAt: now + CONFIRM_TTL_MS,
+    };
+    pendingByToken.set(token, pending);
+    tokenByKey.set(key, token);
+    return pending;
+}
+export function consumeDestructiveConfirmation(token, sessionKey, userId) {
+    purgeExpired();
+    const pending = pendingByToken.get(token);
+    if (!pending)
+        return null;
+    if (pending.sessionKey !== sessionKey)
+        return null;
+    if (pending.userId !== userId)
+        return null;
+    pendingByToken.delete(token);
+    tokenByKey.delete(makeKey(pending.sessionKey, pending.userId, pending.actionFingerprint));
+    return pending;
+}
+export function describeDestructiveConfirmationRequirement(action, confirmation) {
+    if (!isDestructiveActionType(action.type))
+        return { allow: true };
+    if (confirmation?.bypassDestructive)
+        return { allow: true };
+    if (confirmation?.mode !== 'interactive') {
+        return {
+            allow: false,
+            error: `Blocked destructive action "${action.type}": destructive actions require interactive user confirmation and are disabled in automated flows.`,
+        };
+    }
+    const sessionKey = confirmation.sessionKey?.trim();
+    const userId = confirmation.userId?.trim();
+    if (!sessionKey || !userId) {
+        return {
+            allow: false,
+            error: `Blocked destructive action "${action.type}": missing confirmation context.`,
+        };
+    }
+    const pending = requestDestructiveConfirmation(action, sessionKey, userId);
+    return {
+        allow: false,
+        error: `Destructive action "${action.type}" requires confirmation. Run \`!confirm ${pending.token}\` in this channel within 10 minutes to execute.`,
+    };
+}
+export function _resetDestructiveConfirmationForTest() {
+    pendingByToken.clear();
+    tokenByKey.clear();
+}

package/dist/discord/destructive-confirmation.test.js

@@ -0,0 +1,49 @@
+import crypto from 'node:crypto';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { _resetDestructiveConfirmationForTest as resetState, requestDestructiveConfirmation, consumeDestructiveConfirmation, describeDestructiveConfirmationRequirement, } from './destructive-confirmation.js';
+describe('destructive confirmation state', () => {
+    beforeEach(() => {
+        resetState();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('reuses token for the same action/session/user while pending', () => {
+        const action = { type: 'channelDelete', channelId: '123' };
+        const first = requestDestructiveConfirmation(action, 'discord:channel:1', 'u1');
+        const second = requestDestructiveConfirmation(action, 'discord:channel:1', 'u1');
+        expect(first.token).toBe(second.token);
+    });
+    it('consumes token only for matching session and user', () => {
+        const action = { type: 'channelDelete', channelId: '123' };
+        const pending = requestDestructiveConfirmation(action, 'discord:channel:1', 'u1');
+        expect(consumeDestructiveConfirmation(pending.token, 'discord:channel:2', 'u1')).toBeNull();
+        expect(consumeDestructiveConfirmation(pending.token, 'discord:channel:1', 'u2')).toBeNull();
+        const consumed = consumeDestructiveConfirmation(pending.token, 'discord:channel:1', 'u1');
+        expect(consumed?.actionType).toBe('channelDelete');
+        expect(consumeDestructiveConfirmation(pending.token, 'discord:channel:1', 'u1')).toBeNull();
+    });
+    it('blocks destructive actions in automated mode', () => {
+        const decision = describeDestructiveConfirmationRequirement({ type: 'ban', userId: '42' }, { mode: 'automated' });
+        expect(decision.allow).toBe(false);
+        if (decision.allow)
+            throw new Error('expected block');
+        expect(decision.error).toContain('disabled in automated flows');
+    });
+    it('allows non-destructive actions without confirmation metadata', () => {
+        const decision = describeDestructiveConfirmationRequirement({ type: 'channelList' }, undefined);
+        expect(decision).toEqual({ allow: true });
+    });
+    it('generates a different token when random token collides with a pending entry', () => {
+        const randomSpy = vi.spyOn(crypto, 'randomBytes');
+        randomSpy
+            .mockReturnValueOnce(Buffer.from('aaaaaaaa', 'hex'))
+            .mockReturnValueOnce(Buffer.from('aaaaaaaa', 'hex'))
+            .mockReturnValueOnce(Buffer.from('bbbbbbbb', 'hex'));
+        const first = requestDestructiveConfirmation({ type: 'channelDelete', channelId: 'c1' }, 'discord:channel:1', 'u1');
+        const second = requestDestructiveConfirmation({ type: 'ban', userId: '42' }, 'discord:channel:1', 'u1');
+        expect(first.token).toBe('aaaaaaaa');
+        expect(second.token).toBe('bbbbbbbb');
+        expect(first.token).not.toBe(second.token);
+    });
+});

package/dist/discord/discord-plan-auto-implement.test.js

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { buildPlanImplementationMessage, legacyPlanImplementationCta, } from './forge-commands.js';
+describe('buildPlanImplementationMessage', () => {
+    const planId = 'plan-123';
+    it('returns only the CTA when there is no skip reason', () => {
+        expect(buildPlanImplementationMessage(undefined, planId)).toBe(legacyPlanImplementationCta(planId));
+    });
+    it('appends the CTA when the skip reason does not already include it', () => {
+        const reason = 'Skipped auto-implementation because severity warnings remain.';
+        const message = buildPlanImplementationMessage(reason, planId);
+        expect(message).toBe(`${reason}\n\n${legacyPlanImplementationCta(planId)}`);
+    });
+    it('does not duplicate the CTA when the skip reason already contains it', () => {
+        const cta = legacyPlanImplementationCta(planId);
+        const reason = `Auto-implementation skipped.\n\n${cta}`;
+        expect(buildPlanImplementationMessage(reason, planId)).toBe(reason);
+    });
+});

package/dist/discord/durable-memory.js

@@ -0,0 +1,145 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+export const CURRENT_VERSION = 1;
+export function emptyStore() {
+    return { version: CURRENT_VERSION, updatedAt: Date.now(), items: [] };
+}
+function migrateStore(store) {
+    // Migration blocks run first, then the unknown-version guard.
+    // Future migrations follow the run-stats.ts pattern:
+    //   if ((store as any).version === 1) { /* transform fields */; store.version = 2; }
+    if (store.version !== CURRENT_VERSION) {
+        // Unrecognized (future) version — caller will create a fresh store.
+        return null;
+    }
+    return store;
+}
+function safeUserId(userId) {
+    if (!/^[a-zA-Z0-9_-]+$/.test(userId)) {
+        throw new Error(`Invalid userId for durable memory path: ${userId}`);
+    }
+    return userId;
+}
+export async function loadDurableMemory(dir, userId) {
+    const filePath = path.join(dir, `${safeUserId(userId)}.json`);
+    try {
+        const raw = await fs.readFile(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed &&
+            typeof parsed === 'object' &&
+            'version' in parsed &&
+            'items' in parsed &&
+            Array.isArray(parsed.items)) {
+            return migrateStore(parsed) ?? emptyStore();
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveDurableMemory(dir, userId, store) {
+    await fs.mkdir(dir, { recursive: true });
+    const filePath = path.join(dir, `${safeUserId(userId)}.json`);
+    const tmp = `${filePath}.tmp.${process.pid}`;
+    await fs.writeFile(tmp, JSON.stringify(store, null, 2) + '\n', 'utf8');
+    await fs.rename(tmp, filePath);
+}
+export function deriveItemId(kind, text) {
+    const normalized = kind + ':' + text.trim().toLowerCase().replace(/\s+/g, ' ');
+    return 'durable-' + crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 8);
+}
+export function addItem(store, text, source, maxItems, kind = 'fact') {
+    const now = Date.now();
+    const id = deriveItemId(kind, text);
+    const existing = store.items.find((item) => item.id === id && item.status === 'active');
+    if (existing) {
+        existing.kind = kind;
+        existing.text = text;
+        existing.source = source;
+        existing.updatedAt = now;
+        store.updatedAt = now;
+        return store;
+    }
+    const item = {
+        id,
+        kind,
+        text,
+        tags: [],
+        status: 'active',
+        source,
+        createdAt: now,
+        updatedAt: now,
+    };
+    store.items.push(item);
+    store.updatedAt = now;
+    // Enforce maxItems cap.
+    while (store.items.length > maxItems) {
+        // Drop oldest deprecated first.
+        const deprecatedIdx = store.items
+            .map((it, i) => ({ it, i }))
+            .filter(({ it }) => it.status === 'deprecated')
+            .sort((a, b) => a.it.updatedAt - b.it.updatedAt)[0];
+        if (deprecatedIdx) {
+            store.items.splice(deprecatedIdx.i, 1);
+        }
+        else {
+            // Drop oldest active.
+            const activeIdx = store.items
+                .map((it, i) => ({ it, i }))
+                .filter(({ it }) => it.status === 'active')
+                .sort((a, b) => a.it.updatedAt - b.it.updatedAt)[0];
+            if (activeIdx) {
+                store.items.splice(activeIdx.i, 1);
+            }
+            else {
+                break;
+            }
+        }
+    }
+    return store;
+}
+export function deprecateItems(store, substring) {
+    const now = Date.now();
+    const needle = substring.toLowerCase();
+    let deprecatedCount = 0;
+    for (const item of store.items) {
+        if (item.status !== 'active')
+            continue;
+        // Match if substring covers >= 60% of item's text length.
+        const textLower = item.text.toLowerCase();
+        if (textLower.includes(needle) && needle.length >= item.text.length * 0.6) {
+            item.status = 'deprecated';
+            item.updatedAt = now;
+            deprecatedCount++;
+        }
+    }
+    if (deprecatedCount > 0)
+        store.updatedAt = now;
+    return { store, deprecatedCount };
+}
+export function selectItemsForInjection(store, maxChars) {
+    const active = store.items
+        .filter((item) => item.status === 'active')
+        .sort((a, b) => b.updatedAt - a.updatedAt);
+    const selected = [];
+    let chars = 0;
+    for (const item of active) {
+        const lineLen = formatItemLine(item).length;
+        const sep = selected.length > 0 ? 1 : 0; // \n between items
+        if (chars + sep + lineLen > maxChars)
+            continue;
+        selected.push(item);
+        chars += sep + lineLen;
+    }
+    return selected;
+}
+function formatItemLine(item) {
+    const date = new Date(item.updatedAt).toISOString().slice(0, 10);
+    const ch = item.source.channelName ? `, #${item.source.channelName}` : '';
+    return `- [${item.kind}] ${item.text} (src: ${item.source.type}${ch}, updated ${date})`;
+}
+export function formatDurableSection(items) {
+    return items.map(formatItemLine).join('\n');
+}