discoclaw 0.1.0

package/dist/cron/tag-map.test.js

@@ -0,0 +1,64 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import fs from 'node:fs/promises';
+import { loadCronTagMapStrict, reloadCronTagMapInPlace } from './tag-map.js';
+vi.mock('node:fs/promises');
+const mockReadFile = vi.mocked(fs.readFile);
+describe('loadCronTagMapStrict', () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+    });
+    it('parses valid tag map', async () => {
+        mockReadFile.mockResolvedValue(JSON.stringify({ monitoring: 'tag-1', daily: 'tag-2' }));
+        const result = await loadCronTagMapStrict('/tmp/tags.json');
+        expect(result).toEqual({ monitoring: 'tag-1', daily: 'tag-2' });
+    });
+    it('throws on invalid JSON', async () => {
+        mockReadFile.mockResolvedValue('not json {{{');
+        await expect(loadCronTagMapStrict('/tmp/tags.json')).rejects.toThrow();
+    });
+    it('throws on array', async () => {
+        mockReadFile.mockResolvedValue(JSON.stringify(['a', 'b']));
+        await expect(loadCronTagMapStrict('/tmp/tags.json')).rejects.toThrow('must be a JSON object');
+    });
+    it('throws on null', async () => {
+        mockReadFile.mockResolvedValue(JSON.stringify(null));
+        await expect(loadCronTagMapStrict('/tmp/tags.json')).rejects.toThrow('must be a JSON object');
+    });
+    it('throws on number', async () => {
+        mockReadFile.mockResolvedValue(JSON.stringify(42));
+        await expect(loadCronTagMapStrict('/tmp/tags.json')).rejects.toThrow('must be a JSON object');
+    });
+    it('throws on non-string value', async () => {
+        mockReadFile.mockResolvedValue(JSON.stringify({ monitoring: 123 }));
+        await expect(loadCronTagMapStrict('/tmp/tags.json')).rejects.toThrow('must be a string');
+    });
+    it('throws on read error', async () => {
+        mockReadFile.mockRejectedValue(new Error('ENOENT'));
+        await expect(loadCronTagMapStrict('/tmp/tags.json')).rejects.toThrow('ENOENT');
+    });
+});
+describe('reloadCronTagMapInPlace', () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+    });
+    it('mutates existing map in-place and returns new count', async () => {
+        mockReadFile.mockResolvedValue(JSON.stringify({ a: '1', b: '2', c: '3' }));
+        const tagMap = { old: 'val' };
+        const count = await reloadCronTagMapInPlace('/tmp/tags.json', tagMap);
+        expect(count).toBe(3);
+        expect(tagMap).toEqual({ a: '1', b: '2', c: '3' });
+        expect(tagMap).not.toHaveProperty('old');
+    });
+    it('preserves existing map on read failure', async () => {
+        mockReadFile.mockRejectedValue(new Error('ENOENT'));
+        const tagMap = { existing: 'val' };
+        await expect(reloadCronTagMapInPlace('/tmp/tags.json', tagMap)).rejects.toThrow('ENOENT');
+        expect(tagMap).toEqual({ existing: 'val' });
+    });
+    it('preserves existing map on validation failure', async () => {
+        mockReadFile.mockResolvedValue(JSON.stringify({ good: 'ok', bad: 123 }));
+        const tagMap = { existing: 'val' };
+        await expect(reloadCronTagMapInPlace('/tmp/tags.json', tagMap)).rejects.toThrow('must be a string');
+        expect(tagMap).toEqual({ existing: 'val' });
+    });
+});

package/dist/cron/types.js

@@ -0,0 +1 @@
+export {};

package/dist/discoclaw-plan-format.test.js

