@aiderdesk/aiderdesk 0.61.0-dev → 0.61.1

package/out/resources/skills/extension-creator/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: extension-creator
+description: Create AiderDesk extensions by setting up extension files, defining metadata, implementing Extension interface methods, and updating documentation. Use when building a new extension, creating extension commands, tools, or event handlers.
+---
+
+# Extension Creator
+
+Create AiderDesk extensions that extend functionality through events, commands, tools, agents, and modes.
+
+## When to Use
+
+Use this skill when:
+
+- Building a new AiderDesk extension
+- Creating extension commands, tools, or event handlers
+- Implementing the Extension interface
+- Setting up extension metadata and documentation
+
+Do not use when:
+
+- Simply activating an existing extension
+- Making general code changes unrelated to extensions
+- Running tests or builds
+
+## Rules
+
+### Rule: Choose installation target first
+
+**When:** Starting extension creation
+
+**Then:** Ask the user where to install the extension
+
+**If:** Working inside the AiderDesk project (the current project is the aider-desk repository)
+
+**Then:** Offer three options:
+1. **Current Project** — Install to `.aider-desk/extensions/` in the current project (project-scoped)
+2. **Global** — Install to `~/.aider-desk/extensions/` (available in all projects)
+3. **In-Repo** — Create inside `packages/extensions/extensions/` (ships with AiderDesk app)
+
+**If:** Working outside the AiderDesk project
+
+**Then:** Offer two options:
+1. **Current Project** — Install to `.aider-desk/extensions/` in the current project (project-scoped)
+2. **Global** — Install to `~/.aider-desk/extensions/` (available in all projects)
+
+**Must:** Wait for user's choice before proceeding. The chosen target determines the entire workflow.
+
+**Reference:** [references/install-targets.md](references/install-targets.md) for full details on each target.
+
+### Rule: Follow the correct flow for the chosen target
+
+**When:** User has chosen an installation target
+
+**If:** Target is **Current Project** or **Global**
+
+**Then:** Follow the [Project / Global Flow](references/project-global-flow.md):
+1. Determine extension type (single-file or folder)
+2. Create extension file(s) in the target directory (`.aider-desk/extensions/` or `~/.aider-desk/extensions/`)
+3. Implement Extension interface methods
+4. Export metadata and default class
+5. Verify the extension loads (auto-discovered, no registry needed)
+
+**If:** Target is **In-Repo**
+
+**Then:** Follow the [In-Repo Flow](references/in-repo-flow.md):
+1. Determine extension type (single-file or folder)
+2. Create extension file(s) in `packages/extensions/extensions/`
+3. Implement Extension interface methods
+4. Export metadata and default class
+5. **Register in `packages/extensions/extensions.json`**
+6. **Document in `docs-site/docs/extensions/examples.md`**
+7. Install npm dependencies if folder extension
+8. Verify with type checking
+
+### Rule: Determine extension type
+
+**When:** Creating extension files (after target is chosen)
+
+**Then:** Check if extension needs npm dependencies or multiple files
+
+**If:** Extension needs dependencies or multiple files
+
+**Then:** Create folder extension
+
+**If:** Extension is simple with no dependencies
+
+**Then:** Create single-file extension
+
+### Rule: Implement Extension interface
+
+**When:** Creating extension file
+
+**Then:** Implement required methods from Extension interface
+
+**Must:** Define `static metadata` property on the class with name, version, description, author, capabilities
+
+**Must:** Export class as `default` (e.g., `export default class MyExtension implements Extension`)
+
+**Never:** Use `@/` imports in extension files
+
+### Rule: Add UI components when needed
+
+**When:** Extension needs to display UI elements in task page placements
+
+**Then:** Implement `getUIComponents()` method
+
+**Must:** Return array of UIComponentDefinition objects with id, placement, jsx
+
+**Must:** Define components as JSX strings or load from .jsx files
+
+**If:** Component needs data, set `loadData: true` and implement `getUIExtensionData()`
+
+**If:** Component triggers actions, implement `executeUIExtensionAction()`
+
+### Rule: Add config component for extension settings
+
+**When:** Extension needs user-configurable settings (shown in gear icon dialog)
+
+**Then:** Implement three methods: `getConfigComponent()`, `getConfigData()`, `saveConfigData()`
+
+**Must:** Return JSX string from `getConfigComponent()` — use external .jsx file for components > 20 lines
+
+**Must:** Load/merge defaults in `getConfigData()`, persist merged data in `saveConfigData()`
+
+**Must:** Store config file in extension directory via `join(__dirname, 'config.json')`
+
+**Must:** Use `ui.*` components (`ui.Input`, `ui.Checkbox`, etc.) instead of raw HTML elements
+
+**Should:** Avoid inner state (`useState`/`useEffect`) for simple form fields — read directly from `config` prop, call `updateConfig` on change. Only use local state for derived values or transient UI state.
+
+**Never:** Use `'extension-settings'` placement — it was removed; use the dedicated config API instead
+
+### Rule: Update registry and docs (In-Repo only)
+
+**When:** Target is In-Repo and extension file is created
+
+**Then:** Add entry to `packages/extensions/extensions.json`
+
+**Must:** Include id, name, description, file or folder path, type, capabilities
+
+**Must:** Set `hasDependencies: true` for folder extensions
+
+**Then:** Add entry to `docs-site/docs/extensions/examples.md` table
+
+**Must:** Include extension name, description, capabilities, and type
+
+**When:** Target is Project or Global
+
+**Then:** Do NOT modify `extensions.json` or `examples.md` — these are only for built-in extensions
+
+### Rule: Use proper TypeScript config for folders
+
+**When:** Creating folder extension
+
+**Then:** Include `tsconfig.json` with `module: ES2020+`
+
+**Must:** Include `package.json` with name, version, main, dependencies
+
+### Rule: Store config in extension directory
+
+**When:** Extension needs persistent config
+
+**Then:** Store config files in extension directory
+
+**Never:** Store config outside extension directory
+
+## Process Overview
+
+### For Project / Global targets:
+
+1. Ask user: Current Project or Global?
+2. Determine extension type (single-file or folder)
+3. Create extension file or directory structure in target dir
+4. Implement Extension interface methods
+5. Export metadata and default class
+6. Verify extension loads (auto-discovered)
+
+**Between steps 3 and 5:**
+- If extension needs config storage, create config.ts (or use inline getConfigData/saveConfigData)
+- If extension has a settings UI (config component), create ConfigComponent.jsx and implement the three config methods
+- If extension needs logging, create logger.ts
+- If extension needs constants, create constants.ts
+- If extension has placement-based UI components, create .jsx files for components (recommended for components > 20 lines)
+
+### For In-Repo target:
+
+1. Confirm user wants In-Repo (only available in aider-desk project)
+2. Determine extension type (single-file or folder)
+3. Create extension file or directory structure in `packages/extensions/extensions/`
+4. Implement Extension interface methods
+5. Export metadata and default class
+6. **Register in `packages/extensions/extensions.json`**
+7. **Document in `docs-site/docs/extensions/examples.md`**
+8. Run `npm install` in `packages/extensions/` (folder extensions)
+9. Verify with type checking
+
+**Between steps 3 and 5:**
+- Same optional files as Project/Global flow above
+
+## Preconditions
+
+Before using this skill, verify:
+
+- Installation target has been chosen by the user
+- Extension purpose and required capabilities are clear
+- Extension type (single-file or folder) is determined
+- Extension interface and types are understood
+
+If any precondition fails:
+
+- Review [packages/common/src/extensions.ts](https://raw.githubusercontent.com/hotovo/aider-desk/refs/heads/main/packages/common/src/extensions.ts) for types
+- Check [references/install-targets.md](references/install-targets.md) for target options
+- Check [references/event-types.md](references/event-types.md) for event types
+- Check [references/command-definition.md](references/command-definition.md) for command structure
+
+## Postconditions
+
+After completing this skill, verify:
+
+- Extension implements Extension interface correctly
+- Static `metadata` property on the class includes all required fields (name, version)
+- Default export is the extension class
+- No `@/` imports used
+- **If In-Repo:** extensions.json updated correctly
+- **If In-Repo:** docs-site/docs/extensions/examples.md updated
+- **If In-Repo:** Type checking passes
+- Extension loads without errors
+- Extension appears in extensions list
+- Extension capabilities work as expected
+
+**Success metrics:**
+
+- Extension loads without errors
+- Extension appears in extensions list
+- Extension capabilities work as expected
+
+## Common Situations
+
+**Situation:** Extension needs to handle events
+
+**Pattern:**
+- When: Extension needs to modify agent behavior
+- Then: Implement event handler methods (onAgentStarted, onToolCalled, etc.)
+- Return: Partial event object to modify behavior
+
+**Situation:** Extension needs to register commands
+
+**Pattern:**
+- When: Extension provides slash commands
+- Then: Implement getCommands() method
+- Return: Array of CommandDefinition objects
+
+**Situation:** Extension needs to add UI components
+
+**Pattern:**
+- When: Extension needs to display information in UI
+- Then: Implement getUIComponents() method
+- Return: Array of UIComponentDefinition objects
+- Use: JSX strings or external .jsx files
+- Load data: Implement getUIExtensionData() if component needs data
+- Handle actions: Implement executeUIExtensionAction() for user interactions
+
+**Situation:** Extension needs to log messages
+
+**Pattern:**
+- If: Debug/internal logging (developer diagnostics, not shown to users)
+- Then: Use `context.log(message, type)` — logs to backend console only
+- If: User-visible output (showing results, status, timing info in the chat)
+- Then: Use `context.getTaskContext()?.addLogMessage(level, message)` — displays in task's chat UI
+- When ambiguous: If the user says "log", "show", "display", or "report" something, default to `addLogMessage` (user-visible). Use `context.log` only for internal diagnostics.
+- Note: `context.log` is always available; `getTaskContext()` returns `null` outside a task, so always use optional chaining (`?.`)
+
+**Situation:** Extension needs config storage
+
+**Pattern:**
+- Check: Extension needs persistent settings
+- If yes: Create config.ts with loadConfig and saveConfig functions
+- Store: Config files in extension directory
+
+**Situation:** Extension needs a settings UI (config component)
+
+**Pattern:**
+- When: Extension has user-configurable options that should appear in the Settings dialog
+- Then: Implement `getConfigComponent()`, `getConfigData()`, `saveConfigData()` methods
+- JSX: Return a `.jsx` file content via `readFileSync(join(__dirname, './ConfigComponent.jsx'), 'utf-8')`
+- Props: Component receives `{ config, updateConfig, ui, icons, models, providers, ... }`
+- Flow: Dialog opens → loads data via getConfigData → renders JSX with props → user edits → Save calls saveConfigData
+- Reference: [config-components.md](references/config-components.md) for full guide and examples
+
+## References
+
+### Target Selection
+
+- [install-targets.md](references/install-targets.md) - All three installation targets, when to use each, key differences
+
+### Flows
+
+- [project-global-flow.md](references/project-global-flow.md) - Step-by-step for Project and Global installations
+- [in-repo-flow.md](references/in-repo-flow.md) - Step-by-step for In-Repo (packages/extensions/) installations
+
+### Technical Reference (all targets)
+
+- [packages/common/src/extensions.ts](https://raw.githubusercontent.com/hotovo/aider-desk/refs/heads/main/packages/common/src/extensions.ts) - Extension types and interfaces
+- [extension-interface.md](references/extension-interface.md) - Full Extension interface, ExtensionContext, TaskContext, Metadata
+- [extension-types.md](references/extension-types.md) - Single-file vs folder extensions, examples, extensions.json format
+- [event-types.md](references/event-types.md) - All event types and payloads
+- [command-definition.md](references/command-definition.md) - Command structure
+- [ui-components.md](references/ui-components.md) - UI component system, placements, and available components
+- [config-components.md](references/config-components.md) - Config component API (settings UI), methods, JSX format, and patterns
+- [examples-gallery.md](references/examples-gallery.md) - Real extension examples
+
+## Assets
+
+- [templates/single-file.ts.template](assets/templates/single-file.ts.template) - Single-file template
+- [templates/folder-extension/](assets/templates/folder-extension/) - Folder template (basic)
+- [templates/folder-extension-with-config/index.ts.template](assets/templates/folder-extension-with-config/index.ts.template) - Folder template with config component API
+- [templates/ui-component.ts.template](assets/templates/ui-component.ts.template) - UI component inline template
+- [templates/ui-component-external.ts.template](assets/templates/ui-component-external.ts.template) - UI component with external JSX
+- [templates/Component.jsx.template](assets/templates/Component.jsx.template) - Placement-based JSX component template
+- [templates/ConfigComponent.jsx.template](assets/templates/ConfigComponent.jsx.template) - Config/settings JSX component template

package/out/resources/skills/extension-creator/assets/templates/Component.jsx.template

@@ -0,0 +1,76 @@
+/**
+ * UI Component for {{EXTENSION_NAME}}
+ * 
+ * Note: React is globally available (use React.useState, React.useEffect, etc.)
+ * 
+ * Available props (via 'props' or destructured):
+ * - data: Data from getUIExtensionData()
+ * - task: Current TaskData
+ * - projectDir: Project directory path
+ * - models: Available models
+ * - providers: Available providers
+ * - ui: UI components (Button, Checkbox, Input, etc.)
+ * - icons: React Icons organized by set (Fi, Hi, Cg, etc.)
+ * - executeExtensionAction: Function to call extension actions
+ */
+
+(props) => {
+  const { data, task, ui, icons, executeExtensionAction } = props;
+  const { useState, useCallback } = React;
+  const { Button } = ui;
+  const { FiCheckCircle } = icons.Fi;
+  
+  // Early return if no data
+  if (!data) return null;
+  
+  // Local state
+  const [isHovered, setIsHovered] = useState(false);
+  
+  // Event handlers
+  const handleIncrement = useCallback(async () => {
+    const result = await executeExtensionAction('increment');
+    console.log('Increment result:', result);
+  }, [executeExtensionAction]);
+  
+  const handleSetMessage = useCallback(async () => {
+    await executeExtensionAction('set-message', 'New message!');
+  }, [executeExtensionAction]);
+  
+  return (
+    <div 
+      className="flex items-center gap-2 p-2 bg-bg-secondary rounded"
+      onMouseEnter={() => setIsHovered(true)}
+      onMouseLeave={() => setIsHovered(false)}
+    >
+      <FiCheckCircle className="w-4 h-4 text-success" />
+      
+      <div className="flex-1">
+        <div className="text-sm text-text-primary">
+          {data.message}
+        </div>
+        <div className="text-xs text-text-secondary">
+          Count: {data.count}
+        </div>
+      </div>
+      
+      {isHovered && (
+        <div className="flex gap-1">
+          <Button 
+            size="xs" 
+            variant="outline"
+            onClick={handleIncrement}
+          >
+            +1
+          </Button>
+          <Button 
+            size="xs" 
+            variant="outline"
+            onClick={handleSetMessage}
+          >
+            Change
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+};

package/out/resources/skills/extension-creator/assets/templates/ConfigComponent.jsx.template

@@ -0,0 +1,38 @@
+/**
+ * Config Component for {{EXTENSION_NAME}}
+ *
+ * Renders a settings UI in the ExtensionSettingsDialog.
+ *
+ * Available props:
+ * - config: Current config data from getConfigData()
+ * - updateConfig: Callback to mutate in-memory config (does NOT persist)
+ * - ui: UI components (Button, Checkbox, Input, Select, TextArea, etc.) — prefer these over raw HTML
+ * - icons: React Icons organized by set (Fi, Hi, Cg, etc.)
+ * - models: Available models
+ * - providers: Available providers
+ * - projectDir: Project directory path
+ * - task: Current TaskData
+ * - mode: Current mode string
+ * - api: ApplicationAPI reference
+ *
+ * Note: React is globally available (use React.useState, React.useEffect, etc.)
+ * Note: Prefer ui.* components over raw HTML elements for consistent styling
+ */
+
+({ config, updateConfig, ui }) => {
+  const { Input } = ui;
+
+  return (
+    <div className="flex flex-col gap-4">
+      <Input
+        label="My Setting Label"
+        value={config?.mySetting || ''}
+        onChange={(value) => updateConfig({ ...config, mySetting: value })}
+        placeholder="Enter a value..."
+      />
+      <p className="text-xs text-text-secondary -mt-2">
+        Description of what this setting controls and how it affects the extension behavior.
+      </p>
+    </div>
+  );
+};

package/out/resources/skills/extension-creator/assets/templates/folder-extension/config.ts.template

@@ -0,0 +1,29 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export interface {EXTENSION_NAME}Config {
+  // Add config properties
+}
+
+const DEFAULT_CONFIG: {EXTENSION_NAME}Config = {
+  // Add default values
+};
+
+const CONFIG_FILE = path.join(__dirname, 'config.json');
+
+export const loadConfig = async (): Promise<{EXTENSION_NAME}Config> => {
+  try {
+    const data = await fs.readFile(CONFIG_FILE, 'utf-8');
+    const config = JSON.parse(data);
+    return { ...DEFAULT_CONFIG, ...config };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+};
+
+export const saveConfig = async (config: {EXTENSION_NAME}Config): Promise<void> => {
+  await fs.writeFile(CONFIG_FILE, JSON.stringify(config, null, 2), 'utf-8');
+};

package/out/resources/skills/extension-creator/assets/templates/folder-extension/index.ts.template

@@ -0,0 +1,42 @@
+/**
+ * {EXTENSION_NAME} Extension
+ *
+ * {DESCRIPTION}
+ */
+
+import type { Extension, ExtensionContext, AgentStartedEvent, CommandDefinition } from '@aiderdesk/extensions';
+
+import { loadConfig, saveConfig } from './config';
+import type { {EXTENSION_NAME}Config } from './config';
+
+const DEFAULT_CONFIG: {EXTENSION_NAME}Config = {
+  // Add default config values
+};
+
+export default class {CLASS_NAME} implements Extension {
+  static metadata = {
+    name: '{EXTENSION_NAME}',
+    version: '1.0.0',
+    description: '{DESCRIPTION}',
+    author: '{AUTHOR}',
+    capabilities: ['events', 'commands'],
+  };
+
+  private config: {EXTENSION_NAME}Config = DEFAULT_CONFIG;
+
+  async onLoad(context: ExtensionContext): Promise<void> {
+    context.log('{EXTENSION_NAME} Extension loaded', 'info');
+    this.config = await loadConfig();
+  }
+
+  getCommands(_context: ExtensionContext): CommandDefinition[] {
+    return [
+      // Add commands here
+    ];
+  }
+
+  async onAgentStarted(event: AgentStartedEvent, context: ExtensionContext): Promise<void | Partial<AgentStartedEvent>> {
+    // Handle event
+    return undefined;
+  }
+}

package/out/resources/skills/extension-creator/assets/templates/folder-extension/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "{extension-name}",
+  "version": "1.0.0",
+  "description": "{DESCRIPTION}",
+  "main": "index.ts",
+  "keywords": ["aiderdesk", "extension"],
+  "author": "{AUTHOR}",
+  "license": "MIT",
+  "dependencies": {
+    // Add npm dependencies here
+  }
+}

package/out/resources/skills/extension-creator/assets/templates/folder-extension/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "lib": ["ES2020"],
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "forceConsistentCasingInFileNames": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["*.ts"],
+  "exclude": ["node_modules", "dist", "__tests__"]
+}

package/out/resources/skills/extension-creator/assets/templates/folder-extension-with-config/index.ts.template

@@ -0,0 +1,80 @@
+/**
+ * {EXTENSION_NAME} Extension
+ *
+ * {DESCRIPTION}
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { Extension, ExtensionContext } from '@aiderdesk/extensions';
+
+// Load config JSX at module level (read once, reused on every getConfigComponent call)
+const configComponentJsx = readFileSync(join(__dirname, './ConfigComponent.jsx'), 'utf-8');
+
+interface {EXTENSION_NAME}Config {
+  // Add your config properties here
+  mySetting: string;
+  enabled: boolean;
+}
+
+const DEFAULT_CONFIG: {EXTENSION_NAME}Config = {
+  mySetting: '',
+  enabled: true,
+};
+
+export default class {CLASS_NAME} implements Extension {
+  static metadata = {
+    name: '{EXTENSION_NAME}',
+    version: '1.0.0',
+    description: '{DESCRIPTION}',
+    author: '{AUTHOR}',
+    capabilities: ['context'],
+    // iconUrl: 'https://...',
+  };
+
+  private configPath: string;
+
+  constructor() {
+    this.configPath = join(__dirname, 'config.json');
+  }
+
+  async onLoad(context: ExtensionContext): Promise<void> {
+    context.log('{EXTENSION_NAME} Extension loaded', 'info');
+  }
+
+  // --- Config Component API ---
+
+  getConfigComponent(_context: ExtensionContext): string {
+    return configComponentJsx;
+  }
+
+  async getConfigData(_context: ExtensionContext): Promise<{EXTENSION_NAME}Config> {
+    try {
+      if (existsSync(this.configPath)) {
+        const data = readFileSync(this.configPath, 'utf-8');
+        const parsed = JSON.parse(data);
+        return { ...DEFAULT_CONFIG, ...parsed };
+      }
+    } catch {
+      // Ignore errors, fall back to defaults
+    }
+    return { ...DEFAULT_CONFIG };
+  }
+
+  async saveConfigData(configData: unknown, _context: ExtensionContext): Promise<unknown> {
+    const merged: {EXTENSION_NAME}Config = {
+      ...DEFAULT_CONFIG,
+      ...configData as Partial<{EXTENSION_NAME}Config>,
+    };
+    writeFileSync(this.configPath, JSON.stringify(merged, null, 2), 'utf-8');
+    return merged;
+  }
+
+  // --- Event Handlers / Other Methods ---
+
+  // async onRuleFilesRetrieved(event: RuleFilesRetrievedEvent, context: ExtensionContext) {
+  //   const config = await this.getConfigData(context);
+  //   Use config values in your logic...
+  // }
+}

package/out/resources/skills/extension-creator/assets/templates/single-file.ts.template

@@ -0,0 +1,30 @@
+/**
+ * {EXTENSION_NAME} Extension
+ *
+ * {DESCRIPTION}
+ */
+
+import type { Extension, ExtensionContext } from '@aiderdesk/extensions';
+
+export default class {CLASS_NAME} implements Extension {
+  static metadata = {
+    name: '{EXTENSION_NAME}',
+    version: '1.0.0',
+    description: '{DESCRIPTION}',
+    author: '{AUTHOR}',
+    capabilities: ['{CAPABILITY}'],
+  };
+
+  async onLoad(context: ExtensionContext): Promise<void> {
+    context.log('{EXTENSION_NAME} Extension loaded', 'info');
+  }
+
+  // Add methods as needed:
+  // - getCommands()
+  // - getTools()
+  // - getAgents()
+  // - getModes()
+  // - onAgentStarted()
+  // - onToolCalled()
+  // etc.
+}