windsor-bot 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "windsor-bot",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Self-hosted Discord bot automation for household list and todo printing",
   "type": "module",
   "main": "dist/index.js",
@@ -11,8 +11,12 @@
     "test": "node --test src/tests/*.test.ts"
   },
   "bin": {
-    "windsor-bot": "./dist/index.js"
+    "windsor-bot": "dist/index.js"
   },
+  "files": [
+    "dist",
+    "assets"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/SeaRyanC/windsor-bot.git"

package/SPEC.md

@@ -1,179 +0,0 @@
-# Windsor Specification: Implementation Guide
-
-## Channel Behavior Mapping
-
-The server UI always immediately saves all config changes.
-
-In the server config UI webpage, we see a list of channel->behavior mapping rows. Clicking on a row allows the user to see sub-configuration for that behavior (e.g. footer text). They can also delete a row. There's adjacent UI with a list of unmapped channels and list of behaviors; the user can pick one of each and then click "Add" to create the behavior mapping.
-
-Internally, we store configuration in terms of both the channel name and ID, and match based on what we see on server startup or refresh: If the ID matches, use that and update our name. If none of the IDs match, see if a channel with the right name exists, update the ID instead. If neither exist, just delete that configuraiton entry. Be careful to not accidently nuke all config if we're encountering a server availabiliy blip - if *all* channels are missing, probably something has gone wrong, don't delete the config.
-
-Channels may only have one behavior.
-
-## URL Detection and Transformation
-
-URLs are detected as any `https://...` text; we don't need to support other protocols. Trailing punctuation is ignored.
-
-If multiple URLs are in the same message, write `[link 1]`, `[link 2]`, etc, instead of `[link]`. Don't try to dedupe URLs. There is a maximum of 5 links per printout. If URL parsing fails, assume it wasn't a URL in the first pace. If a URL is too long to generate a printable QR code for, assume it wasn't a URL in the first place.
-
-## Idempotency
-
-The bot does not require or assume 24/7 uptime. On startup you should scan prior messages and see what needs acting on. You only need to look at the last 100 messages per channel (500 for recurrences - assume we do not have more than that); messages older than this can be assumed to already be actioned.
-
-For non-recurring items, use **reactions** to indicate that you've complied (e.g. printed or whatever) to a request. Use the ✅ reaction upon successfully fulfilling the request.
-
-If printing fails, react with ⏸️ and post a reply that explains what went wrong.
-
-The intended user workflow on fixing a printer is to power-cycle the Raspberry Pi, so you should attempt to re-process these messages on startup.
-
-## Print Layout
-
-In general we assume an 80mm printer. Long text should be wrapped. Extremely long messages (800 characters (?) after stripping URLs) should be ignored and reacted with ⁉️.
-
-For message content, we generally want to print at quite a large font, for readability. This should scale down for longer messages; our ideal is that we are printing something that is modestly square to rectangular (not a tiny strip, not a CVS receipt). Images should span the full width of the paper minus a small margin.
-
-General format is:
-
- * User-specified header (large font)
- * Primary text (medium-large font, depending)
- * Icon
- * QR codes
- * User-specified footer (medium font)
- * Metadata footer (small font)
-
-Timestamps are in local time, in the format `2026-08-17 7:34 PM`
-
-## Message Ingestion
-
-Ignore user attachments, images, embeds, etc.. Only look at primary message content.
-Ignore replies.
-Ignore messages from your own account.
-
-If parsing fails, react with ⁉️ and reply with something sensible related to the parsing failure that occurred.
-
-Editing a message does not re-trigger bot activity.
-
-## Accumulating List Behavior
-
-The message `print` (any casing, all spacing / punctuation ignored) triggers a print.
-Print all items between this message and the prior print message (or 100 messages, whichever is shorter).
-If this would yield 0 items, instead print the "previous" list (this would normally occur if the printer had run out of paper and the user is retrying).
-
-Don't try to deduplicate items.
-Ignore deleted messages in the chat.
-Use the latest version of any edited message.
-
-## Recurring Print Behavior
-
-We need to extract two main things from the user's message:
- * The *message* part
- * The *schedule* part
-
-Use structured output using a zod schema to implement this.
-
-Send the AI a message in this form:
-
-> The user has asked for a recurring printout. It is currently [the current date and time]. Tell me the next time that I should do this, and what the non-schedule part of the message was (verbatim). If the user didn't specify a time of day, use 8:00 AM. Here's the user's message: [the user message]
-
-You'll want to get back a JSON blob like this:
-```json
-{
-    "message without schedule": "take out the trash",
-    "next occurrence": "2025-08-02 07:30 PM"
-}
-```
-Be flexible about date parsing.
-
-Use majority-reasoning method of asking 5 times. You must get 60% consistency in the message portion and 60% consistency in the next occurrence portion (not necessarily from the same responses); if this doesn't happen, treat this as a failure to parse and react appropriately.
-
-React to the message with the standard green checkmark and reply with:
-
-> Got it. I will print ⟪take out the trash⟫ at 2025-08-02 07:30 PM
-
-You'll ingest this message on re-starts to establish what scheduled tasks there are.
-Enqueue a background task that checks for scheduled items maturing (check every 30s).
-
-When a task matures, we'll of course print it as requested.
-When print finishes, react to the reply with the checkmark emoji.
-
-Then we'll return to the AI to ask for what the next occurrence is.
-Note that a task might have finite occurrences, e.g. the user prompt might be "for the next five weeks, remind me at 2 PM to take my medicine on Tuesdays".
-
-So we'll post a reply either like
-
-> This occurrence has expired and no more prints are scheduled
-
-*or*
-
-> Printed at 2025-08-02 07:30 PM. The next print will be at 2025-08-09 07:30 PM.
-
-You can thus interpret the absence of such a reply (but the presence of the checkmark) as meaning the prior run failed to reach the AI server, and needs a retry.
-
-## OpenAI Notes
-
-Use `gpt-5.4-nano`, low reasoning, with structured outputs with zod v4 JSON schema for all tasks.
-
-Keep a global rolling window of never consuming more than 200,000 tokens during any 24 hour period (something would be EXTREMELY wrong if this happens). If this happens, literally delete the AI key from your config.
-
-## Icon Feature
-
-For our auto-generated icon, we'll use OpenAI API. Use `gpt-image-1-mini`, 1024x1024, auto quality, transparency on, png format, with a prompt like
-
-> Black-on-transparent line drawing icon for the TODO item: "take out the trash". Do not produce any text. Use big, thick lines. No fine detailing.
-
-Once you get an image back, store it somewhere sensible on disk with a name like `1837c1a3e.png` where the name is derived from a SHA of the prompt. Check this cache first before calling out to the API.
-
-If you're trying to print an item and the AI API is not working for some reason, retry up to 3 times, then just give up and skip the icon, it's never mandatory.
-
-## On-Demand Commands and Interaction Model
-
-Both `!command` and `/command` are supported.
-Follow our standard idempotency model.
-All users can run commands.
-
-## Persistence and Data Model
-
-We have three primary data sources:
- * Messages in the channel itself
- * Our own messages and reactions, which indicate work we've already done
- * Local config JSON file
- * In-memory log. This is where we persist logging, etc - we do not need to persist logging between server restarts
-
-## Security and Access Control
-
-In the server configuration page, users can optionally set a password (hash this and store it in the config file). Once this is set, the config server can only be accessed using that password; use WWW-Authenticate and ignore the username portion.
-
-Channel security is up to Discord config; any user posting in a behavior-configured channel is assumed to be authorized to trigger whatever they're doing.
-
-## Printer Integration
-
-We only support ESC/P protocol, and there must be at most one printer installed.
-The server configuration page should show what printer is connected (if any), offer appropriate printer config options, and have a "print test page button" that prints a small test page demonstrating printer capabilities (fonts, images, alignments, etc).
-
-## Diagnostics
-
-The server log, visible in the server config page, should show enough events to allow basic diagnostic health, e.g.
- * Successful discord gateway connection
- * Print success/fail
-
-Do not include keepalive pings or other routine "non-events".
-
-## Testing
-
-Write tasteful unit tests at module boundaries. Test for behavorial acceptance, not hardcoded results, and don't test things that TypeScript is already covering for us. Tests must be typechecked. Don't test things that are too much of a pain in the ass.
-
-## Revision notes: alpha
-
-Apply these revisions to the spec or readme IF APPROPRIATE
-
- * It should be more apparent in the server config whether a Discord token has been set yet. Same for OpenAI. Don't actually hide these, just always show them
- * Use "server" in all user-facing config, never "guild"
- * Server ID is required
- * Setting the discord token and server ID should reload the channel list in the server UI
- * Fix this: "(node:49701) DeprecationWarning: The ready event has been renamed to clientReady to distinguish it from the gateway READY event and will only emit under that name in v15. Please use clientReady instead."
- * Add a "refresh channels" button to the server UI, next to the channel list
- * Remove all "back compat" code, you don't need to be backward compatible with anything, this is an alpha project
- * Command invocation should automatically trigger a log event without extra per-code command
- * Don't use `class` in this project, use a function/revealing-module pattern instead
- * Server config UI should have a "Restart Server" button
- * Don't show voice channels or forum channels in the channel listing

package/scripts/build-web.mjs

@@ -1,13 +0,0 @@
-import { build } from 'esbuild';
-
-await build({
-    entryPoints: ['src/web/app.tsx'],
-    bundle: true,
-    outfile: 'dist/web/app.bundle.js',
-    platform: 'browser',
-    format: 'esm',
-    target: ['es2022'],
-    jsx: 'automatic',
-    jsxImportSource: 'preact',
-    sourcemap: 'inline',
-});

package/scripts/download-pokemon-sprites.mjs

@@ -1,38 +0,0 @@
-// Downloads Gen 1 GameBoy (yellow/gray) sprites for all 151 Kanto pokemon.
-// Run once: node scripts/download-pokemon-sprites.mjs
-
-import { mkdir, writeFile, access } from 'fs/promises';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const OUT_DIR = join(__dirname, '../src/commands/pokemon-sprites');
-
-const BASE_URL = 'https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/versions/generation-i/yellow/gray';
-
-await mkdir(OUT_DIR, { recursive: true });
-
-let ok = 0, skipped = 0, failed = 0;
-
-for (let id = 1; id <= 151; id++) {
-    const dest = join(OUT_DIR, `${id}.png`);
-    try {
-        await access(dest);
-        skipped++;
-        continue;
-    } catch { /* not downloaded yet */ }
-
-    const url = `${BASE_URL}/${id}.png`;
-    const res = await fetch(url);
-    if (!res.ok) {
-        console.error(`FAIL #${id}: HTTP ${res.status}`);
-        failed++;
-        continue;
-    }
-    const buf = Buffer.from(await res.arrayBuffer());
-    await writeFile(dest, buf);
-    process.stdout.write(`\r${id}/151`);
-    ok++;
-}
-
-console.log(`\nDone. Downloaded: ${ok}, Skipped (already existed): ${skipped}, Failed: ${failed}`);

package/src/ai.ts

@@ -1,214 +0,0 @@
-import { createHash } from 'crypto';
-import { mkdir, writeFile, readFile, access } from 'fs/promises';
-import { join } from 'path';
-import OpenAI from 'openai';
-import { zodResponseFormat } from 'openai/helpers/zod.js';
-import { z } from 'zod/v4';
-import { getCurrentConfig, updateConfig } from './config.ts';
-import { logEvent } from './server.ts';
-
-const MODEL = 'gpt-5.4-nano';
-const IMAGE_MODEL = 'gpt-image-1-mini';
-const TOKEN_LIMIT_24H = 200_000;
-
-
-export function trackTokenUsage(tokens: number): void {
-    const config = getCurrentConfig();
-    const entry = { timestamp: new Date().toISOString(), tokens };
-    const usage = [...config.tokenUsage, entry];
-    // Keep only entries from the last 24 hours
-    const cutoff = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
-    const pruned = usage.filter(e => e.timestamp >= cutoff);
-    void updateConfig({ tokenUsage: pruned });
-}
-
-export function getTokenUsage24h(): number {
-    const config = getCurrentConfig();
-    const cutoff = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
-    return config.tokenUsage
-        .filter(e => e.timestamp >= cutoff)
-        .reduce((sum, e) => sum + e.tokens, 0);
-}
-
-export async function isOverTokenLimit(): Promise<boolean> {
-    const used = getTokenUsage24h();
-    if (used >= TOKEN_LIMIT_24H) {
-        logEvent('error', `Token limit exceeded (${used} tokens in last 24h). Deleting OpenAI key.`);
-        const config = getCurrentConfig();
-        const updated = { ...config };
-        delete updated.openaiKey;
-        await updateConfig(updated);
-        return true;
-    }
-    return false;
-}
-
-
-function getClient(): OpenAI | null {
-    const key = getCurrentConfig().openaiKey;
-    if (!key) return null;
-    return new OpenAI({ apiKey: key });
-}
-
-
-const ScheduleSchema = z.object({
-    'message without schedule': z.string(),
-    'next occurrence': z.string(),
-});
-
-type ScheduleResult = z.infer<typeof ScheduleSchema>;
-
-export interface ParsedSchedule {
-    message: string;
-    nextOccurrence: Date;
-}
-
-function parseOccurrenceDate(str: string): Date | null {
-    try {
-        const d = new Date(str);
-        if (!isNaN(d.getTime())) return d;
-    } catch {
-        // ignore
-    }
-    return null;
-}
-
-export async function parseRecurringSchedule(userMessage: string, now: Date): Promise<ParsedSchedule | null> {
-    const client = getClient();
-    if (!client) return null;
-
-    if (await isOverTokenLimit()) return null;
-
-    const nowStr = formatScheduleDate(now);
-    const prompt = `The user has asked for a recurring printout. It is currently ${nowStr}. Tell me the next time that I should do this, and what the non-schedule part of the message was (verbatim). If the user didn't specify a time of day, use 8:00 AM. Here's the user's message: ${userMessage}`;
-
-    const results: ScheduleResult[] = [];
-    const ATTEMPTS = 5;
-
-    for (let i = 0; i < ATTEMPTS; i++) {
-        try {
-            const completion = await client.chat.completions.create({
-                model: MODEL,
-                reasoning_effort: 'low',
-                messages: [{ role: 'user', content: prompt }],
-                response_format: zodResponseFormat(ScheduleSchema, 'schedule'),
-            } as Parameters<typeof client.chat.completions.create>[0]) as import("openai/resources/chat/completions/completions.js").ChatCompletion;
-            const content = completion.choices[0]?.message?.content;
-            if (content) {
-                const parsed = ScheduleSchema.parse(JSON.parse(content));
-                results.push(parsed);
-                const tokens = (completion as { usage?: { total_tokens?: number } }).usage?.total_tokens ?? 0;
-                trackTokenUsage(tokens);
-            }
-        } catch (err) {
-            logEvent('error', `Schedule parsing attempt ${i + 1} failed: ${err}`);
-        }
-    }
-
-    if (results.length < 3) return null;
-
-    // Majority voting: need 60% consistency for each field
-    const messageCounts = new Map<string, number>();
-    const occurrenceCounts = new Map<string, number>();
-
-    for (const r of results) {
-        messageCounts.set(r['message without schedule'], (messageCounts.get(r['message without schedule']) ?? 0) + 1);
-        occurrenceCounts.set(r['next occurrence'], (occurrenceCounts.get(r['next occurrence']) ?? 0) + 1);
-    }
-
-    const threshold = ATTEMPTS * 0.6;
-
-    let bestMessage: string | null = null;
-    for (const [msg, count] of messageCounts) {
-        if (count >= threshold) { bestMessage = msg; break; }
-    }
-
-    let bestOccurrence: string | null = null;
-    for (const [occ, count] of occurrenceCounts) {
-        if (count >= threshold) { bestOccurrence = occ; break; }
-    }
-
-    if (!bestMessage || !bestOccurrence) return null;
-
-    const occDate = parseOccurrenceDate(bestOccurrence);
-    if (!occDate) return null;
-
-    return { message: bestMessage, nextOccurrence: occDate };
-}
-
-function formatScheduleDate(date: Date): string {
-    const year = date.getFullYear();
-    const month = String(date.getMonth() + 1).padStart(2, '0');
-    const day = String(date.getDate()).padStart(2, '0');
-    let hours = date.getHours();
-    const minutes = String(date.getMinutes()).padStart(2, '0');
-    const ampm = hours >= 12 ? 'PM' : 'AM';
-    hours = hours % 12 || 12;
-    return `${year}-${month}-${day} ${hours}:${minutes} ${ampm}`;
-}
-
-export { formatScheduleDate };
-
-export async function getNextOccurrence(originalMessage: string, now: Date): Promise<Date | null> {
-    const result = await parseRecurringSchedule(originalMessage, now);
-    return result ? result.nextOccurrence : null;
-}
-
-export async function generateIcon(text: string, cacheDir: string): Promise<string | null> {
-    const prompt = `Black-on-transparent line drawing icon for the TODO item: "${text}". Do not produce any text. Use big, thick lines. No fine detailing.`;
-    const hash = createHash('sha1').update(prompt).digest('hex').slice(0, 9);
-    const filename = `${hash}.png`;
-    const cachePath = join(cacheDir, filename);
-
-    // Check cache first
-    try {
-        await access(cachePath);
-        return cachePath;
-    } catch {
-        // not cached
-    }
-
-    const client = getClient();
-    if (!client) return null;
-
-    if (await isOverTokenLimit()) return null;
-
-    for (let attempt = 0; attempt < 3; attempt++) {
-        try {
-            const response = await client.images.generate({
-                model: IMAGE_MODEL,
-                prompt,
-                n: 1,
-                size: '1024x1024',
-                quality: 'low',
-                background: 'transparent',
-                output_format: 'png',
-            } as Parameters<typeof client.images.generate>[0]) as import("openai/resources/images.js").ImagesResponse;
-
-            const imageData = response.data?.[0];
-            if (!imageData) throw new Error('No image data returned');
-
-            let imageBuffer: Buffer;
-            if ('b64_json' in imageData && imageData.b64_json) {
-                imageBuffer = Buffer.from(imageData.b64_json, 'base64');
-            } else if ('url' in imageData && imageData.url) {
-                const res = await fetch(imageData.url);
-                imageBuffer = Buffer.from(await res.arrayBuffer());
-            } else {
-                throw new Error('No image URL or base64 data');
-            }
-
-            await mkdir(cacheDir, { recursive: true });
-            await writeFile(cachePath, imageBuffer);
-            return cachePath;
-        } catch (err) {
-            logEvent('error', `Icon generation attempt ${attempt + 1} failed: ${err}`);
-            if (attempt === 2) return null;
-        }
-    }
-
-    return null;
-}
-
-// suppress unused import warning
-void readFile;