@@ -0,0 +1,137 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const REPO_ROOT = path.join(__dirname, '..');
+const REQUIRED_HEADINGS = [
+    '# DiscoClaw Plan',
+    '## Metadata',
+    '## Use Case',
+    '## Scope',
+    '## Integration Contract',
+    '## Implementation Steps',
+    '## Acceptance Tests',
+    '## Risk, Permissions, Rollback',
+    '## Handoff Prompt (Consumer Agent)',
+    '## Changelog',
+];
+const REQUIRED_METADATA_KEYS = [
+    'spec_version',
+    'plan_id',
+    'title',
+    'author',
+    'source',
+    'license',
+    'created_at',
+    'integration_type',
+    'discoclaw_min_version',
+    'risk_level',
+];
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function stripQuotes(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1).trim();
+    }
+    return trimmed;
+}
+function parseFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---\n/);
+    if (!match)
+        return {};
+    const lines = match[1].split('\n');
+    const out = {};
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const idx = trimmed.indexOf(':');
+        if (idx <= 0)
+            continue;
+        const key = trimmed.slice(0, idx).trim();
+        const value = stripQuotes(trimmed.slice(idx + 1));
+        out[key] = value;
+    }
+    return out;
+}
+function headingCount(content, heading) {
+    const re = new RegExp(`^${escapeRegExp(heading)}$`, 'gm');
+    return [...content.matchAll(re)].length;
+}
+function getSection(content, heading) {
+    const escaped = escapeRegExp(heading);
+    const re = new RegExp(`^${escaped}\\n([\\s\\S]*?)(?=^## |\\Z)`, 'm');
+    const match = content.match(re);
+    return (match?.[1] ?? '').trim();
+}
+async function findPlanFiles(dir) {
+    const results = [];
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...(await findPlanFiles(full)));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.discoclaw-plan.md')) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+async function loadPlanFiles() {
+    const plansDir = path.join(REPO_ROOT, 'plans');
+    const planFiles = await findPlanFiles(plansDir);
+    return [
+        path.join(REPO_ROOT, 'templates', 'plans', 'integration.discoclaw-plan.md'),
+        ...planFiles,
+    ];
+}
+describe('discoclaw-plan format', () => {
+    it('enforces frontmatter metadata, required headings, and risk-gated contract rules', async () => {
+        const files = await loadPlanFiles();
+        expect(files.length).toBeGreaterThan(1);
+        for (const filePath of files) {
+            const content = await fs.readFile(filePath, 'utf-8');
+            const metadata = parseFrontmatter(content);
+            for (const key of REQUIRED_METADATA_KEYS) {
+                expect(metadata[key], `${path.relative(REPO_ROOT, filePath)} missing frontmatter key: ${key}`).toBeTruthy();
+            }
+            expect(metadata.spec_version, `${path.relative(REPO_ROOT, filePath)} invalid spec_version`).toBe('1.0');
+            expect(['runtime', 'actions', 'context']).toContain(metadata.integration_type);
+            expect(['low', 'medium', 'high']).toContain(metadata.risk_level);
+            for (const heading of REQUIRED_HEADINGS) {
+                expect(headingCount(content, heading), `${path.relative(REPO_ROOT, filePath)} heading count for ${heading}`).toBe(1);
+            }
+            const isTemplate = path.relative(REPO_ROOT, filePath) === 'templates/plans/integration.discoclaw-plan.md';
+            if (!isTemplate) {
+                const expectedPlanId = path.basename(filePath, '.discoclaw-plan.md');
+                expect(metadata.plan_id, `${path.relative(REPO_ROOT, filePath)} plan_id should match filename`).toBe(expectedPlanId);
+            }
+            const integrationSection = getSection(content, '## Integration Contract');
+            const acceptanceSection = getSection(content, '## Acceptance Tests');
+            const hasIntegrationJson = integrationSection.includes('```json');
+            const hasAcceptanceJson = acceptanceSection.includes('```json');
+            if (metadata.risk_level === 'low') {
+                if (!hasIntegrationJson) {
+                    expect(integrationSection).toMatch(/Files to add:/);
+                    expect(integrationSection).toMatch(/Files to modify:/);
+                    expect(integrationSection).toMatch(/Environment changes:/);
+                    expect(integrationSection).toMatch(/Runtime behavior changes:/);
+                    expect(integrationSection).toMatch(/Out of scope:/);
+                }
+                if (!hasAcceptanceJson) {
+                    expect(acceptanceSection).toMatch(/Scenarios:/);
+                    expect(acceptanceSection).toMatch(/Required checks:/);
+                }
+            }
+            else {
+                expect(hasIntegrationJson, `${path.relative(REPO_ROOT, filePath)} medium/high plan missing integration JSON`).toBe(true);
+                expect(hasAcceptanceJson, `${path.relative(REPO_ROOT, filePath)} medium/high plan missing acceptance JSON`).toBe(true);
+            }
+        }
+    });
+});

package/dist/discoclaw-recipe-format.test.js

