feat: optional selection only mode (#14)

* feat: introduce optional selection-only mode

* fix: do not render suggestions if they're not present

* docs: explain selection-only option in the readme

Author: chernodub

README.md

@@ -25,6 +25,30 @@ Becomes a list of commands:
 - 📚 Prompt Library: Organize prompts in a folder structure
 - 🔥 Instant Commands: Your prompts transform into Obsidian commands
 
+## Extra Features
+
+### Selection-Only Commands
+
+Some prompts work best when applied to a specific selection of text. You can mark a command as selection-only by adding frontmatter to your prompt file:
+
+```yaml
+---
+llm-shortcut-selection-mode: selection-only
+---
+
+Your prompt content here...
+```
+
+When a command is marked as selection-only, it will:
+
+- Require text to be selected before execution
+- Show an error notification if you try to run it without a selection
+- Only process the selected text (and the document context) when executed
+
+This is useful for prompts that are designed to transform, analyze, or modify specific portions of text rather than working with the entire document.
+
+<video width="350" alt="Demo Selection Only" src="https://github.com/user-attachments/assets/4eabe88a-d4c5-4928-b357-ad0928b7484b" />
+
 ## Example
 
 Probably the best way to explain the workflow is via this little vid I made:

src/main.ts

@@ -21,6 +21,18 @@ import { PLUGIN_NAME } from "./utils/constants";
 import { mapCursorPositionToIdx } from "./utils/obsidian/map-position-to-idx";
 import { obsidianFetchAdapter } from "./utils/obsidian/obsidian-fetch-adapter";
 
+const SELECTION_MODE_TAG = "llm-shortcut-selection-mode";
+const SELECTION_ONLY_VALUE = "selection-only";
+
+interface CommandOptions {
+  readonly shouldHandleSelectionOnly?: boolean;
+}
+
+export interface ParsedCommandPrompt {
+  readonly content: string;
+  readonly options?: CommandOptions;
+}
+
 interface PluginSettings {
   apiKey: string;
   providerUrl: string;
@@ -63,6 +75,13 @@ export default class LlmShortcutPlugin extends Plugin {
       file.path.startsWith(this.settings.promptLibraryDirectory);
 
     this.eventRefs = [
+      this.app.metadataCache.on("changed", (file) => {
+        if (!isPromptLibraryDirectory(file)) {
+          return;
+        }
+
+        this.recurseOverAbstractFile(file, file.parent?.path.split("/") ?? []);
+      }),
       this.app.vault.on("modify", (file) => {
         if (!isPromptLibraryDirectory(file)) {
           return;
@@ -131,45 +150,104 @@ export default class LlmShortcutPlugin extends Plugin {
 
       logger.debug(`Added command ${readableCommandName}`);
 
-      this.addCommandBasedOnPrompt(
-        readableCommandName,
-        file.path,
-        await file.vault.read(file),
-      );
+      const { content, options } = await this.parseCommandPromptFromFile(file);
+
+      this.addCommandBasedOnPrompt({
+        name: readableCommandName,
+        path: file.path,
+        prompt: content,
+        options,
+      });
     } else if (file instanceof TFolder) {
       for (const child of file.children) {
         this.recurseOverAbstractFile(child, currentPath);
       }
     }
   }
 
-  private addCommandBasedOnPrompt(name: string, path: string, prompt: string) {
+  private async parseCommandPromptFromFile(
+    file: TFile,
+  ): Promise<ParsedCommandPrompt> {
+    const fileContent = await file.vault.read(file);
+    // Danger! The cache could be stale (but we're listening to changes so this will be overriden next run)
+    const metadata = this.app.metadataCache.getFileCache(file);
+
+    // Use Obsidian's parsed frontmatter if available
+    if (!metadata?.frontmatter || !metadata.frontmatterPosition) {
+      return { content: fileContent };
+    }
+    const shouldHandleSelectionOnly =
+      metadata.frontmatter[SELECTION_MODE_TAG] === SELECTION_ONLY_VALUE;
+
+    const content = fileContent
+      .slice(metadata.frontmatterPosition.end.offset)
+      .trimStart();
+
+    return {
+      content,
+      options: {
+        shouldHandleSelectionOnly,
+      },
+    };
+  }
+
+  private addCommandBasedOnPrompt({
+    name,
+    path,
+    prompt,
+    options,
+  }: {
+    readonly name: string;
+    readonly path: string;
+    readonly prompt: string;
+    readonly options: CommandOptions | undefined;
+  }) {
     const command = {
       id: path,
       name,
-      editorCallback: this.handleRespond.bind(this, prompt),
+      editorCallback: this.handleRespond.bind(
+        this,
+        prompt,
+        options?.shouldHandleSelectionOnly ?? false,
+      ),
     };
     this.commands.push(command);
     this.addCommand(command);
   }
 
-  private async handleRespond(systemPrompt: string, editor: Editor) {
+  private async handleRespond(
+    systemPrompt: string,
+    requiresSelection: boolean,
+    editor: Editor,
+  ) {
     assertExists(this.llmClient, "LLM client is not initialized");
 
+    const startIdx = mapCursorPositionToIdx(
+      editor.getValue(),
+      editor.getCursor("from"),
+    );
+    const endIdx = mapCursorPositionToIdx(
+      editor.getValue(),
+      editor.getCursor("to"),
+    );
+
+    if (requiresSelection) {
+      if (startIdx === endIdx) {
+        showErrorNotification({
+          title: "This command requires text to be selected",
+        });
+        return;
+      }
+    }
+
     this.loaderStrategy.start();
     try {
       const responseStream = this.llmClient.getResponse({
         userPrompt: {
           currentContent: editor.getValue(),
           selection: {
-            startIdx: mapCursorPositionToIdx(
-              editor.getValue(),
-              editor.getCursor("from"),
-            ),
-            endIdx: mapCursorPositionToIdx(
-              editor.getValue(),
-              editor.getCursor("to"),
-            ),
+            startIdx,
+            endIdx,
           },
         },
         systemPrompt,

src/ui/user-notifications.ts

@@ -20,8 +20,10 @@ export function showErrorNotification(
   let message = withSeparator(`🤖 ${PLUGIN_NAME} Error:`, TWO_LINE_SEP);
   message += withSeparator(options.title, TWO_LINE_SEP);
   message += withSeparator(options.message, TWO_LINE_SEP);
-  message += withSeparator("💡 Suggestions:", TWO_LINE_SEP);
-  message += suggestionsText;
+  if (suggestionsText) {
+    message += withSeparator("💡 Suggestions:", TWO_LINE_SEP);
+    message += suggestionsText;
+  }
 
   new Notice(message, timeout);
 }