discoclaw 0.1.0

package/dist/logging/logger-like.js

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

package/dist/observability/memory-sampler.js

@@ -0,0 +1,51 @@
+export class MemorySampler {
+    rssHwm = 0;
+    heapUsedHwm = 0;
+    count = 0;
+    source;
+    constructor(source = process.memoryUsage) {
+        this.source = source;
+    }
+    /** Take a sample and update high-water marks. Returns current stats. */
+    sample() {
+        const usage = this.source();
+        this.count++;
+        if (usage.rss > this.rssHwm)
+            this.rssHwm = usage.rss;
+        if (usage.heapUsed > this.heapUsedHwm)
+            this.heapUsedHwm = usage.heapUsed;
+        return this.current(usage);
+    }
+    /** Read current stats without updating counters or HWMs. */
+    peek() {
+        return this.current(this.source());
+    }
+    /** Reset high-water marks and sample count. */
+    reset() {
+        this.rssHwm = 0;
+        this.heapUsedHwm = 0;
+        this.count = 0;
+    }
+    current(usage) {
+        return {
+            rssBytes: usage.rss,
+            heapUsedBytes: usage.heapUsed,
+            heapTotalBytes: usage.heapTotal,
+            externalBytes: usage.external,
+            rssHwmBytes: Math.max(this.rssHwm, usage.rss),
+            heapUsedHwmBytes: Math.max(this.heapUsedHwm, usage.heapUsed),
+            sampleCount: this.count,
+        };
+    }
+}
+/** Format bytes as a human-readable MiB string, e.g. "42.1 MiB" */
+export function formatMiB(bytes) {
+    return `${(bytes / 1024 / 1024).toFixed(1)} MiB`;
+}
+/** Render a one-line memory summary suitable for `!health verbose`. */
+export function renderMemoryLine(stats) {
+    return (`Memory: rss=${formatMiB(stats.rssBytes)} heapUsed=${formatMiB(stats.heapUsedBytes)}` +
+        ` heapTotal=${formatMiB(stats.heapTotalBytes)}` +
+        ` hwm(rss=${formatMiB(stats.rssHwmBytes)} heap=${formatMiB(stats.heapUsedHwmBytes)})` +
+        ` samples=${stats.sampleCount}`);
+}