@@ -0,0 +1,137 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const REPO_ROOT = path.join(__dirname, '..');
+const REQUIRED_HEADINGS = [
+    '# DiscoClaw Recipe',
+    '## Metadata',
+    '## Use Case',
+    '## Scope',
+    '## Integration Contract',
+    '## Implementation Steps',
+    '## Acceptance Tests',
+    '## Risk, Permissions, Rollback',
+    '## Handoff Prompt (Consumer Agent)',
+    '## Changelog',
+];
+const REQUIRED_METADATA_KEYS = [
+    'spec_version',
+    'plan_id',
+    'title',
+    'author',
+    'source',
+    'license',
+    'created_at',
+    'integration_type',
+    'discoclaw_min_version',
+    'risk_level',
+];
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function stripQuotes(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1).trim();
+    }
+    return trimmed;
+}
+function parseFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---\n/);
+    if (!match)
+        return {};
+    const lines = match[1].split('\n');
+    const out = {};
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const idx = trimmed.indexOf(':');
+        if (idx <= 0)
+            continue;
+        const key = trimmed.slice(0, idx).trim();
+        const value = stripQuotes(trimmed.slice(idx + 1));
+        out[key] = value;
+    }
+    return out;
+}
+function headingCount(content, heading) {
+    const re = new RegExp(`^${escapeRegExp(heading)}$`, 'gm');
+    return [...content.matchAll(re)].length;
+}
+function getSection(content, heading) {
+    const escaped = escapeRegExp(heading);
+    const re = new RegExp(`^${escaped}\\n([\\s\\S]*?)(?=^## |\\Z)`, 'm');
+    const match = content.match(re);
+    return (match?.[1] ?? '').trim();
+}
+async function findRecipeFiles(dir) {
+    const results = [];
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...(await findRecipeFiles(full)));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.discoclaw-recipe.md')) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+async function loadRecipeFiles() {
+    const recipesDir = path.join(REPO_ROOT, 'recipes');
+    const recipeFiles = await findRecipeFiles(recipesDir);
+    return [
+        path.join(REPO_ROOT, 'templates', 'recipes', 'integration.discoclaw-recipe.md'),
+        ...recipeFiles,
+    ];
+}
+describe('discoclaw-recipe format', () => {
+    it('enforces frontmatter metadata, required headings, and risk-gated contract rules', async () => {
+        const files = await loadRecipeFiles();
+        expect(files.length).toBeGreaterThan(1);
+        for (const filePath of files) {
+            const content = await fs.readFile(filePath, 'utf-8');
+            const metadata = parseFrontmatter(content);
+            for (const key of REQUIRED_METADATA_KEYS) {
+                expect(metadata[key], `${path.relative(REPO_ROOT, filePath)} missing frontmatter key: ${key}`).toBeTruthy();
+            }
+            expect(metadata.spec_version, `${path.relative(REPO_ROOT, filePath)} invalid spec_version`).toBe('1.0');
+            expect(['runtime', 'actions', 'context']).toContain(metadata.integration_type);
+            expect(['low', 'medium', 'high']).toContain(metadata.risk_level);
+            for (const heading of REQUIRED_HEADINGS) {
+                expect(headingCount(content, heading), `${path.relative(REPO_ROOT, filePath)} heading count for ${heading}`).toBe(1);
+            }
+            const isTemplate = path.relative(REPO_ROOT, filePath) === 'templates/recipes/integration.discoclaw-recipe.md';
+            if (!isTemplate) {
+                const expectedPlanId = path.basename(filePath, '.discoclaw-recipe.md');
+                expect(metadata.plan_id, `${path.relative(REPO_ROOT, filePath)} plan_id should match filename`).toBe(expectedPlanId);
+            }
+            const integrationSection = getSection(content, '## Integration Contract');
+            const acceptanceSection = getSection(content, '## Acceptance Tests');
+            const hasIntegrationJson = integrationSection.includes('```json');
+            const hasAcceptanceJson = acceptanceSection.includes('```json');
+            if (metadata.risk_level === 'low') {
+                if (!hasIntegrationJson) {
+                    expect(integrationSection).toMatch(/Files to add:/);
+                    expect(integrationSection).toMatch(/Files to modify:/);
+                    expect(integrationSection).toMatch(/Environment changes:/);
+                    expect(integrationSection).toMatch(/Runtime behavior changes:/);
+                    expect(integrationSection).toMatch(/Out of scope:/);
+                }
+                if (!hasAcceptanceJson) {
+                    expect(acceptanceSection).toMatch(/Scenarios:/);
+                    expect(acceptanceSection).toMatch(/Required checks:/);
+                }
+            }
+            else {
+                expect(hasIntegrationJson, `${path.relative(REPO_ROOT, filePath)} medium/high plan missing integration JSON`).toBe(true);
+                expect(hasAcceptanceJson, `${path.relative(REPO_ROOT, filePath)} medium/high plan missing acceptance JSON`).toBe(true);
+            }
+        }
+    });
+});

