From 5579a15ee2ad82f8e5e336e36f80b19134ad940c Mon Sep 17 00:00:00 2001 From: Bill Date: Sun, 26 Oct 2025 11:01:16 -0400 Subject: [PATCH] docs: remove legacy .windsurf documentation files - Removed all .windsurf/rules/ markdown files containing outdated plugin development guidelines - Files included agent guidelines, code examples, coding conventions, commands/settings docs, environment setup, file organization, manifest rules, project overview, references, security/privacy, troubleshooting, and UX guidelines - Content will be replaced with updated documentation in a new location Note: This appears to be a cleanup commit removing --- .windsurf/rules/agent-guidelines.md | 26 -------- .windsurf/rules/code-examples.md | 84 -------------------------- .windsurf/rules/coding-conventions.md | 35 ----------- .windsurf/rules/commands-settings.md | 54 ----------------- .windsurf/rules/environment-tooling.md | 38 ------------ .windsurf/rules/file-organization.md | 39 ------------ .windsurf/rules/manifest-rules.md | 30 --------- .windsurf/rules/project-overview.md | 16 ----- .windsurf/rules/references.md | 22 ------- .windsurf/rules/security-privacy.md | 27 --------- .windsurf/rules/troubleshooting.md | 45 -------------- .windsurf/rules/ux-guidelines.md | 32 ---------- .windsurf/rules/versioning-releases.md | 32 ---------- 13 files changed, 480 deletions(-) delete mode 100644 .windsurf/rules/agent-guidelines.md delete mode 100644 .windsurf/rules/code-examples.md delete mode 100644 .windsurf/rules/coding-conventions.md delete mode 100644 .windsurf/rules/commands-settings.md delete mode 100644 .windsurf/rules/environment-tooling.md delete mode 100644 .windsurf/rules/file-organization.md delete mode 100644 .windsurf/rules/manifest-rules.md delete mode 100644 .windsurf/rules/project-overview.md delete mode 100644 .windsurf/rules/references.md delete mode 100644 .windsurf/rules/security-privacy.md delete mode 100644 .windsurf/rules/troubleshooting.md delete mode 100644 .windsurf/rules/ux-guidelines.md delete mode 100644 .windsurf/rules/versioning-releases.md diff --git a/.windsurf/rules/agent-guidelines.md b/.windsurf/rules/agent-guidelines.md deleted file mode 100644 index a3747f1..0000000 --- a/.windsurf/rules/agent-guidelines.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -description: Agent-specific do's and don'ts ---- - -# Agent Guidelines - -## Do - -- Add commands with stable IDs (don't rename once released) -- Provide defaults and validation in settings -- Write idempotent code paths so reload/unload doesn't leak listeners or intervals -- Use `this.register*` helpers for everything that needs cleanup -- Keep `main.ts` minimal and focused on lifecycle management -- Split functionality across separate modules -- Organize code into logical folders (commands/, ui/, utils/) - -## Don't - -- Introduce network calls without an obvious user-facing reason and documentation -- Ship features that require cloud services without clear disclosure and explicit opt-in -- Store or transmit vault contents unless essential and consented -- Put all code in `main.ts` - delegate to separate modules -- Create files larger than 200-300 lines without splitting them -- Commit build artifacts to version control -- Change plugin `id` after release -- Rename command IDs after release diff --git a/.windsurf/rules/code-examples.md b/.windsurf/rules/code-examples.md deleted file mode 100644 index 061fcdd..0000000 --- a/.windsurf/rules/code-examples.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -trigger: always_on -description: Common code patterns and examples ---- - -# Code Examples - -## Organize Code Across Multiple Files - -### main.ts (minimal, lifecycle only) - -```ts -import { Plugin } from "obsidian"; -import { MySettings, DEFAULT_SETTINGS } from "./settings"; -import { registerCommands } from "./commands"; - -export default class MyPlugin extends Plugin { - settings: MySettings; - - async onload() { - this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData()); - registerCommands(this); - } -} -``` - -### settings.ts - -```ts -export interface MySettings { - enabled: boolean; - apiKey: string; -} - -export const DEFAULT_SETTINGS: MySettings = { - enabled: true, - apiKey: "", -}; -``` - -### commands/index.ts - -```ts -import { Plugin } from "obsidian"; -import { doSomething } from "./my-command"; - -export function registerCommands(plugin: Plugin) { - plugin.addCommand({ - id: "do-something", - name: "Do something", - callback: () => doSomething(plugin), - }); -} -``` - -## Add a Command - -```ts -this.addCommand({ - id: "your-command-id", - name: "Do the thing", - callback: () => this.doTheThing(), -}); -``` - -## Persist Settings - -```ts -interface MySettings { enabled: boolean } -const DEFAULT_SETTINGS: MySettings = { enabled: true }; - -async onload() { - this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData()); - await this.saveData(this.settings); -} -``` - -## Register Listeners Safely - -```ts -this.registerEvent(this.app.workspace.on("file-open", f => { /* ... */ })); -this.registerDomEvent(window, "resize", () => { /* ... */ }); -this.registerInterval(window.setInterval(() => { /* ... */ }, 1000)); -``` \ No newline at end of file diff --git a/.windsurf/rules/coding-conventions.md b/.windsurf/rules/coding-conventions.md deleted file mode 100644 index e2f91c2..0000000 --- a/.windsurf/rules/coding-conventions.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -trigger: always_on -description: TypeScript coding conventions and best practices ---- - -# Coding Conventions - -## TypeScript Standards - -- Use TypeScript with `"strict": true` preferred -- Bundle everything into `main.js` (no unbundled runtime deps) -- Prefer `async/await` over promise chains -- Handle errors gracefully - -## Code Organization - -- **Keep `main.ts` minimal** - Focus only on plugin lifecycle (onload, onunload, addCommand calls) -- **Delegate all feature logic to separate modules** -- **Split large files** - If any file exceeds ~200-300 lines, break it into smaller, focused modules -- **Use clear module boundaries** - Each file should have a single, well-defined responsibility - -## Platform Compatibility - -- Avoid Node/Electron APIs if you want mobile compatibility -- Set `isDesktopOnly` accordingly if using desktop-only features -- Test on iOS and Android where feasible -- Don't assume desktop-only behavior unless `isDesktopOnly` is `true` - -## Performance - -- Keep startup light - defer heavy work until needed -- Avoid long-running tasks during `onload` - use lazy initialization -- Batch disk access and avoid excessive vault scans -- Debounce/throttle expensive operations in response to file system events -- Avoid large in-memory structures on mobile - be mindful of memory and storage constraints \ No newline at end of file diff --git a/.windsurf/rules/commands-settings.md b/.windsurf/rules/commands-settings.md deleted file mode 100644 index 2f1307a..0000000 --- a/.windsurf/rules/commands-settings.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -trigger: always_on -description: Commands and settings implementation guidelines ---- - -# Commands & Settings - -## Commands - -- Add user-facing commands via `this.addCommand(...)` -- **Use stable command IDs** - Don't rename once released -- Ensure commands are unique and descriptive - -### Example: Add a Command - -```ts -this.addCommand({ - id: "your-command-id", - name: "Do the thing", - callback: () => this.doTheThing(), -}); -``` - -## Settings - -- Provide a settings tab if the plugin has configuration -- Always provide sensible defaults -- Persist settings using `this.loadData()` / `this.saveData()` -- Provide defaults and validation in settings - -### Example: Persist Settings - -```ts -interface MySettings { enabled: boolean } -const DEFAULT_SETTINGS: MySettings = { enabled: true }; - -async onload() { - this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData()); - await this.saveData(this.settings); -} -``` - -## Resource Management - -- Write idempotent code paths so reload/unload doesn't leak listeners or intervals -- Use `this.register*` helpers for everything that needs cleanup - -### Example: Register Listeners Safely - -```ts -this.registerEvent(this.app.workspace.on("file-open", f => { /* ... */ })); -this.registerDomEvent(window, "resize", () => { /* ... */ }); -this.registerInterval(window.setInterval(() => { /* ... */ }, 1000)); -``` \ No newline at end of file diff --git a/.windsurf/rules/environment-tooling.md b/.windsurf/rules/environment-tooling.md deleted file mode 100644 index 8c2f5f5..0000000 --- a/.windsurf/rules/environment-tooling.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -trigger: always_on -description: Development environment and tooling requirements ---- - -# Environment & Tooling - -## Required Tools - -- **Node.js**: Use current LTS (Node 18+ recommended) -- **Package manager**: npm (required for this sample - `package.json` defines npm scripts and dependencies) -- **Bundler**: esbuild (required for this sample - `esbuild.config.mjs` and build scripts depend on it) -- **Types**: `obsidian` type definitions - -**Note**: This sample project has specific technical dependencies on npm and esbuild. If creating a plugin from scratch, you can choose different tools, but you'll need to replace the build configuration accordingly. Alternative bundlers like Rollup or webpack are acceptable if they bundle all external dependencies into `main.js`. - -## Common Commands - -### Install dependencies -```bash -npm install -``` - -### Development (watch mode) -```bash -npm run dev -``` - -### Production build -```bash -npm run build -``` - -## Linting - -- Install eslint: `npm install -g eslint` -- Analyze project: `eslint main.ts` -- Analyze folder: `eslint ./src/` \ No newline at end of file diff --git a/.windsurf/rules/file-organization.md b/.windsurf/rules/file-organization.md deleted file mode 100644 index 2dcdf3a..0000000 --- a/.windsurf/rules/file-organization.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -trigger: always_on -description: File and folder organization conventions ---- - -# File & Folder Organization - -## Core Principles - -- **Organize code into multiple files**: Split functionality across separate modules rather than putting everything in `main.ts` -- **Keep `main.ts` minimal**: Focus only on plugin lifecycle (onload, onunload, addCommand calls) -- **Split large files**: If any file exceeds ~200-300 lines, break it into smaller, focused modules -- **Use clear module boundaries**: Each file should have a single, well-defined responsibility - -## Recommended Structure - -``` -src/ - main.ts # Plugin entry point, lifecycle management only - settings.ts # Settings interface and defaults - commands/ # Command implementations - command1.ts - command2.ts - ui/ # UI components, modals, views - modal.ts - view.ts - utils/ # Utility functions, helpers - helpers.ts - constants.ts - types.ts # TypeScript interfaces and types -``` - -## Best Practices - -- Source lives in `src/` -- Keep the plugin small - avoid large dependencies -- Prefer browser-compatible packages -- Generated output should be placed at the plugin root or `dist/` depending on build setup -- Release artifacts must end up at the top level of the plugin folder (`main.js`, `manifest.json`, `styles.css`) \ No newline at end of file diff --git a/.windsurf/rules/manifest-rules.md b/.windsurf/rules/manifest-rules.md deleted file mode 100644 index c63388b..0000000 --- a/.windsurf/rules/manifest-rules.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -trigger: always_on -description: Manifest.json requirements and conventions ---- - -# Manifest Rules - -## Required Fields - -The `manifest.json` must include: - -- `id` - Plugin ID; for local dev it should match the folder name -- `name` - Display name -- `version` - Semantic Versioning `x.y.z` -- `minAppVersion` - Minimum Obsidian version required -- `description` - Brief description -- `isDesktopOnly` - Boolean indicating mobile compatibility - -## Optional Fields - -- `author` - Plugin author name -- `authorUrl` - Author's URL -- `fundingUrl` - Funding/donation URL (string or map) - -## Critical Rules - -- **Never change `id` after release** - Treat it as stable API -- Keep `minAppVersion` accurate when using newer APIs -- Use Semantic Versioning for `version` field -- Canonical requirements: https://github.com/obsidianmd/obsidian-releases/blob/master/.github/workflows/validate-plugin-entry.yml \ No newline at end of file diff --git a/.windsurf/rules/project-overview.md b/.windsurf/rules/project-overview.md deleted file mode 100644 index 4ab2dc9..0000000 --- a/.windsurf/rules/project-overview.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -trigger: always_on -description: Obsidian plugin project structure and requirements ---- - -# Project Overview - -- **Target**: Obsidian Community Plugin (TypeScript → bundled JavaScript) -- **Entry point**: `main.ts` compiled to `main.js` and loaded by Obsidian -- **Required release artifacts**: `main.js`, `manifest.json`, and optional `styles.css` - -## Key Requirements - -- All TypeScript code must be bundled into a single `main.js` file -- Release artifacts must be placed at the top level of the plugin folder -- Never commit build artifacts (`node_modules/`, `main.js`, etc.) to version control \ No newline at end of file diff --git a/.windsurf/rules/references.md b/.windsurf/rules/references.md deleted file mode 100644 index 37aa439..0000000 --- a/.windsurf/rules/references.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -trigger: always_on -description: Official documentation and reference links ---- - -# References - -## Official Resources - -- **Obsidian sample plugin**: https://github.com/obsidianmd/obsidian-sample-plugin -- **API documentation**: https://docs.obsidian.md -- **Developer policies**: https://docs.obsidian.md/Developer+policies -- **Plugin guidelines**: https://docs.obsidian.md/Plugins/Releasing/Plugin+guidelines -- **Style guide**: https://help.obsidian.md/style-guide -- **Manifest validation**: https://github.com/obsidianmd/obsidian-releases/blob/master/.github/workflows/validate-plugin-entry.yml - -## When to Consult - -- Check **Developer policies** before implementing features that access external services -- Review **Plugin guidelines** before submitting to the community catalog -- Reference **API documentation** when using Obsidian APIs -- Follow **Style guide** for UI text and documentation \ No newline at end of file diff --git a/.windsurf/rules/security-privacy.md b/.windsurf/rules/security-privacy.md deleted file mode 100644 index 76f05a0..0000000 --- a/.windsurf/rules/security-privacy.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -trigger: always_on -description: Security, privacy, and compliance requirements ---- - -# Security, Privacy, and Compliance - -Follow Obsidian's **Developer Policies** and **Plugin Guidelines**. - -## Network & External Services - -- **Default to local/offline operation** - Only make network requests when essential to the feature -- **No hidden telemetry** - If you collect optional analytics or call third-party services, require explicit opt-in and document clearly in `README.md` and in settings -- **Never execute remote code** - Don't fetch and eval scripts, or auto-update plugin code outside of normal releases -- **Clearly disclose external services** - Document any external services used, data sent, and risks - -## Data Access & Privacy - -- **Minimize scope** - Read/write only what's necessary inside the vault -- **Do not access files outside the vault** -- **Respect user privacy** - Do not collect vault contents, filenames, or personal information unless absolutely necessary and explicitly consented -- **No deceptive patterns** - Avoid ads or spammy notifications - -## Resource Management - -- **Register and clean up all resources** - Use the provided `register*` helpers so the plugin unloads safely -- Clean up DOM, app, and interval listeners properly \ No newline at end of file diff --git a/.windsurf/rules/troubleshooting.md b/.windsurf/rules/troubleshooting.md deleted file mode 100644 index 3567ea7..0000000 --- a/.windsurf/rules/troubleshooting.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -trigger: always_on -description: Common issues and solutions ---- - -# Troubleshooting - -## Plugin Doesn't Load After Build - -**Issue**: Plugin doesn't appear in Obsidian after building - -**Solution**: Ensure `main.js` and `manifest.json` are at the top level of the plugin folder under `/.obsidian/plugins//` - -## Build Issues - -**Issue**: `main.js` is missing after build - -**Solution**: Run `npm run build` or `npm run dev` to compile your TypeScript source code - -## Commands Not Appearing - -**Issue**: Commands don't show up in command palette - -**Solution**: -- Verify `addCommand` runs after `onload` -- Ensure command IDs are unique -- Check that commands are properly registered - -## Settings Not Persisting - -**Issue**: Settings reset after reloading Obsidian - -**Solution**: -- Ensure `loadData`/`saveData` are awaited -- Re-render the UI after changes -- Verify settings are properly merged with defaults - -## Mobile-Only Issues - -**Issue**: Plugin works on desktop but not mobile - -**Solution**: -- Confirm you're not using desktop-only APIs -- Check `isDesktopOnly` setting in manifest -- Test on actual mobile devices or adjust compatibility \ No newline at end of file diff --git a/.windsurf/rules/ux-guidelines.md b/.windsurf/rules/ux-guidelines.md deleted file mode 100644 index 293e205..0000000 --- a/.windsurf/rules/ux-guidelines.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -trigger: always_on -description: UX and copy guidelines for UI text ---- - -# UX & Copy Guidelines - -For UI text, commands, and settings: - -## Text Formatting - -- **Prefer sentence case** for headings, buttons, and titles -- Use clear, action-oriented imperatives in step-by-step copy -- Keep in-app strings short, consistent, and free of jargon - -## UI References - -- Use **bold** to indicate literal UI labels -- Prefer "select" for interactions -- Use arrow notation for navigation: **Settings → Community plugins** - -## Examples - -✅ Good: -- "Select **Settings → Community plugins**" -- "Enable the plugin" -- "Configure your API key" - -❌ Avoid: -- "Go to Settings and then Community plugins" -- "Turn on the plugin" -- "Setup your API key" \ No newline at end of file diff --git a/.windsurf/rules/versioning-releases.md b/.windsurf/rules/versioning-releases.md deleted file mode 100644 index 3f3de6b..0000000 --- a/.windsurf/rules/versioning-releases.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -trigger: always_on -description: Versioning and release process ---- - -# Versioning & Releases - -## Version Management - -- Bump `version` in `manifest.json` using Semantic Versioning (SemVer) -- Update `versions.json` to map plugin version → minimum app version -- Keep version numbers consistent across all release artifacts - -## Release Process - -1. **Create GitHub release** with tag that exactly matches `manifest.json`'s `version` - - **Do not use a leading `v`** in the tag -2. **Attach required assets** to the release: - - `manifest.json` - - `main.js` - - `styles.css` (if present) -3. After initial release, follow the process to add/update your plugin in the community catalog - -## Testing Before Release - -Manual install for testing: -1. Copy `main.js`, `manifest.json`, `styles.css` (if any) to: - ``` - /.obsidian/plugins// - ``` -2. Reload Obsidian -3. Enable the plugin in **Settings → Community plugins** \ No newline at end of file