DevScribe Plugin Development & AI Context Specification

AI Prompt Directive: Use this document as the authoritative context specification when instructing AI coding assistants (e.g. Gemini, Claude, Cursor, ChatGPT) to build, refactor, or generate custom plugins for the DevScribe developer workspace.

1. AI System Prompt / Directive

Copy and paste the following prompt block when starting a new plugin project with an AI assistant:

You are an expert full-stack developer building a plugin for DevScribe (an Electron-based developer application).
DevScribe plugins run inside an Electron Webview and communicate with the main application strictly through `window.pluginAPI`.

Core Architectural Rules:
1. All interactions with DevScribe (storage, file operations, code execution, database queries, terminal, notifications, API client) MUST use `window.pluginAPI`.
2. Do NOT use Node.js `require` or Electron direct modules in the webview bundle; use `window.pluginAPI`.
3. Listen for theme updates via `window.addEventListener("theme-changed", ...)` or read `window.pluginAPI.context.theme`.
4. Persist document state using `window.pluginAPI.updateDocument(window.pluginAPI.context.fileId, data)` or `window.pluginAPI.saveData(data)`.
5. Strictly adhere to the method signatures in the DevScribe Plugin API reference below.

2. Quickstart: Commands to Initialize a Plugin Repository

Run these commands to set up a new DevScribe plugin repository using Vite + React (recommended) or Vanilla JavaScript:

Option A: React + Vite (Recommended)

# 1. Create a new React plugin repository
npx -y create-vite@latest devscribe-plugin-mytool --template react
cd devscribe-plugin-mytool

# 2. Install dependencies
npm install

# 3. Add Remix Icons for visual consistency with DevScribe
npm install remixicon

# 4. Start local development server
npm run dev

Option B: Vanilla JavaScript

mkdir devscribe-plugin-mytool && cd devscribe-plugin-mytool
npm init -y

3. Plugin Manifest Specification (manifest.json)

Every plugin repository MUST include a manifest.json at its root directory:

{
  "id": "my-custom-plugin",
  "name": "My Custom Plugin",
  "version": "1.0.0",
  "description": "A custom developer tool plugin for the DevScribe workspace.",
  "author": "Developer Name",
  "entry": "index.html",
  "icon": "ri-code-s-slash-line",
  "fileTypes": ["code-editor", "custom-tool"],
  "permissions": [
    "file-system",
    "code-execution",
    "terminal",
    "database"
  ]
}

4. Complete Reference of Allowed window.pluginAPI Methods

A. Context & Theme Properties

Theme Listener Pattern:

window.addEventListener("theme-changed", (event) => {
  const currentTheme = event.detail.theme; // "light" | "dark"
  console.log("DevScribe Theme updated:", currentTheme);
});

B. Document & File Management

C. Native Code Execution Engine

D. Data-Bridge (Database Operations)

E. Integrated PTY Terminal (window.pluginAPI.terminal)

F. Native API Client & Environments (window.pluginAPI.api)

G. Messaging & System Utilities

5. Standard Component Architecture Example (React)

Below is a production boilerplate for a DevScribe plugin component demonstrating theme synchronization, auto-saving, and code execution:

import React, { useState, useEffect } from 'react';

export default function App() {
  const [code, setCode] = useState('');
  const [output, setOutput] = useState('');
  const [theme, setTheme] = useState(window.pluginAPI?.context?.theme || 'light');
  const [loading, setLoading] = useState(false);

  const fileId = window.pluginAPI?.context?.fileId;

  // 1. Initialize Document Content & Theme Listener
  useEffect(() => {
    async function loadContent() {
      if (!fileId || !window.pluginAPI) return;
      try {
        const docs = await window.pluginAPI.getDocumentsByParentFile(fileId);
        if (docs && docs.length > 0 && docs[0].content) {
          const docData = docs[0].content;
          const initialCode = Array.isArray(docData) ? docData[0]?.data?.code : docData.code;
          if (initialCode) setCode(initialCode);
        }
      } catch (err) {
        console.error("Failed to load initial document data:", err);
      }
    }

    loadContent();

    const handleThemeChange = (e) => setTheme(e.detail.theme);
    window.addEventListener('theme-changed', handleThemeChange);
    return () => window.removeEventListener('theme-changed', handleThemeChange);
  }, [fileId]);

  // 2. Persist Document Content to DevScribe
  const handleCodeChange = async (newCode) => {
    setCode(newCode);
    if (!fileId || !window.pluginAPI) return;

    try {
      await window.pluginAPI.updateDocument(fileId, [
        {
          type: "code-editor",
          data: { code: newCode, updatedAt: Date.now() }
        }
      ]);
    } catch (err) {
      console.error("Auto-save failed:", err);
    }
  };

  // 3. Run Code Action
  const handleExecute = async () => {
    setLoading(true);
    try {
      const result = await window.pluginAPI.runJsCode(code);
      setOutput(typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result));
      window.pluginAPI.notify("Code executed successfully!", "success");
    } catch (err) {
      setOutput("Error: " + err.message);
      window.pluginAPI.notify("Execution failed", "error");
    } finally {
      setLoading(false);
    }
  };

  return (
    <div style={{
      padding: '16px',
      backgroundColor: theme === 'dark' ? '#1E1E1E' : '#FFFFFF',
      color: theme === 'dark' ? '#F3F4F6' : '#111827',
      minHeight: '100vh',
      fontFamily: 'Inter, sans-serif'
    }}>
      <header style={{ display: 'flex', justifyContent: 'space-between', marginBottom: '12px' }}>
        <h3>DevScribe Plugin Tool</h3>
        <button
          onClick={handleExecute}
          disabled={loading}
          style={{
            padding: '6px 14px',
            backgroundColor: '#2563EB',
            color: '#FFFFFF',
            border: 'none',
            borderRadius: '4px',
            cursor: 'pointer'
          }}
        >
          {loading ? 'Executing...' : 'Run Code'}
        </button>
      </header>

      <textarea
        value={code}
        onChange={(e) => handleCodeChange(e.target.value)}
        placeholder="// Write your code or document content here..."
        style={{
          width: '100%',
          height: '240px',
          fontFamily: 'monospace',
          fontSize: '13px',
          padding: '10px',
          borderRadius: '6px',
          border: '1px solid #D1D5DB',
          backgroundColor: theme === 'dark' ? '#2D2D2D' : '#FAFAFA',
          color: theme === 'dark' ? '#F9FAFB' : '#111827'
        }}
      />

      {output && (
        <div style={{ marginTop: '16px' }}>
          <h4>Console Output:</h4>
          <pre style={{
            padding: '12px',
            borderRadius: '6px',
            backgroundColor: theme === 'dark' ? '#111827' : '#F3F4F6',
            overflowX: 'auto'
          }}>
            {output}
          </pre>
        </div>
      )}
    </div>
  );
}