package/dist/observability/memory-sampler.test.js

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest';
+import { MemorySampler, formatMiB, renderMemoryLine } from './memory-sampler.js';
+function makeSource(values) {
+    let idx = 0;
+    return () => {
+        const v = values[Math.min(idx++, values.length - 1)];
+        return { rss: 0, heapUsed: 0, heapTotal: 0, external: 0, arrayBuffers: 0, ...v };
+    };
+}
+describe('MemorySampler', () => {
+    it('returns current values from a single sample', () => {
+        const sampler = new MemorySampler(makeSource([{ rss: 100, heapUsed: 50, heapTotal: 80, external: 5 }]));
+        const stats = sampler.sample();
+        expect(stats.rssBytes).toBe(100);
+        expect(stats.heapUsedBytes).toBe(50);
+        expect(stats.heapTotalBytes).toBe(80);
+        expect(stats.externalBytes).toBe(5);
+        expect(stats.sampleCount).toBe(1);
+    });
+    it('tracks high-water marks across multiple samples', () => {
+        const sampler = new MemorySampler(makeSource([
+            { rss: 100, heapUsed: 50 },
+            { rss: 200, heapUsed: 30 },
+            { rss: 150, heapUsed: 80 },
+        ]));
+        sampler.sample();
+        sampler.sample();
+        const stats = sampler.sample();
+        expect(stats.rssHwmBytes).toBe(200);
+        expect(stats.heapUsedHwmBytes).toBe(80);
+        expect(stats.sampleCount).toBe(3);
+    });
+    it('hwm equals current value when current exceeds prior hwm', () => {
+        const sampler = new MemorySampler(makeSource([
+            { rss: 100, heapUsed: 50 },
+            { rss: 300, heapUsed: 200 },
+        ]));
+        sampler.sample();
+        const stats = sampler.sample();
+        expect(stats.rssHwmBytes).toBe(300);
+        expect(stats.heapUsedHwmBytes).toBe(200);
+    });
+    it('peek does not increment sample count or update hwm', () => {
+        const sampler = new MemorySampler(makeSource([
+            { rss: 100, heapUsed: 50 },
+            { rss: 999, heapUsed: 999 },
+        ]));
+        sampler.sample();
+        const peeked = sampler.peek();
+        expect(peeked.sampleCount).toBe(1);
+        // HWM should reflect sample (100/50), not the peek value (999/999)
+        expect(peeked.rssHwmBytes).toBe(999);
+        expect(peeked.heapUsedHwmBytes).toBe(999);
+        // But internal hwm state remains at 100/50 — verify via another sample
+        const sampler2 = new MemorySampler(makeSource([{ rss: 100, heapUsed: 50 }]));
+        sampler2.sample();
+        const after = sampler2.peek();
+        expect(after.sampleCount).toBe(1);
+    });
+    it('reset clears hwm and count', () => {
+        const sampler = new MemorySampler(makeSource([
+            { rss: 500, heapUsed: 300 },
+            { rss: 10, heapUsed: 5 },
+        ]));
+        sampler.sample();
+        sampler.reset();
+        const stats = sampler.sample();
+        expect(stats.rssHwmBytes).toBe(10);
+        expect(stats.heapUsedHwmBytes).toBe(5);
+        expect(stats.sampleCount).toBe(1);
+    });
+});
+describe('formatMiB', () => {
+    it('formats bytes to one decimal MiB', () => {
+        expect(formatMiB(1024 * 1024)).toBe('1.0 MiB');
+        expect(formatMiB(1.5 * 1024 * 1024)).toBe('1.5 MiB');
+        expect(formatMiB(0)).toBe('0.0 MiB');
+    });
+});
+describe('renderMemoryLine', () => {
+    it('produces a correctly formatted line', () => {
+        const line = renderMemoryLine({
+            rssBytes: 50 * 1024 * 1024,
+            heapUsedBytes: 30 * 1024 * 1024,
+            heapTotalBytes: 40 * 1024 * 1024,
+            externalBytes: 2 * 1024 * 1024,
+            rssHwmBytes: 60 * 1024 * 1024,
+            heapUsedHwmBytes: 35 * 1024 * 1024,
+            sampleCount: 12,
+        });
+        expect(line).toBe('Memory: rss=50.0 MiB heapUsed=30.0 MiB heapTotal=40.0 MiB hwm(rss=60.0 MiB heap=35.0 MiB) samples=12');
+    });
+});

package/dist/observability/metrics.js

@@ -0,0 +1,88 @@
+function percentile(values, p) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const idx = Math.min(sorted.length - 1, Math.max(0, Math.floor((sorted.length - 1) * p)));
+    return Math.round(sorted[idx] * 100) / 100;
+}
+function classifyError(message) {
+    const msg = String(message ?? '').toLowerCase();
+    if (!msg)
+        return 'unknown';
+    if (msg.includes('timed out'))
+        return 'timeout';
+    if (msg.includes('missing permissions') || msg.includes('missing access'))
+        return 'discord_permissions';
+    if (msg.includes('unauthorized') || msg.includes('auth'))
+        return 'auth';
+    if (msg.includes('stream stall'))
+        return 'stream_stall';
+    return 'other';
+}
+export class MetricsRegistry {
+    startedAtMs = Date.now();
+    counters = new Map();
+    latencies = {
+        message: [],
+        reaction: [],
+        cron: [],
+    };
+    maxLatencySamples = 400;
+    memorySampler;
+    setMemorySampler(sampler) {
+        this.memorySampler = sampler;
+    }
+    increment(name, value = 1) {
+        const next = (this.counters.get(name) ?? 0) + value;
+        this.counters.set(name, next);
+    }
+    recordInvokeStart(flow) {
+        this.increment(`invoke.${flow}.started`);
+    }
+    recordInvokeResult(flow, ms, ok, errorMessage) {
+        this.increment(`invoke.${flow}.${ok ? 'succeeded' : 'failed'}`);
+        this.pushLatency(flow, ms);
+        if (!ok) {
+            this.increment(`invoke.${flow}.error_class.${classifyError(errorMessage)}`);
+        }
+    }
+    recordActionResult(ok) {
+        this.increment(`actions.${ok ? 'succeeded' : 'failed'}`);
+    }
+    snapshot() {
+        const counters = {};
+        for (const [k, v] of this.counters.entries())
+            counters[k] = v;
+        const snap = {
+            startedAt: this.startedAtMs,
+            counters,
+            latencies: {
+                message: this.latencySummary('message'),
+                reaction: this.latencySummary('reaction'),
+                cron: this.latencySummary('cron'),
+            },
+        };
+        if (this.memorySampler) {
+            snap.memory = this.memorySampler.peek();
+        }
+        return snap;
+    }
+    pushLatency(flow, ms) {
+        const arr = this.latencies[flow];
+        arr.push(Math.max(0, ms));
+        if (arr.length > this.maxLatencySamples) {
+            arr.shift();
+        }
+    }
+    latencySummary(flow) {
+        const values = this.latencies[flow];
+        const maxMs = values.length > 0 ? Math.max(...values) : 0;
+        return {
+            count: values.length,
+            p50Ms: percentile(values, 0.5),
+            p95Ms: percentile(values, 0.95),
+            maxMs: Math.round(maxMs * 100) / 100,
+        };
+    }
+}
+export const globalMetrics = new MetricsRegistry();

