pochade-obsidian 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+![Pochade Obsidian Splash Image](./pochade-js-logo.jpg)
+
+# Pochade Obsidian Plugin Generator
+
+## Write Obsidian Plugins with Passion
+
+**Pochade Obsidian** is a modern boilerplate generator for [Obsidian](https://obsidian.md/) plugins. It sets you up with a robust, modular TypeScript environment designed for Agentic AI workflows and clean architecture.
+
+It includes **Context Engineering** files (`LLM.md`, `AGENTS.md`) specifically designed to help Large Language Models (like Gemini, ChatGPT, Claude) understand and generate high-quality Obsidian plugin code.
+
+## Quick Start
+
+Create a new plugin with a single command:
+
+```bash
+npx pochade-obsidian-plugin my-plugin-name
+```
+
+The interactive CLI will ask for:
+1.  **Plugin Name & Description**
+2.  **Author Name**
+3.  **Commands** (comma-separated list of commands to scaffold)
+
+It will then:
+*   🚀 Scaffold a new directory with a modular `src/` structure.
+*   📦 Install dependencies automatically.
+*   ✨ Generate boilerplate code for your specific commands.
+*   🔧 Configure `esbuild` and `TypeScript`.
+*   🔥 Set up Hot Reload support.
+
+## Project Structure
+
+Unlike the default sample plugin, Pochade Obsidian enforces a scalable `src/` structure:
+
+```
+my-plugin-name/
+├── .hotreload          # Trigger file for Obsidian Hot Reload
+├── AGENTS.md           # Guide for AI Agents
+├── LLM.md              # Detailed plugin dev guide for LLMs
+├── manifest.json       # Plugin metadata
+├── esbuild.config.mjs  # Build config
+├── src/
+│   ├── main.ts           # Entry point (Lifecycle & Registration)
+│   ├── settings.ts       # Settings Tab & Interface
+│   └── commands/         # Modular command files
+│       ├── insert-date.ts
+│       └── format-table.ts
+└── styles.css
+```
+
+## AI-Assisted Development
+
+This template is built to work seamlessly with AI coding assistants.
+
+*   **`LLM.md`**: A comprehensive guide on Obsidian API constraints (`requestUrl` vs `fetch`), file structure, and best practices. Feed this to your AI context.
+*   **`AGENTS.md`**: High-level architectural rules.
+
+## Development Workflow
+
+1.  **Go to your project:**
+    ```bash
+    cd my-plugin-name
+    ```
+
+2.  **Start development build (Watch mode):**
+    ```bash
+    npm run dev
+    ```
+
+3.  **Install in Obsidian:**
+    *   Copy your `my-plugin-name` folder to `<Vault>/.obsidian/plugins/`.
+    *   **Pro Tip**: Use a symlink to avoid copying manually.
+
+4.  **Enable Hot Reload:**
+    *   Install the [Hot Reload](https://github.com/pjeby/hot-reload) plugin in Obsidian.
+    *   Enable your plugin in Community Plugins.
+    *   Changes will automatically reload the plugin!
+
+## Features
+
+*   **Interactive CLI**: Define your commands upfront.
+*   **Modular Architecture**: Separates concerns by default (commands, settings, main).
+*   **Strict TypeScript**: configured for safety.
+*   **Agent Ready**: Documentation included to bootstrap AI understanding.
+
+## License
+
+Unlicense (Public Domain). Write code freely.

package/bin/create-pochade-js.js

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+
+/**
+ * create-pochade-js (Obsidian Plugin Edition)
+ * 
+ * Creates a new Obsidian plugin project from the template.
+ */
+
+const spawn = require('cross-spawn');
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+// Utilities
+const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+});
+
+const ask = (question, defaultVal = '') => {
+    return new Promise((resolve) => {
+        const prompt = defaultVal ? `${question} (${defaultVal}): ` : `${question}: `;
+        rl.question(prompt, (answer) => {
+            resolve(answer.trim() || defaultVal);
+        });
+    });
+};
+
+// CamelCase to kebab-case
+const toKebabCase = (str) => {
+    return str
+        .replace(/([a-z])([A-Z])/g, '$1-$2')
+        .replace(/[\s_]+/g, '-')
+        .toLowerCase();
+};
+
+// CamelCase helper for class names
+const toCamelCase = (str) => {
+    return str.replace(/(?:^\w|[A-Z]|\b\w)/g, (word, index) => {
+        return index === 0 ? word.toLowerCase() : word.toUpperCase();
+    }).replace(/\s+/g, '');
+};
+
+const toPascalCase = (str) => {
+    const camel = toCamelCase(str);
+    return camel.charAt(0).toUpperCase() + camel.slice(1);
+}
+
+async function createPlugin() {
+    const logo = ".-. .-. .-. . . .-. .-. .-.   . .-.\r\n|-\' | | |   |-| |-| |  )|-    | `-.\r\n\'   `-\' `-\' \' ` ` \' `-\' `-\' `-\' `-\'\r\n       Obsidian Plugin Gen\r\n             By LNSY\r\n"
+    console.log(logo);
+
+    // 1. Collect Info
+    let projectName = process.argv[2];
+    if (!projectName) {
+        projectName = await ask('Plugin ID (kebab-case folder name)', 'my-obsidian-plugin');
+    }
+
+    // Ensure kebab case
+    projectName = toKebabCase(projectName);
+
+    const pluginName = await ask('Plugin Name (Human Readable)', toPascalCase(projectName));
+    const pluginDesc = await ask('Description', 'A super cool Obsidian plugin');
+    const author = await ask('Author', 'Mister Anderson');
+
+    // Ask for commands
+    console.log('\nDefine your commands. Enter them as a comma-separated list.');
+    console.log('e.g. "Insert Date, Format Table, Toggle Mode"');
+    const commandsInput = await ask('Commands', '');
+    const commands = commandsInput.split(',').map(c => c.trim()).filter(c => c.length > 0);
+
+    const projectDir = path.resolve(process.cwd(), projectName);
+
+    if (fs.existsSync(projectDir)) {
+        console.error(`\n❌ Error: Directory "${projectName}" already exists.`);
+        process.exit(1);
+    }
+
+    console.log(`\n🚀 Scaffolding ${pluginName} in ${projectDir}...`);
+
+    // 2. Create Directory & Copy Template
+    fs.mkdirSync(projectDir, { recursive: true });
+
+    const templateDir = path.resolve(__dirname, '..', 'template');
+    fs.cpSync(templateDir, projectDir, { recursive: true });
+
+    // 3. Structure Restructuring (Move to src/)
+    const srcDir = path.join(projectDir, 'src');
+    fs.mkdirSync(srcDir);
+    const cmdDir = path.join(srcDir, 'commands');
+    fs.mkdirSync(cmdDir);
+
+    // Move main.ts and delete old one
+    // We will actually GENERATE a completely new main.ts, so we can delete the template one.
+    if (fs.existsSync(path.join(projectDir, 'main.ts'))) {
+        fs.unlinkSync(path.join(projectDir, 'main.ts'));
+    }
+
+    // 4. Generate Command Files
+    const commandImports = [];
+    const commandRegistrations = [];
+
+    commands.forEach(cmd => {
+        const cmdId = toKebabCase(cmd);
+        const cmdFnName = toCamelCase(cmd);
+        const cmdFileName = `${cmdId}.ts`;
+        const cmdPath = path.join(cmdDir, cmdFileName);
+
+        const fileContent = `import { Editor, MarkdownView, Notice } from 'obsidian';
+import { MyPluginSettings } from '../settings';
+
+export function ${cmdFnName}(editor: Editor, settings: MyPluginSettings) {
+    new Notice('Running ${cmd}!');
+    console.log('${cmd} requested');
+    // Implementation here
+    const cursor = editor.getCursor();
+    editor.replaceRange(' [${cmd}] ', cursor);
+}
+`;
+        fs.writeFileSync(cmdPath, fileContent);
+
+        commandImports.push(`import { ${cmdFnName} } from './commands/${cmdId}';`);
+        commandRegistrations.push(`
+        this.addCommand({
+            id: '${cmdId}',
+            name: '${cmd}',
+            editorCallback: (editor: Editor, view: MarkdownView) => {
+                ${cmdFnName}(editor, this.settings);
+            }
+        });`);
+    });
+
+    // 5. Generate Settings.ts
+    const settingsContent = `import { App, PluginSettingTab, Setting } from 'obsidian';
+import MyPlugin from './main';
+
+export interface MyPluginSettings {
+    mySetting: string;
+}
+
+export const DEFAULT_SETTINGS: MyPluginSettings = {
+    mySetting: 'default'
+}
+
+export class SampleSettingTab extends PluginSettingTab {
+    plugin: MyPlugin;
+
+    constructor(app: App, plugin: MyPlugin) {
+        super(app, plugin);
+        this.plugin = plugin;
+    }
+
+    display(): void {
+        const {containerEl} = this;
+        containerEl.empty();
+
+        new Setting(containerEl)
+            .setName('Setting #1')
+            .setDesc('It\\'s a secret')
+            .addText(text => text
+                .setPlaceholder('Enter your secret')
+                .setValue(this.plugin.settings.mySetting)
+                .onChange(async (value) => {
+                    this.plugin.settings.mySetting = value;
+                    await this.plugin.saveSettings();
+                }));
+    }
+}
+`;
+    fs.writeFileSync(path.join(srcDir, 'settings.ts'), settingsContent);
+
+    // 6. Generate main.ts
+    const mainContent = `import { App, Editor, MarkdownView, Modal, Notice, Plugin, PluginSettingTab, Setting } from 'obsidian';
+import { MyPluginSettings, DEFAULT_SETTINGS, SampleSettingTab } from './settings';
+${commandImports.join('\n')}
+
+export default class MyPlugin extends Plugin {
+    settings: MyPluginSettings;
+
+    async onload() {
+        await this.loadSettings();
+
+        // Settings Tab
+        this.addSettingTab(new SampleSettingTab(this.app, this));
+
+        // Commands
+${commandRegistrations.join('')}
+    }
+
+    onunload() {
+
+    }
+
+    async loadSettings() {
+        this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData());
+    }
+
+    async saveSettings() {
+        await this.saveData(this.settings);
+    }
+}
+`;
+    fs.writeFileSync(path.join(srcDir, 'main.ts'), mainContent);
+
+    // 7. Update esbuild.config.mjs to point to src/main.ts
+    const esbuildPath = path.join(projectDir, 'esbuild.config.mjs');
+    let esbuildContent = fs.readFileSync(esbuildPath, 'utf8');
+    esbuildContent = esbuildContent.replace('entryPoints: ["main.ts"]', 'entryPoints: ["src/main.ts"]');
+    fs.writeFileSync(esbuildPath, esbuildContent);
+
+    // 8. Update manifest.json
+    const manifestPath = path.join(projectDir, 'manifest.json');
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    manifest.id = projectName;
+    manifest.name = pluginName;
+    manifest.description = pluginDesc;
+    manifest.author = author;
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, '\t'));
+
+    // 9. Update package.json
+    const pkgPath = path.join(projectDir, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    pkg.name = projectName;
+    pkg.description = pluginDesc;
+    pkg.author = author;
+    delete pkg.bin; // remove bin from generated project
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
+
+    // 10. Create .hotreload file
+    fs.writeFileSync(path.join(projectDir, '.hotreload'), '');
+
+    // 11. Rename dotfiles
+    const dotfiles = [
+        { from: 'gitignore', to: '.gitignore' },
+        { from: 'npmignore', to: '.npmignore' },
+        { from: 'envexample', to: '.env.example' }
+    ];
+    dotfiles.forEach(({ from, to }) => {
+        const fromPath = path.join(projectDir, from);
+        if (fs.existsSync(fromPath)) fs.renameSync(fromPath, path.join(projectDir, to));
+    });
+
+    console.log('\n📦 Installing dependencies...');
+    spawn.sync('npm', ['install'], { cwd: projectDir, stdio: 'inherit' });
+
+    console.log(`\n✨ Success! Created ${pluginName} at ./${projectName}`);
+    console.log('\nNext steps:');
+    console.log(`1. cd ${projectName}`);
+    console.log('2. npm run dev');
+    console.log('3. Open Obsidian settings -> Community Plugins -> Enable Your Plugin');
+    console.log('4. We recommend installing the Obsidian Hot Reload plugin for live reloading');
+
+    rl.close();
+}
+
+createPlugin();

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "pochade-obsidian",
+  "version": "0.1.0",
+  "description": "npx starter template for Obsidian Plugins",
+  "bin": {
+    "create-pochade-js": "./bin/create-pochade-js.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lnsy-dev/pochade-obsidian.git"
+  },
+  "keywords": [
+    "obsidian",
+    "plugin",
+    "notes"
+  ],
+  "author": "LNSY",
+  "license": "Unlicense",
+  "bugs": {
+    "url": "https://github.com/lnsy-dev/pochade-obsidian/issues"
+  },
+  "homepage": "https://github.com/lnsy-dev/pochade-obsidian#readme",
+  "dependencies": {
+    "cross-spawn": "^7.0.6"
+  },
+  "files": [
+    "bin/",
+    "template/"
+  ]
+}

