# Agents Instructions for Blogging Desktop Server (bDS) This document provides context and best practices for GitHub Copilot when working on this Electron + TypeScript + SQLite blogging application. ## Plan Mode - Make the plan extremely concise. Sacrifice grammar for the sake of concision. - At the end of each plan, give me a list of unresolved questions to answer, if any. ## Commits - our default branch is origin/master - commit messages are short - one sentence. do not write long articles. - pull requests are more verbose and especially give reasoning for changes ## Important facts - published posts don't have body in the database, the body content is only in the file - functionality you implement have to be tied to UI - UI you implement has to be tied to functionality - you must use drizzle to generate migrations and snapshots - we use an sqlite database. use sqlite semantics in snapshots and other artifacts - on MacOS we use native menus and you have to hook them into the intercept for new menu items - there are two areas of localization, you sometimes need both (menus for example) - all automatic AI activities must be gated by airplane (offline) mode of the app and either use the local model or inform the user via toast - metadata needs to be flushed to the filesystem and needs to be included in metadata diff tool and in rebuild from filesystem. All three aspects have to be in sync with each other. - if you add new metadata, add them to publishing, metadata-diff and rebuild-from-database - HEREDOCs don't work most of the time. Don't use them. Use editor tools to create proper scripots --- ## ⚠️ MANDATORY: Test-First Development **STOP!** Before writing ANY implementation code, you MUST: 1. **Write a failing test first** that describes the expected behavior 2. **Run the test** to confirm it fails (Red) 3. **Write minimal code** to make the test pass (Green) 4. **Refactor** while keeping tests green > **No code without tests. No exceptions.** > > Tests must import and exercise the REAL implementation classes, not inline helper functions. > Mock only external dependencies (database, filesystem), never the class under test. --- ## ⚠️ MANDATORY: Fix All Test Failures **You MUST investigate and fix ALL test failures before completing any task.** - Never leave tests failing, even if they appear unrelated to your changes - If a test failure is pre-existing, fix it as part of your current work - Run the full test suite (`npm test`) before considering any task complete - If you cannot fix a test, explain why and propose a solution > **Zero failing tests. No exceptions.** --- ## ⚠️ MANDATORY: Remove Unused Code **Never keep unused code around. Always delete it completely.** - When a feature is removed, delete ALL related code (implementation, tests, types, configs) - Do NOT comment out code "for later" - use version control history - Do NOT skip tests for removed functionality - delete them - Do NOT leave dead code paths, unused imports, or orphaned functions - When refactoring, actively look for and remove any code that becomes unused > **Delete unused code immediately. No exceptions.** --- ## ⚠️ MANDATORY: Build Verification After Code Changes **You MUST run the full build after making code changes.** - Run `npm run build` after any code modifications - Fix ALL build errors before considering the task complete - Build errors indicate issues that may not be caught by `tsc --noEmit` alone (e.g., event forwarding, renderer build) - The build must complete successfully before the task is complete > **Successful build required. No exceptions.** --- ## ⚠️ MANDATORY: No External JS/CSS in Preview or Generated HTML **Do not reference external JavaScript or CSS libraries (CDNs/remote URLs) from the preview server output or generated HTML.** - Preview HTML must reference only local/package-bundled assets - Generated HTML must not include CDN-hosted JS/CSS libraries - If a library is needed (e.g., Pico CSS, Lightbox), include it as a local dependency and serve/reference it locally - Avoid introducing any new `