package/dist/observability/metrics.test.js

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { MetricsRegistry } from './metrics.js';
+describe('MetricsRegistry', () => {
+    it('tracks invoke counters and latency summaries', () => {
+        const m = new MetricsRegistry();
+        m.recordInvokeStart('message');
+        m.recordInvokeResult('message', 100, true);
+        m.recordInvokeResult('message', 200, false, 'timed out');
+        const snap = m.snapshot();
+        expect(snap.counters['invoke.message.started']).toBe(1);
+        expect(snap.counters['invoke.message.succeeded']).toBe(1);
+        expect(snap.counters['invoke.message.failed']).toBe(1);
+        expect(snap.counters['invoke.message.error_class.timeout']).toBe(1);
+        expect(snap.latencies.message.count).toBe(2);
+        expect(snap.latencies.message.maxMs).toBe(200);
+        expect(snap.latencies.reaction.count).toBe(0);
+    });
+    it('classifies stream stall errors as stream_stall', () => {
+        const m = new MetricsRegistry();
+        m.recordInvokeResult('message', 120000, false, 'stream stall: no output for 120000ms');
+        const snap = m.snapshot();
+        expect(snap.counters['invoke.message.error_class.stream_stall']).toBe(1);
+    });
+    it('includes memory stats when a memory sampler is configured', () => {
+        const m = new MetricsRegistry();
+        m.setMemorySampler({
+            peek: () => ({
+                rssBytes: 1,
+                heapUsedBytes: 2,
+                heapTotalBytes: 3,
+                externalBytes: 4,
+                rssHwmBytes: 5,
+                heapUsedHwmBytes: 6,
+                sampleCount: 7,
+            }),
+        });
+        const snap = m.snapshot();
+        expect(snap.memory).toBeDefined();
+        expect(snap.memory?.rssBytes).toBe(1);
+        expect(snap.memory?.sampleCount).toBe(7);
+    });
+});

package/dist/onboarding/onboarding-flow.js