package/template/.editorconfig

@@ -0,0 +1,10 @@
+# top-most EditorConfig file
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = tab
+indent_size = 4
+tab_width = 4

package/template/.eslintignore

@@ -0,0 +1,3 @@
+node_modules/
+
+main.js

package/template/.eslintrc

@@ -0,0 +1,23 @@
+{
+    "root": true,
+    "parser": "@typescript-eslint/parser",
+    "env": { "node": true },
+    "plugins": [
+      "@typescript-eslint"
+    ],
+    "extends": [
+      "eslint:recommended",
+      "plugin:@typescript-eslint/eslint-recommended",
+      "plugin:@typescript-eslint/recommended"
+    ], 
+    "parserOptions": {
+        "sourceType": "module"
+    },
+    "rules": {
+      "no-unused-vars": "off",
+      "@typescript-eslint/no-unused-vars": ["error", { "args": "none" }],
+      "@typescript-eslint/ban-ts-comment": "off",
+      "no-prototype-builtins": "off",
+      "@typescript-eslint/no-empty-function": "off"
+    } 
+  }

package/template/AGENTS.md

@@ -0,0 +1,252 @@
+# Obsidian community plugin
+
+## 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`.
+
+## Environment & tooling
+
+- 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). Alternative bundlers like Rollup or webpack are acceptable for other projects if they bundle all external dependencies into `main.js`.
+- Types: `obsidian` type definitions.
+- **Network Calls**: usage of `requestUrl` from the `obsidian` module is **MANDATORY** for all network requests. Do not use `fetch` or node's `http` module to ensure compatibility and avoid CORS issues.
+
+**Note**: This sample project has specific technical dependencies on npm and esbuild. If you're creating a plugin from scratch, you can choose different tools, but you'll need to replace the build configuration accordingly.
+
+### Install
+
+```bash
+npm install
+```
+
+### Dev (watch)
+
+```bash
+npm run dev
+```
+
+### Production build
+
+```bash
+npm run build
+```
+
+## Linting
+
+- To use eslint install eslint from terminal: `npm install -g eslint`
+- To use eslint to analyze this project use this command: `eslint main.ts`
+- eslint will then create a report with suggestions for code improvement by file and line number.
+- If your source code is in a folder, such as `src`, you can use eslint with this command to analyze all files in that folder: `eslint ./src/`
+
+## File & folder conventions
+
+- **Organize code into multiple files**: Split functionality across separate modules rather than putting everything in `main.ts`.
+- Source lives in `src/`. Keep `main.ts` small and focused on plugin lifecycle (loading, unloading, registering commands).
+- **Example file structure**:
+  ```
+  src/
+    main.ts           # Plugin entry point, lifecycle management
+    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
+  ```
+- **Do not commit build artifacts**: Never commit `node_modules/`, `main.js`, or other generated files to version control.
+- Keep the plugin small. Avoid large dependencies. Prefer browser-compatible packages.
+- Generated output should be placed at the plugin root or `dist/` depending on your build setup. Release artifacts must end up at the top level of the plugin folder in the vault (`main.js`, `manifest.json`, `styles.css`).
+
+## Manifest rules (`manifest.json`)
+
+- Must include (non-exhaustive):  
+  - `id` (plugin ID; for local dev it should match the folder name)  
+  - `name`  
+  - `version` (Semantic Versioning `x.y.z`)  
+  - `minAppVersion`  
+  - `description`  
+  - `isDesktopOnly` (boolean)  
+  - Optional: `author`, `authorUrl`, `fundingUrl` (string or map)
+- Never change `id` after release. Treat it as stable API.
+- Keep `minAppVersion` accurate when using newer APIs.
+- Canonical requirements are coded here: https://github.com/obsidianmd/obsidian-releases/blob/master/.github/workflows/validate-plugin-entry.yml
+
+## Testing
+
+- Manual install for testing: copy `main.js`, `manifest.json`, `styles.css` (if any) to:
+  ```
+  <Vault>/.obsidian/plugins/<plugin-id>/
+  ```
+- Reload Obsidian and enable the plugin in **Settings → Community plugins**.
+
+## Commands & settings
+
+- Any user-facing commands should be added via `this.addCommand(...)`.
+- If the plugin has configuration, provide a settings tab and sensible defaults.
+- Persist settings using `this.loadData()` / `this.saveData()`.
+- Use stable command IDs; avoid renaming once released.
+
+## Versioning & releases
+
+- Bump `version` in `manifest.json` (SemVer) and update `versions.json` to map plugin version → minimum app version.
+- Create a GitHub release whose tag exactly matches `manifest.json`'s `version`. Do not use a leading `v`.
+- Attach `manifest.json`, `main.js`, and `styles.css` (if present) to the release as individual assets.
+- After the initial release, follow the process to add/update your plugin in the community catalog as required.
+
+## Security, privacy, and compliance
+
+Follow Obsidian's **Developer Policies** and **Plugin Guidelines**. In particular:
+
+- 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, fetch and eval scripts, or auto-update plugin code outside of normal releases.
+- Minimize scope: read/write only what's necessary inside the vault. Do not access files outside the vault.
+- Clearly disclose any external services used, data sent, and risks.
+- Respect user privacy. Do not collect vault contents, filenames, or personal information unless absolutely necessary and explicitly consented.
+- Avoid deceptive patterns, ads, or spammy notifications.
+- Register and clean up all DOM, app, and interval listeners using the provided `register*` helpers so the plugin unloads safely.
+
+## UX & copy guidelines (for UI text, commands, settings)
+
+- Prefer sentence case for headings, buttons, and titles.
+- Use clear, action-oriented imperatives in step-by-step copy.
+- Use **bold** to indicate literal UI labels. Prefer "select" for interactions.
+- Use arrow notation for navigation: **Settings → Community plugins**.
+- Keep in-app strings short, consistent, and free of jargon.
+
+## 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.
+
+## Coding conventions
+
+- TypeScript with `"strict": true` preferred.
+- **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, consider breaking it into smaller, focused modules.
+- **Use clear module boundaries**: Each file should have a single, well-defined responsibility.
+- Bundle everything into `main.js` (no unbundled runtime deps).
+- Avoid Node/Electron APIs if you want mobile compatibility; set `isDesktopOnly` accordingly.
+- Prefer `async/await` over promise chains; handle errors gracefully.
+
+## Mobile
+
+- Where feasible, test on iOS and Android.
+- Don't assume desktop-only behavior unless `isDesktopOnly` is `true`.
+- Avoid large in-memory structures; be mindful of memory and storage constraints.
+
+## Agent do/don't
+
+**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.
+
+**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.
+
+## Common tasks
+
+### 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));
+```
+
+## Troubleshooting
+
+- Plugin doesn't load after build: ensure `main.js` and `manifest.json` are at the top level of the plugin folder under `<Vault>/.obsidian/plugins/<plugin-id>/`. 
+- Build issues: if `main.js` is missing, run `npm run build` or `npm run dev` to compile your TypeScript source code.
+- Commands not appearing: verify `addCommand` runs after `onload` and IDs are unique.
+- Settings not persisting: ensure `loadData`/`saveData` are awaited and you re-render the UI after changes.
+- Mobile-only issues: confirm you're not using desktop-only APIs; check `isDesktopOnly` and adjust.
+
+## References
+
+- 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

package/template/LICENSE

@@ -0,0 +1,5 @@
+Copyright (C) 2020-2025 by Dynalist Inc.
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/template/LLM.md

@@ -0,0 +1,185 @@
+# Obsidian Plugin Development Guide for LLMs
+
+This document is a comprehensive guide for Large Language Models (LLMs) on how to generate high-quality, maintainable, and compliant Obsidian plugins.
+
+## Core Principles
+
+1.  **Safety & Security**:
+    *   **NO** arbitrary network calls without user consent.
+    *   **NO** remote code execution.
+    *   **NO** accessing files outside the vault.
+    *   **ALWAYS** use `requestUrl` (from `obsidian` module) for HTTP requests, not `fetch`.
+
+2.  **Performance**:
+    *   Minimize work in `onload`.
+    *   Debounce file system listeners.
+    *   Avoid reading the entire vault.
+
+3.  **Modularity**:
+    *   Split code into small, focused files (Single Responsibility Principle).
+    *   Use a `src/` directory structure.
+    *   `src/main.ts`: Entry point, lifecycle management (onload/onunload), registering commands/settings.
+    *   `src/settings.ts`: Settings interface and Tab.
+    *   `src/commands/`: Individual command implementations.
+    *   `src/ui/`: Modals, Views, and other UI components.
+
+## TypeScript & API Usage
+
+*   **Strict Typing**: Always use TypeScript with `strict: true`. Avoid `any`.
+*   **Obsidian API**: Import types and classes from `obsidian`.
+    *   `Plugin`, `App`, `Editor`, `MarkdownView`, `Modal`, `Notice`, `Setting`, `PluginSettingTab`.
+*   **Asynchronous Operations**: Use `async/await` for all file I/O and network operations.
+
+## File Structure Standard
+
+Generate plugins using this directory structure:
+
+```
+src/
+├── main.ts           # Plugin entry point
+├── settings.ts       # Settings definition & UI
+├── types.ts          # Shared interfaces
+├── utils/            # Helper functions
+└── commands/         # Separate file for each command logic (optional but recommended for complex commands)
+    ├── insert-date.ts
+    └── format-table.ts
+styles.css            # CSS styles
+manifest.json         # Plugin metadata
+esbuild.config.mjs    # Build configuration
+```
+
+## Implementation Patterns
+
+### 1. `src/main.ts` (Entry Point)
+
+The `main.ts` should be minimal. It orchestrates the plugin's components.
+
+```typescript
+import { Plugin } from 'obsidian';
+import { MyPluginSettings, DEFAULT_SETTINGS, SampleSettingTab } from './settings';
+import { insertDateCommand } from './commands/insert-date';
+
+export default class MyPlugin extends Plugin {
+    settings: MyPluginSettings;
+
+    async onload() {
+        await this.loadSettings();
+
+        // Register Commands
+        this.addCommand({
+            id: 'insert-date',
+            name: 'Insert Date',
+            editorCallback: (editor) => insertDateCommand(editor, this.settings)
+        });
+
+        // Add Settings Tab
+        this.addSettingTab(new SampleSettingTab(this.app, this));
+    }
+
+    async loadSettings() {
+        this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData());
+    }
+
+    async saveSettings() {
+        await this.saveData(this.settings);
+    }
+}
+```
+
+### 2. Network Requests (`requestUrl`)
+
+**CRITICAL**: Do NOT use `fetch`. Use `requestUrl` to avoid CORS issues and adhere to Obsidian's API.
+
+```typescript
+import { requestUrl, RequestUrlParam } from 'obsidian';
+
+async function fetchData(url: string) {
+    try {
+        const response = await requestUrl({
+            url: url,
+            method: 'GET',
+            headers: {
+                'Content-Type': 'application/json'
+            }
+        });
+        
+        if (response.status !== 200) {
+            throw new Error(`Failed to fetch: ${response.status}`);
+        }
+
+        return response.json;
+    } catch (error) {
+        console.error('API Error:', error);
+        throw error;
+    }
+}
+```
+
+### 3. Modifing Content (Editor Transactions)
+
+Use the `Editor` interface for text manipulation.
+
+```typescript
+import { Editor } from 'obsidian';
+
+export function insertText(editor: Editor, text: string) {
+    const cursor = editor.getCursor();
+    editor.replaceRange(text, cursor);
+    // Move cursor to end of inserted text
+    editor.setCursor({
+        line: cursor.line,
+        ch: cursor.ch + text.length
+    });
+}
+```
+
+### 4. Settings (`src/settings.ts`)
+
+```typescript
+import { App, PluginSettingTab, Setting } from 'obsidian';
+import MyPlugin from './main';
+
+export interface MyPluginSettings {
+    dateFormat: string;
+}
+
+export const DEFAULT_SETTINGS: MyPluginSettings = {
+    dateFormat: 'YYYY-MM-DD'
+};
+
+export class SampleSettingTab extends PluginSettingTab {
+    plugin: MyPlugin;
+
+    constructor(app: App, plugin: MyPlugin) {
+        super(app, plugin);
+        this.plugin = plugin;
+    }
+
+    display(): void {
+        const { containerEl } = this;
+        containerEl.empty();
+
+        new Setting(containerEl)
+            .setName('Date Format')
+            .setDesc('Moment.js format string')
+            .addText(text => text
+                .setPlaceholder('YYYY-MM-DD')
+                .setValue(this.plugin.settings.dateFormat)
+                .onChange(async (value) => {
+                    this.plugin.settings.dateFormat = value;
+                    await this.plugin.saveSettings();
+                }));
+    }
+}
+```
+
+## Hot Reloading
+
+This project is set up for hot reloading. A `.hotreload` file is present in the root. Ensure you have the "Hot Reload" plugin installed in Obsidian for this to work during development.
+
+## Build System
+
+*   **esbuild** is the bundler.
+*   **src/main.ts** is the entry point.
+*   **main.js** is the output (bundled) file.
+*   Do NOT modify `main.js` manually. 

package/template/README.md

@@ -0,0 +1,94 @@
+# Obsidian Sample Plugin
+
+This is a sample plugin for Obsidian (https://obsidian.md).
+
+This project uses TypeScript to provide type checking and documentation.
+The repo depends on the latest plugin API (obsidian.d.ts) in TypeScript Definition format, which contains TSDoc comments describing what it does.
+
+This sample plugin demonstrates some of the basic functionality the plugin API can do.
+- Adds a ribbon icon, which shows a Notice when clicked.
+- Adds a command "Open Sample Modal" which opens a Modal.
+- Adds a plugin setting tab to the settings page.
+- Registers a global click event and output 'click' to the console.
+- Registers a global interval which logs 'setInterval' to the console.
+
+## First time developing plugins?
+
+Quick starting guide for new plugin devs:
+
+- Check if [someone already developed a plugin for what you want](https://obsidian.md/plugins)! There might be an existing plugin similar enough that you can partner up with.
+- Make a copy of this repo as a template with the "Use this template" button (login to GitHub if you don't see it).
+- Clone your repo to a local development folder. For convenience, you can place this folder in your `.obsidian/plugins/your-plugin-name` folder.
+- Install NodeJS, then run `npm i` in the command line under your repo folder.
+- Run `npm run dev` to compile your plugin from `main.ts` to `main.js`.
+- Make changes to `main.ts` (or create new `.ts` files). Those changes should be automatically compiled into `main.js`.
+- Reload Obsidian to load the new version of your plugin.
+- Enable plugin in settings window.
+- For updates to the Obsidian API run `npm update` in the command line under your repo folder.
+
+## Releasing new releases
+
+- Update your `manifest.json` with your new version number, such as `1.0.1`, and the minimum Obsidian version required for your latest release.
+- Update your `versions.json` file with `"new-plugin-version": "minimum-obsidian-version"` so older versions of Obsidian can download an older version of your plugin that's compatible.
+- Create new GitHub release using your new version number as the "Tag version". Use the exact version number, don't include a prefix `v`. See here for an example: https://github.com/obsidianmd/obsidian-sample-plugin/releases
+- Upload the files `manifest.json`, `main.js`, `styles.css` as binary attachments. Note: The manifest.json file must be in two places, first the root path of your repository and also in the release.
+- Publish the release.
+
+> You can simplify the version bump process by running `npm version patch`, `npm version minor` or `npm version major` after updating `minAppVersion` manually in `manifest.json`.
+> The command will bump version in `manifest.json` and `package.json`, and add the entry for the new version to `versions.json`
+
+## Adding your plugin to the community plugin list
+
+- Check the [plugin guidelines](https://docs.obsidian.md/Plugins/Releasing/Plugin+guidelines).
+- Publish an initial version.
+- Make sure you have a `README.md` file in the root of your repo.
+- Make a pull request at https://github.com/obsidianmd/obsidian-releases to add your plugin.
+
+## How to use
+
+- Clone this repo.
+- Make sure your NodeJS is at least v16 (`node --version`).
+- `npm i` or `yarn` to install dependencies.
+- `npm run dev` to start compilation in watch mode.
+
+## Manually installing the plugin
+
+- Copy over `main.js`, `styles.css`, `manifest.json` to your vault `VaultFolder/.obsidian/plugins/your-plugin-id/`.
+
+## Improve code quality with eslint (optional)
+- [ESLint](https://eslint.org/) is a tool that analyzes your code to quickly find problems. You can run ESLint against your plugin to find common bugs and ways to improve your code. 
+- To use eslint with this project, make sure to install eslint from terminal:
+  - `npm install -g eslint`
+- To use eslint to analyze this project use this command:
+  - `eslint main.ts`
+  - eslint will then create a report with suggestions for code improvement by file and line number.
+- If your source code is in a folder, such as `src`, you can use eslint with this command to analyze all files in that folder:
+  - `eslint ./src/`
+
+## Funding URL
+
+You can include funding URLs where people who use your plugin can financially support it.
+
+The simple way is to set the `fundingUrl` field to your link in your `manifest.json` file:
+
+```json
+{
+    "fundingUrl": "https://buymeacoffee.com"
+}
+```
+
+If you have multiple URLs, you can also do:
+
+```json
+{
+    "fundingUrl": {
+        "Buy Me a Coffee": "https://buymeacoffee.com",
+        "GitHub Sponsor": "https://github.com/sponsors",
+        "Patreon": "https://www.patreon.com/"
+    }
+}
+```
+
+## API Documentation
+
+See https://github.com/obsidianmd/obsidian-api

package/template/esbuild.config.mjs

@@ -0,0 +1,49 @@
+import esbuild from "esbuild";
+import process from "process";
+import builtins from "builtin-modules";
+
+const banner =
+`/*
+THIS IS A GENERATED/BUNDLED FILE BY ESBUILD
+if you want to view the source, please visit the github repository of this plugin
+*/
+`;
+
+const prod = (process.argv[2] === "production");
+
+const context = await esbuild.context({
+	banner: {
+		js: banner,
+	},
+	entryPoints: ["main.ts"],
+	bundle: true,
+	external: [
+		"obsidian",
+		"electron",
+		"@codemirror/autocomplete",
+		"@codemirror/collab",
+		"@codemirror/commands",
+		"@codemirror/language",
+		"@codemirror/lint",
+		"@codemirror/search",
+		"@codemirror/state",
+		"@codemirror/view",
+		"@lezer/common",
+		"@lezer/highlight",
+		"@lezer/lr",
+		...builtins],
+	format: "cjs",
+	target: "es2018",
+	logLevel: "info",
+	sourcemap: prod ? false : "inline",
+	treeShaking: true,
+	outfile: "main.js",
+	minify: prod,
+});
+
+if (prod) {
+	await context.rebuild();
+	process.exit(0);
+} else {
+	await context.watch();
+}

package/template/main.ts

@@ -0,0 +1,134 @@
+import { App, Editor, MarkdownView, Modal, Notice, Plugin, PluginSettingTab, Setting } from 'obsidian';
+
+// Remember to rename these classes and interfaces!
+
+interface MyPluginSettings {
+	mySetting: string;
+}
+
+const DEFAULT_SETTINGS: MyPluginSettings = {
+	mySetting: 'default'
+}
+
+export default class MyPlugin extends Plugin {
+	settings: MyPluginSettings;
+
+	async onload() {
+		await this.loadSettings();
+
+		// This creates an icon in the left ribbon.
+		const ribbonIconEl = this.addRibbonIcon('dice', 'Sample Plugin', (_evt: MouseEvent) => {
+			// Called when the user clicks the icon.
+			new Notice('This is a notice!');
+		});
+		// Perform additional things with the ribbon
+		ribbonIconEl.addClass('my-plugin-ribbon-class');
+
+		// This adds a status bar item to the bottom of the app. Does not work on mobile apps.
+		const statusBarItemEl = this.addStatusBarItem();
+		statusBarItemEl.setText('Status Bar Text');
+
+		// This adds a simple command that can be triggered anywhere
+		this.addCommand({
+			id: 'open-sample-modal-simple',
+			name: 'Open sample modal (simple)',
+			callback: () => {
+				new SampleModal(this.app).open();
+			}
+		});
+		// This adds an editor command that can perform some operation on the current editor instance
+		this.addCommand({
+			id: 'sample-editor-command',
+			name: 'Sample editor command',
+			editorCallback: (editor: Editor, _view: MarkdownView) => {
+				console.log(editor.getSelection());
+				editor.replaceSelection('Sample Editor Command');
+			}
+		});
+		// This adds a complex command that can check whether the current state of the app allows execution of the command
+		this.addCommand({
+			id: 'open-sample-modal-complex',
+			name: 'Open sample modal (complex)',
+			checkCallback: (checking: boolean) => {
+				// Conditions to check
+				const markdownView = this.app.workspace.getActiveViewOfType(MarkdownView);
+				if (markdownView) {
+					// If checking is true, we're simply "checking" if the command can be run.
+					// If checking is false, then we want to actually perform the operation.
+					if (!checking) {
+						new SampleModal(this.app).open();
+					}
+
+					// This command will only show up in Command Palette when the check function returns true
+					return true;
+				}
+			}
+		});
+
+		// This adds a settings tab so the user can configure various aspects of the plugin
+		this.addSettingTab(new SampleSettingTab(this.app, this));
+
+		// If the plugin hooks up any global DOM events (on parts of the app that doesn't belong to this plugin)
+		// Using this function will automatically remove the event listener when this plugin is disabled.
+		this.registerDomEvent(document, 'click', (evt: MouseEvent) => {
+			console.log('click', evt);
+		});
+
+		// When registering intervals, this function will automatically clear the interval when the plugin is disabled.
+		this.registerInterval(window.setInterval(() => console.log('setInterval'), 5 * 60 * 1000));
+	}
+
+	onunload() {
+
+	}
+
+	async loadSettings() {
+		this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData());
+	}
+
+	async saveSettings() {
+		await this.saveData(this.settings);
+	}
+}
+
+class SampleModal extends Modal {
+	constructor(app: App) {
+		super(app);
+	}
+
+	onOpen() {
+		const {contentEl} = this;
+		contentEl.setText('Woah!');
+	}
+
+	onClose() {
+		const {contentEl} = this;
+		contentEl.empty();
+	}
+}
+
+class SampleSettingTab extends PluginSettingTab {
+	plugin: MyPlugin;
+
+	constructor(app: App, plugin: MyPlugin) {
+		super(app, plugin);
+		this.plugin = plugin;
+	}
+
+	display(): void {
+		const {containerEl} = this;
+
+		containerEl.empty();
+
+		new Setting(containerEl)
+			.setName('Setting #1')
+			.setDesc('It\'s a secret')
+			.addText(text => text
+				.setPlaceholder('Enter your secret')
+				.setValue(this.plugin.settings.mySetting)
+				.onChange(async (value) => {
+					this.plugin.settings.mySetting = value;
+					await this.plugin.saveSettings();
+				}));
+	}
+}

package/template/manifest.json

@@ -0,0 +1,11 @@
+{
+	"id": "sample-plugin",
+	"name": "Sample Plugin",
+	"version": "1.0.0",
+	"minAppVersion": "0.15.0",
+	"description": "Demonstrates some of the capabilities of the Obsidian API.",
+	"author": "Obsidian",
+	"authorUrl": "https://obsidian.md",
+	"fundingUrl": "https://obsidian.md/pricing",
+	"isDesktopOnly": false
+}

package/template/package.json

@@ -0,0 +1,24 @@
+{
+	"name": "obsidian-sample-plugin",
+	"version": "1.0.0",
+	"description": "This is a sample plugin for Obsidian (https://obsidian.md)",
+	"main": "main.js",
+	"scripts": {
+		"dev": "node esbuild.config.mjs",
+		"build": "tsc -noEmit -skipLibCheck && node esbuild.config.mjs production",
+		"version": "node version-bump.mjs && git add manifest.json versions.json"
+	},
+	"keywords": [],
+	"author": "",
+	"license": "MIT",
+	"devDependencies": {
+		"@types/node": "^16.11.6",
+		"@typescript-eslint/eslint-plugin": "5.29.0",
+		"@typescript-eslint/parser": "5.29.0",
+		"builtin-modules": "3.3.0",
+		"esbuild": "0.17.3",
+		"obsidian": "latest",
+		"tslib": "2.4.0",
+		"typescript": "4.7.4"
+	}
+}

package/template/styles.css

@@ -0,0 +1,8 @@
+/*
+
+This CSS file will be included with your plugin, and
+available in the app when your plugin is enabled.
+
+If your plugin does not need CSS, delete this file.
+
+*/

package/template/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "module": "ESNext",
+    "target": "ES6",
+    "allowJs": true,
+    "noImplicitAny": true,
+    "moduleResolution": "node",
+    "importHelpers": true,
+    "isolatedModules": true,
+    "strictNullChecks": true,
+    "lib": [
+      "DOM",
+      "ES5",
+      "ES6",
+      "ES7"
+    ]
+  },
+  "include": [
+    "**/*.ts"
+  ]
+}

package/template/version-bump.mjs

@@ -0,0 +1,17 @@
+import { readFileSync, writeFileSync } from "fs";
+
+const targetVersion = process.env.npm_package_version;
+
+// read minAppVersion from manifest.json and bump version to target version
+const manifest = JSON.parse(readFileSync("manifest.json", "utf8"));
+const { minAppVersion } = manifest;
+manifest.version = targetVersion;
+writeFileSync("manifest.json", JSON.stringify(manifest, null, "\t"));
+
+// update versions.json with target version and minAppVersion from manifest.json
+// but only if the target version is not already in versions.json
+const versions = JSON.parse(readFileSync('versions.json', 'utf8'));
+if (!Object.values(versions).includes(minAppVersion)) {
+    versions[targetVersion] = minAppVersion;
+    writeFileSync('versions.json', JSON.stringify(versions, null, '\t'));
+}

package/template/versions.json

@@ -0,0 +1,3 @@
+{
+	"1.0.0": "0.15.0"
+}