package/dist/discord/abort-registry.js

@@ -0,0 +1,70 @@
+// In-memory registry mapping Discord message IDs to AbortController instances.
+// Supports a short-lived cooldown window after disposal so that stale 🛑 taps
+// on recently-finished messages are silently consumed rather than forwarded.
+const COOLDOWN_MS = 15_000;
+const active = new Map();
+const cooldown = new Set();
+/**
+ * Register an AbortController for a message that is about to start streaming.
+ *
+ * Returns:
+ * - `signal` — pass to RuntimeInvokeParams.signal
+ * - `dispose` — call when the stream ends; moves the entry into a cooldown
+ *   set so that a belated 🛑 tap is silently consumed for ~15 s.
+ */
+export function registerAbort(messageId) {
+    const controller = new AbortController();
+    active.set(messageId, controller);
+    function dispose() {
+        active.delete(messageId);
+        cooldown.add(messageId);
+        setTimeout(() => cooldown.delete(messageId), COOLDOWN_MS);
+    }
+    return { signal: controller.signal, dispose };
+}
+/**
+ * Attempt to abort the stream for a message.
+ *
+ * Returns:
+ * - `true` and fires `abort()` if the message is actively streaming.
+ * - `true` (no-op) if the message is in the cooldown window (already finished).
+ * - `false` if the message ID is unknown — caller should let the reaction through.
+ */
+export function tryAbort(messageId) {
+    const controller = active.get(messageId);
+    if (controller) {
+        controller.abort();
+        return true;
+    }
+    if (cooldown.has(messageId)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Returns true if the message is actively streaming (abort not yet fired).
+ * Use this to distinguish an active abort from a cooldown no-op before calling tryAbort.
+ */
+export function isActivelyStreaming(messageId) {
+    return active.has(messageId);
+}
+/**
+ * Abort all active streams.
+ *
+ * Returns the number of streams that were actively streaming and aborted.
+ * Does not modify the active/cooldown sets — each stream's `dispose()` call
+ * (in its finally block) handles cleanup and cooldown the same way as a
+ * single-message abort via `tryAbort`.
+ */
+export function tryAbortAll() {
+    const controllers = [...active.values()];
+    for (const controller of controllers) {
+        controller.abort();
+    }
+    return controllers.length;
+}
+/** Clear all state. Only for use in tests. */
+export function _resetForTest() {
+    active.clear();
+    cooldown.clear();
+}

package/dist/discord/action-categories.js

@@ -0,0 +1,36 @@
+// Action types that return data Claude likely wants to process (read-only queries).
+// When any of these succeed, the auto-follow-up loop re-invokes Claude with the results.
+export const QUERY_ACTION_TYPES = new Set([
+    // Channels
+    'channelList',
+    'channelInfo',
+    'threadListArchived',
+    'forumTagList',
+    // Messaging
+    'readMessages',
+    'fetchMessage',
+    'listPins',
+    // Guild
+    'memberInfo',
+    'roleInfo',
+    'searchMessages',
+    'eventList',
+    // Tasks
+    'taskList',
+    'taskShow',
+    // Crons
+    'cronList',
+    'cronShow',
+    // Plans
+    'planList',
+    'planShow',
+    // Memory
+    'memoryShow',
+    // Config
+    'modelShow',
+    // Forge
+    'forgeStatus',
+]);
+export function hasQueryAction(actionTypes) {
+    return actionTypes.some((t) => QUERY_ACTION_TYPES.has(t));
+}

package/dist/discord/action-types.js

@@ -0,0 +1 @@
+export {};

package/dist/discord/action-utils.js

@@ -0,0 +1,58 @@
+import { ChannelType } from 'discord.js';
+/**
+ * Resolve a channel reference to a text-based guild channel.
+ * Accepts:
+ *   - A numeric channel ID string (e.g. "123456789")
+ *   - A channel name with or without # prefix (e.g. "#general" or "general")
+ */
+export function resolveChannel(guild, ref) {
+    const cleaned = ref.replace(/^#/, '').trim();
+    if (!cleaned)
+        return undefined;
+    // Try by ID first (numeric strings).
+    const byId = guild.channels.cache.get(cleaned);
+    if (byId) {
+        // If the ID matched but isn't text-based, don't fall through to name lookup —
+        // the caller explicitly referenced this channel by ID.
+        return isTextBased(byId) ? byId : undefined;
+    }
+    // Try by name (case-insensitive).
+    const byName = guild.channels.cache.find((ch) => isTextBased(ch) && ch.name.toLowerCase() === cleaned.toLowerCase());
+    return byName;
+}
+function isTextBased(ch) {
+    // We only want channels that are meaningfully sendable via `.send()`.
+    return (ch.type === ChannelType.GuildText ||
+        ch.type === ChannelType.GuildAnnouncement ||
+        ch.type === ChannelType.PublicThread ||
+        ch.type === ChannelType.PrivateThread ||
+        ch.type === ChannelType.AnnouncementThread);
+}
+/** Human-readable channel type name for error messages. */
+export function describeChannelType(ch) {
+    switch (ch?.type) {
+        case ChannelType.GuildForum: return 'forum';
+        case ChannelType.GuildMedia: return 'media';
+        case ChannelType.GuildVoice: return 'voice';
+        case ChannelType.GuildStageVoice: return 'stage';
+        case ChannelType.GuildCategory: return 'category';
+        default: return 'unsupported';
+    }
+}
+/**
+ * Look up a channel by ref (ID or name) and return it raw, without filtering
+ * by type. Returns undefined only if the channel truly doesn't exist.
+ */
+export function findChannelRaw(guild, ref) {
+    const cleaned = ref.replace(/^#/, '').trim();
+    if (!cleaned)
+        return undefined;
+    const byId = guild.channels.cache.get(cleaned);
+    if (byId)
+        return byId;
+    return guild.channels.cache.find((ch) => ch.name.toLowerCase() === cleaned.toLowerCase());
+}
+/** Format a timestamp for display. */
+export function fmtTime(date) {
+    return date.toISOString().replace('T', ' ').slice(0, 19) + ' UTC';
+}

package/dist/discord/action-utils.test.js

@@ -0,0 +1,58 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ChannelType } from 'discord.js';
+import { resolveChannel, findChannelRaw, describeChannelType } from './action-utils.js';
+function makeGuild(channels) {
+    return {
+        channels: {
+            cache: {
+                get: vi.fn((id) => channels.find((c) => String(c.id) === String(id))),
+                find: vi.fn((pred) => channels.find((c) => pred(c))),
+            },
+        },
+    };
+}
+describe('resolveChannel', () => {
+    it('does not treat voice channels as sendable targets', () => {
+        const voice = { id: '123', name: 'voice', type: ChannelType.GuildVoice };
+        const guild = makeGuild([voice]);
+        const out = resolveChannel(guild, '123');
+        expect(out).toBeUndefined();
+        expect(guild.channels.cache.find).not.toHaveBeenCalled();
+    });
+    it('does not resolve forum channels by name', () => {
+        const forum = { id: 'f1', name: 'general', type: ChannelType.GuildForum };
+        const text = { id: 't1', name: 'other', type: ChannelType.GuildText, send: vi.fn() };
+        const guild = makeGuild([forum, text]);
+        const out = resolveChannel(guild, 'general');
+        expect(out).toBeUndefined();
+    });
+});
+describe('findChannelRaw', () => {
+    it('finds a forum channel by ID', () => {
+        const forum = { id: '123', name: 'beads', type: ChannelType.GuildForum };
+        const guild = makeGuild([forum]);
+        const out = findChannelRaw(guild, '123');
+        expect(out).toBe(forum);
+    });
+    it('finds a forum channel by name', () => {
+        const forum = { id: '123', name: 'beads', type: ChannelType.GuildForum };
+        const guild = makeGuild([forum]);
+        const out = findChannelRaw(guild, 'beads');
+        expect(out).toBe(forum);
+    });
+    it('returns undefined for nonexistent channel', () => {
+        const guild = makeGuild([]);
+        expect(findChannelRaw(guild, '999')).toBeUndefined();
+    });
+});
+describe('describeChannelType', () => {
+    it('returns "forum" for forum channels', () => {
+        expect(describeChannelType({ type: ChannelType.GuildForum })).toBe('forum');
+    });
+    it('returns "voice" for voice channels', () => {
+        expect(describeChannelType({ type: ChannelType.GuildVoice })).toBe('voice');
+    });
+    it('returns "unsupported" for unknown types', () => {
+        expect(describeChannelType({ type: 999 })).toBe('unsupported');
+    });
+});

package/dist/discord/actions-beads.js

@@ -0,0 +1 @@
+export { TASK_ACTION_TYPES as BEAD_ACTION_TYPES, executeTaskAction as executeBeadAction, taskActionsPromptSection as beadActionsPromptSection, } from './actions-tasks.js';