@@ -0,0 +1,246 @@
+/**
+ * OnboardingFlow — pure conversation state machine for interactive onboarding.
+ *
+ * No file I/O. Tracks current step, collected values, and returns reply text.
+ * The caller (discord.ts) handles sending messages and invoking the writer.
+ */
+const MAX_INPUT_LENGTH = 200;
+const PLACEHOLDER_RE = /\{\{[^}]+\}\}/;
+/** Common timezone abbreviations mapped to IANA names. */
+const TIMEZONE_ABBR = {
+    PST: 'America/Los_Angeles',
+    PDT: 'America/Los_Angeles',
+    MST: 'America/Denver',
+    MDT: 'America/Denver',
+    CST: 'America/Chicago',
+    CDT: 'America/Chicago',
+    EST: 'America/New_York',
+    EDT: 'America/New_York',
+    GMT: 'Etc/GMT',
+    UTC: 'UTC',
+    CET: 'Europe/Paris',
+    CEST: 'Europe/Paris',
+    BST: 'Europe/London',
+    IST: 'Asia/Kolkata',
+    JST: 'Asia/Tokyo',
+    AEST: 'Australia/Sydney',
+    AEDT: 'Australia/Sydney',
+    NZST: 'Pacific/Auckland',
+    NZDT: 'Pacific/Auckland',
+};
+function parseTimezone(input) {
+    const trimmed = input.trim();
+    const abbr = TIMEZONE_ABBR[trimmed.toUpperCase()];
+    if (abbr)
+        return abbr;
+    try {
+        Intl.DateTimeFormat(undefined, { timeZone: trimmed });
+        return trimmed;
+    }
+    catch {
+        return null;
+    }
+}
+function parseCheckin(input) {
+    const t = input.trim().toLowerCase();
+    if (['yes', 'y', 'yeah', 'yep', 'sure', 'ok', '1', 'true'].includes(t))
+        return true;
+    if (['no', 'n', 'nope', 'nah', '0', 'false'].includes(t))
+        return false;
+    return null;
+}
+const FIELD_DEFS = [
+    { label: 'Your name', key: 'userName' },
+    { label: 'Timezone', key: 'timezone' },
+    { label: 'Morning check-in', key: 'morningCheckin' },
+];
+const CONFIRM_YES = new Set(['yes', 'y', 'ok', 'confirm', 'looks good']);
+export class OnboardingFlow {
+    step = 'NAME';
+    values = {};
+    writeError = '';
+    /** When true, completing any field returns to CONFIRM instead of advancing. */
+    editing = false;
+    /** Updated on start() and handleInput(). Used for timeout checking. */
+    lastActivityTimestamp = 0;
+    /** Tracks whether the redirect notice has been sent this session. */
+    hasRedirected = false;
+    /** Where the conversation is happening. */
+    channelMode = 'dm';
+    /** Guild channel ID when channelMode is 'guild'. */
+    channelId;
+    start(displayName) {
+        this.lastActivityTimestamp = Date.now();
+        return {
+            done: false,
+            reply: `Hey ${displayName}! Quick setup — just 3 questions.\n\n` +
+                `**What's your name?**`,
+        };
+    }
+    handleInput(text) {
+        this.lastActivityTimestamp = Date.now();
+        const input = text.trim();
+        if (this.step === 'WRITING') {
+            return { done: false, reply: 'Hang on, still writing your files...' };
+        }
+        if (this.step === 'DONE') {
+            return { done: true, reply: '' };
+        }
+        if (this.step === 'WRITE_ERROR') {
+            return this.handleWriteError(input);
+        }
+        if (this.step === 'CONFIRM') {
+            return this.handleConfirm(input);
+        }
+        // All question steps require input
+        if (!input) {
+            return { done: false, reply: "I need something here — what would you like?" };
+        }
+        if (input.length > MAX_INPUT_LENGTH) {
+            return { done: false, reply: `That's a bit long — can you keep it under ${MAX_INPUT_LENGTH} characters?` };
+        }
+        if (PLACEHOLDER_RE.test(input)) {
+            return { done: false, reply: "That looks like a template placeholder — give me something real!" };
+        }
+        switch (this.step) {
+            case 'NAME':
+                this.values.userName = input;
+                if (this.editing)
+                    return this.finishEdit();
+                this.step = 'TIMEZONE';
+                return {
+                    done: false,
+                    reply: `Nice to meet you, ${input}!\n\n` +
+                        `**What timezone are you in?**\n` +
+                        `Use an IANA name like \`America/New_York\`, or an abbreviation like \`EST\`, \`PST\`, \`CET\`.`,
+                };
+            case 'TIMEZONE': {
+                const tz = parseTimezone(input);
+                if (!tz) {
+                    return {
+                        done: false,
+                        reply: "I didn't recognize that timezone. Try an IANA name like `America/New_York`, " +
+                            "or an abbreviation like `EST`, `PST`, `CET`.",
+                    };
+                }
+                this.values.timezone = tz;
+                if (this.editing)
+                    return this.finishEdit();
+                this.step = 'CHECKIN';
+                return {
+                    done: false,
+                    reply: `**Would you like a morning check-in message each day?** (yes / no)`,
+                };
+            }
+            case 'CHECKIN': {
+                const checkin = parseCheckin(input);
+                if (checkin === null) {
+                    return {
+                        done: false,
+                        reply: "Just yes or no — would you like a morning check-in message?",
+                    };
+                }
+                this.values.morningCheckin = checkin;
+                if (this.editing)
+                    return this.finishEdit();
+                return this.showConfirmation();
+            }
+            default:
+                return { done: false, reply: '' };
+        }
+    }
+    markWriteComplete() {
+        this.step = 'DONE';
+    }
+    markWriteFailed(error) {
+        this.step = 'WRITE_ERROR';
+        this.writeError = error;
+    }
+    getValues() {
+        return this.values;
+    }
+    getValuesWithDefaults(displayName, systemTimezone) {
+        return {
+            userName: this.values.userName ?? displayName,
+            timezone: this.values.timezone ?? systemTimezone,
+            morningCheckin: this.values.morningCheckin ?? false,
+        };
+    }
+    showConfirmation() {
+        this.step = 'CONFIRM';
+        const lines = FIELD_DEFS.map((f, i) => {
+            const val = this.values[f.key];
+            let display;
+            if (val === undefined || val === null) {
+                display = '(unanswered)';
+            }
+            else if (typeof val === 'boolean') {
+                display = val ? 'Yes' : 'No';
+            }
+            else {
+                display = String(val);
+            }
+            return `${i + 1}. **${f.label}:** ${display}`;
+        });
+        return {
+            done: false,
+            reply: `Here's what I've got:\n\n` +
+                lines.join('\n') +
+                `\n\nType **yes** to confirm, or pick a number to edit a field.`,
+        };
+    }
+    handleConfirm(input) {
+        if (!input) {
+            return { done: false, reply: `Type 'yes' to confirm, or pick a number (1-${FIELD_DEFS.length}) to edit a field.` };
+        }
+        if (CONFIRM_YES.has(input.toLowerCase())) {
+            this.step = 'WRITING';
+            return { done: false, reply: 'Writing your files...', writeResult: 'pending' };
+        }
+        const num = parseInt(input, 10);
+        if (!isNaN(num) && num >= 1 && num <= FIELD_DEFS.length) {
+            return this.reaskField(FIELD_DEFS[num - 1].key);
+        }
+        return { done: false, reply: `Type 'yes' to confirm, or pick a number (1-${FIELD_DEFS.length}) to edit a field.` };
+    }
+    handleWriteError(input) {
+        const t = input.toLowerCase();
+        if (t === 'yes' || t === 'retry') {
+            this.step = 'WRITING';
+            return { done: false, reply: 'Retrying...', writeResult: 'pending' };
+        }
+        const num = parseInt(input, 10);
+        if (!isNaN(num) && num >= 1 && num <= FIELD_DEFS.length) {
+            return this.reaskField(FIELD_DEFS[num - 1].key);
+        }
+        return {
+            done: false,
+            reply: `Something went wrong writing your files: ${this.writeError}\n` +
+                `Type **retry** to try again, pick a number to edit a field, or \`!cancel\` to give up.`,
+        };
+    }
+    finishEdit() {
+        this.editing = false;
+        return this.showConfirmation();
+    }
+    reaskField(key) {
+        this.editing = true;
+        switch (key) {
+            case 'userName':
+                this.step = 'NAME';
+                return { done: false, reply: "**What's your name?**" };
+            case 'timezone':
+                this.step = 'TIMEZONE';
+                return {
+                    done: false,
+                    reply: '**What timezone are you in?**\n' +
+                        'Use an IANA name like `America/New_York`, or an abbreviation like `EST`, `PST`, `CET`.',
+                };
+            case 'morningCheckin':
+                this.step = 'CHECKIN';
+                return { done: false, reply: '**Would you like a morning check-in message each day?** (yes / no)' };
+            default:
+                return this.showConfirmation();
+        }
+    }
+}