markdown-notes-engine 1.0.0

package/lib/backend/github.js

@@ -0,0 +1,318 @@
+/**
+ * GitHub Client Wrapper
+ * Handles all GitHub API operations for note management
+ */
+
+const { Octokit } = require('@octokit/rest');
+
+class GitHubClient {
+  constructor({ token, owner, repo, branch = 'main' }) {
+    this.octokit = new Octokit({ auth: token });
+    this.owner = owner;
+    this.repo = repo;
+    this.branch = branch;
+  }
+
+  /**
+   * Get the default branch for the repository
+   * @returns {Promise<string>} Default branch name
+   */
+  async getDefaultBranch() {
+    try {
+      const response = await this.octokit.repos.get({
+        owner: this.owner,
+        repo: this.repo
+      });
+      return response.data.default_branch;
+    } catch (error) {
+      console.error('Failed to get default branch:', error.message);
+      return 'main'; // fallback
+    }
+  }
+
+  /**
+   * Get repository file tree structure
+   * @returns {Promise<Array>} Array of files and folders
+   */
+  async getFileStructure() {
+    try {
+      // Get the entire tree recursively using git API
+      const { data } = await this.octokit.git.getTree({
+        owner: this.owner,
+        repo: this.repo,
+        tree_sha: this.branch,
+        recursive: '1'
+      });
+
+      // Filter to only blob files (not trees)
+      const files = data.tree.filter(item => item.type === 'blob');
+
+      return this._buildStructureFromFiles(files);
+    } catch (error) {
+      if (error.status === 404) {
+        // Branch doesn't exist, try to get default branch
+        try {
+          const defaultBranch = await this.getDefaultBranch();
+          this.branch = defaultBranch; // Update for future calls
+
+          const { data } = await this.octokit.git.getTree({
+            owner: this.owner,
+            repo: this.repo,
+            tree_sha: defaultBranch,
+            recursive: '1'
+          });
+
+          const files = data.tree.filter(item => item.type === 'blob');
+          return this._buildStructureFromFiles(files);
+        } catch (retryError) {
+          // Repository might be empty
+          console.error('Repository appears to be empty or inaccessible:', retryError.message);
+          return []; // Return empty array for empty repos
+        }
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Get file content
+   * @param {string} path - File path
+   * @returns {Promise<Object>} File content and metadata
+   */
+  async getFile(path) {
+    try {
+      const response = await this.octokit.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path: path,
+        ref: this.branch
+      });
+
+      // Check if this is a file (not a directory)
+      if (!response.data.content) {
+        console.error('No content in response - might be a directory');
+        return null;
+      }
+
+      return {
+        content: Buffer.from(response.data.content, 'base64').toString('utf-8'),
+        sha: response.data.sha,
+        path: response.data.path
+      };
+    } catch (error) {
+      if (error.status === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Create or update a file
+   * @param {string} path - File path
+   * @param {string} content - File content
+   * @param {string} [sha] - File SHA (required for updates)
+   * @returns {Promise<Object>} Response from GitHub
+   */
+  async saveFile(path, content, sha = null) {
+    const params = {
+      owner: this.owner,
+      repo: this.repo,
+      path: path,
+      message: sha ? `Update ${path}` : `Create ${path}`,
+      content: Buffer.from(content).toString('base64'),
+      branch: this.branch
+    };
+
+    if (sha) {
+      params.sha = sha;
+    }
+
+    const response = await this.octokit.repos.createOrUpdateFileContents(params);
+    return response.data;
+  }
+
+  /**
+   * Delete a file
+   * @param {string} path - File path
+   * @param {string} sha - File SHA
+   * @returns {Promise<Object>} Response from GitHub
+   */
+  async deleteFile(path, sha) {
+    const response = await this.octokit.repos.deleteFile({
+      owner: this.owner,
+      repo: this.repo,
+      path: path,
+      message: `Delete ${path}`,
+      sha: sha,
+      branch: this.branch
+    });
+
+    return response.data;
+  }
+
+  /**
+   * Create a folder (by creating a .gitkeep file)
+   * @param {string} path - Folder path
+   * @returns {Promise<Object>} Response from GitHub
+   */
+  async createFolder(path) {
+    const gitkeepPath = `${path}/.gitkeep`;
+    return this.saveFile(gitkeepPath, '', null);
+  }
+
+  /**
+   * Delete a folder (recursively delete all files)
+   * @param {string} path - Folder path
+   * @returns {Promise<Array>} Array of delete responses
+   */
+  async deleteFolder(path) {
+    const files = await this._getFilesInFolder(path);
+    const deletePromises = files.map(file =>
+      this.deleteFile(file.path, file.sha)
+    );
+
+    return Promise.all(deletePromises);
+  }
+
+  /**
+   * Search notes for a query
+   * @param {string} query - Search query
+   * @returns {Promise<Array>} Search results
+   */
+  async searchNotes(query) {
+    const searchQuery = `${query} repo:${this.owner}/${this.repo}`;
+    const response = await this.octokit.search.code({
+      q: searchQuery
+    });
+
+    const results = [];
+
+    for (const item of response.data.items) {
+      if (!item.path.endsWith('.md')) continue;
+
+      const file = await this.getFile(item.path);
+      if (!file) continue;
+
+      const lines = file.content.split('\n');
+      const matches = [];
+
+      lines.forEach((line, index) => {
+        if (line.toLowerCase().includes(query.toLowerCase())) {
+          matches.push({
+            line: index + 1,
+            content: line
+          });
+        }
+      });
+
+      if (matches.length > 0) {
+        results.push({
+          path: item.path,
+          matches: matches
+        });
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Get all files in a folder
+   * @private
+   */
+  async _getFilesInFolder(path) {
+    const response = await this.octokit.repos.getContent({
+      owner: this.owner,
+      repo: this.repo,
+      path: path,
+      ref: this.branch
+    });
+
+    let files = [];
+
+    for (const item of response.data) {
+      if (item.type === 'file') {
+        files.push(item);
+      } else if (item.type === 'dir') {
+        const subFiles = await this._getFilesInFolder(item.path);
+        files = files.concat(subFiles);
+      }
+    }
+
+    return files;
+  }
+
+  /**
+   * Build hierarchical structure from flat file list
+   * @private
+   */
+  _buildStructureFromFiles(files) {
+    const root = [];
+    const folderMap = new Map();
+
+    // Sort files to ensure consistent ordering
+    files.sort((a, b) => a.path.localeCompare(b.path));
+
+    for (const file of files) {
+      const parts = file.path.split('/');
+      let currentLevel = root;
+      let currentPath = '';
+
+      // Process each part of the path
+      for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        currentPath = currentPath ? `${currentPath}/${part}` : part;
+
+        if (i === parts.length - 1) {
+          // It's a file - skip .gitkeep files
+          if (part === '.gitkeep') {
+            continue;
+          }
+
+          currentLevel.push({
+            name: part,
+            type: 'file',
+            path: file.path,
+            sha: file.sha
+          });
+        } else {
+          // It's a folder
+          let folder = folderMap.get(currentPath);
+
+          if (!folder) {
+            folder = {
+              name: part,
+              type: 'folder',
+              path: currentPath,
+              children: []
+            };
+            folderMap.set(currentPath, folder);
+            currentLevel.push(folder);
+          }
+
+          currentLevel = folder.children;
+        }
+      }
+    }
+
+    // Sort function: folders first, then alphabetically
+    const sortStructure = (items) => {
+      items.sort((a, b) => {
+        if (a.type === b.type) return a.name.localeCompare(b.name);
+        return a.type === 'folder' ? -1 : 1;
+      });
+
+      items.forEach((item) => {
+        if (item.type === 'folder' && item.children) {
+          sortStructure(item.children);
+        }
+      });
+    };
+
+    sortStructure(root);
+    return root;
+  }
+}
+
+module.exports = { GitHubClient };

package/lib/backend/index.js

@@ -0,0 +1,76 @@
+/**
+ * Markdown Notes Engine - Backend Router
+ *
+ * Creates an Express router with all note-taking API endpoints
+ */
+
+const express = require('express');
+const { GitHubClient } = require('./github');
+const { StorageClient } = require('./storage');
+const { MarkdownRenderer } = require('./markdown');
+const notesRoutes = require('./routes/notes');
+const uploadRoutes = require('./routes/upload');
+const searchRoutes = require('./routes/search');
+
+/**
+ * Creates a configured notes router
+ * @param {Object} config - Configuration object
+ * @param {Object} config.github - GitHub configuration
+ * @param {string} config.github.token - GitHub personal access token
+ * @param {string} config.github.owner - Repository owner
+ * @param {string} config.github.repo - Repository name
+ * @param {string} [config.github.branch='main'] - Repository branch (defaults to 'main')
+ * @param {Object} config.storage - Storage configuration (R2 or S3)
+ * @param {string} config.storage.type - 'r2' or 's3'
+ * @param {string} config.storage.accountId - Account ID (R2) or region (S3)
+ * @param {string} config.storage.accessKeyId - Access key ID
+ * @param {string} config.storage.secretAccessKey - Secret access key
+ * @param {string} config.storage.bucketName - Bucket name
+ * @param {string} config.storage.publicUrl - Public URL for accessing files
+ * @param {Object} [config.options] - Optional configuration
+ * @param {boolean} [config.options.autoUpdateReadme=true] - Auto-update README on note save
+ * @returns {express.Router} Configured Express router
+ */
+function createNotesRouter(config) {
+  if (!config.github || !config.github.token || !config.github.owner || !config.github.repo) {
+    throw new Error('GitHub configuration is required: token, owner, and repo');
+  }
+
+  if (!config.storage) {
+    throw new Error('Storage configuration is required');
+  }
+
+  const router = express.Router();
+
+  // Initialize clients
+  const githubClient = new GitHubClient({
+    token: config.github.token,
+    owner: config.github.owner,
+    repo: config.github.repo,
+    branch: config.github.branch || 'main'
+  });
+
+  const storageClient = new StorageClient(config.storage);
+  const markdownRenderer = new MarkdownRenderer();
+  const options = config.options || {};
+
+  // Middleware to attach clients to request
+  router.use((req, res, next) => {
+    req.notesEngine = {
+      githubClient,
+      storageClient,
+      markdownRenderer,
+      options
+    };
+    next();
+  });
+
+  // Mount route handlers
+  router.use(notesRoutes);
+  router.use(uploadRoutes);
+  router.use(searchRoutes);
+
+  return router;
+}
+
+module.exports = { createNotesRouter };

package/lib/backend/markdown.js

@@ -0,0 +1,62 @@
+/**
+ * Markdown Renderer
+ * Renders markdown to HTML with syntax highlighting
+ */
+
+const { marked } = require('marked');
+const { markedHighlight } = require('marked-highlight');
+const hljs = require('highlight.js');
+
+class MarkdownRenderer {
+  constructor() {
+    // Configure marked with syntax highlighting
+    marked.use(markedHighlight({
+      langPrefix: 'hljs language-',
+      highlight(code, lang) {
+        const language = hljs.getLanguage(lang) ? lang : 'plaintext';
+        return hljs.highlight(code, { language }).value;
+      }
+    }));
+
+    // Custom renderer for links and videos
+    const renderer = new marked.Renderer();
+
+    // Custom link renderer - handles internal markdown links
+    renderer.link = (href, title, text) => {
+      if (href.endsWith('.md')) {
+        return `<a href="#" class="internal-link" data-path="${href}">${text}</a>`;
+      }
+      return `<a href="${href}" ${title ? `title="${title}"` : ''}>${text}</a>`;
+    };
+
+    // Custom image renderer - detects videos and renders video tag
+    renderer.image = (href, title, text) => {
+      // Check if it's a video
+      const videoExtensions = ['.mp4', '.webm', '.mov', '.avi', '.mkv'];
+      const isVideo = videoExtensions.some(ext => href.toLowerCase().endsWith(ext)) ||
+                      href.includes('/videos/');
+
+      if (isVideo) {
+        return `<video controls style="max-width: 100%;" ${title ? `title="${title}"` : ''}>
+          <source src="${href}" type="video/mp4">
+          Your browser does not support the video tag.
+        </video>`;
+      }
+
+      return `<img src="${href}" alt="${text}" ${title ? `title="${title}"` : ''} style="max-width: 100%;">`;
+    };
+
+    marked.use({ renderer });
+  }
+
+  /**
+   * Render markdown to HTML
+   * @param {string} markdown - Markdown content
+   * @returns {string} HTML content
+   */
+  render(markdown) {
+    return marked(markdown);
+  }
+}
+
+module.exports = { MarkdownRenderer };

package/lib/backend/routes/notes.js

@@ -0,0 +1,197 @@
+/**
+ * Notes Routes
+ * Handles note CRUD operations
+ */
+
+const express = require('express');
+const router = express.Router();
+
+// Get file structure
+router.get('/structure', async (req, res) => {
+  try {
+    const { githubClient } = req.notesEngine;
+    const structure = await githubClient.getFileStructure();
+    res.json({ structure });
+  } catch (error) {
+    console.error('Error fetching structure:', error);
+    res.status(500).json({ error: 'Failed to fetch file structure' });
+  }
+});
+
+// Get note content
+router.get('/note', async (req, res) => {
+  try {
+    const { path } = req.query;
+    if (!path) {
+      return res.status(400).json({ error: 'Path is required' });
+    }
+
+    const { githubClient } = req.notesEngine;
+    const file = await githubClient.getFile(path);
+
+    if (!file) {
+      return res.status(404).json({ error: 'Note not found' });
+    }
+
+    res.json(file);
+  } catch (error) {
+    console.error('Error fetching note:', error);
+    res.status(500).json({ error: 'Failed to fetch note' });
+  }
+});
+
+// Save note
+router.post('/note', async (req, res) => {
+  try {
+    let { path, content } = req.body;
+
+    if (!path || content === undefined) {
+      return res.status(400).json({ error: 'Path and content are required' });
+    }
+
+    // Ensure .md extension
+    if (!path.endsWith('.md')) {
+      path += '.md';
+    }
+
+    const { githubClient, options } = req.notesEngine;
+
+    // Get existing file SHA if it exists
+    const existingFile = await githubClient.getFile(path);
+    const sha = existingFile ? existingFile.sha : null;
+
+    // Save the file
+    await githubClient.saveFile(path, content, sha);
+
+    // Auto-update README if enabled
+    if (options.autoUpdateReadme !== false && path !== 'README.md') {
+      try {
+        await updateReadme(githubClient);
+      } catch (error) {
+        console.error('Error updating README:', error);
+        // Don't fail the request if README update fails
+      }
+    }
+
+    res.json({ success: true, path });
+  } catch (error) {
+    console.error('Error saving note:', error);
+    res.status(500).json({ error: 'Failed to save note' });
+  }
+});
+
+// Delete note
+router.delete('/note', async (req, res) => {
+  try {
+    const { path } = req.body;
+
+    if (!path) {
+      return res.status(400).json({ error: 'Path is required' });
+    }
+
+    const { githubClient } = req.notesEngine;
+
+    // Get file SHA
+    const file = await githubClient.getFile(path);
+    if (!file) {
+      return res.status(404).json({ error: 'Note not found' });
+    }
+
+    await githubClient.deleteFile(path, file.sha);
+
+    res.json({ success: true });
+  } catch (error) {
+    console.error('Error deleting note:', error);
+    res.status(500).json({ error: 'Failed to delete note' });
+  }
+});
+
+// Create folder
+router.post('/folder', async (req, res) => {
+  try {
+    const { path } = req.body;
+
+    if (!path) {
+      return res.status(400).json({ error: 'Path is required' });
+    }
+
+    const { githubClient } = req.notesEngine;
+    await githubClient.createFolder(path);
+
+    res.json({ success: true });
+  } catch (error) {
+    console.error('Error creating folder:', error);
+    res.status(500).json({ error: 'Failed to create folder' });
+  }
+});
+
+// Delete folder
+router.delete('/folder', async (req, res) => {
+  try {
+    const { path } = req.body;
+
+    if (!path) {
+      return res.status(400).json({ error: 'Path is required' });
+    }
+
+    const { githubClient } = req.notesEngine;
+    await githubClient.deleteFolder(path);
+
+    res.json({ success: true });
+  } catch (error) {
+    console.error('Error deleting folder:', error);
+    res.status(500).json({ error: 'Failed to delete folder' });
+  }
+});
+
+// Render markdown to HTML
+router.post('/render', async (req, res) => {
+  try {
+    const { markdown } = req.body;
+
+    if (markdown === undefined) {
+      return res.status(400).json({ error: 'Markdown content is required' });
+    }
+
+    const { markdownRenderer } = req.notesEngine;
+    const html = markdownRenderer.render(markdown);
+
+    res.json({ html });
+  } catch (error) {
+    console.error('Error rendering markdown:', error);
+    res.status(500).json({ error: 'Failed to render markdown' });
+  }
+});
+
+/**
+ * Auto-update README with list of notes
+ * @private
+ */
+async function updateReadme(githubClient) {
+  const structure = await githubClient.getFileStructure();
+
+  let readmeContent = '# Notes\n\n';
+  readmeContent += 'This is an auto-generated index of all notes.\n\n';
+
+  const mdFiles = structure
+    .filter(item => item.type === 'file' && item.name.endsWith('.md') && item.name !== 'README.md')
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  if (mdFiles.length === 0) {
+    readmeContent += '*No notes yet.*\n';
+  } else {
+    mdFiles.forEach(file => {
+      const displayName = file.name.replace('.md', '');
+      readmeContent += `- [${displayName}](${file.path})\n`;
+    });
+  }
+
+  readmeContent += `\n---\n*Last updated: ${new Date().toISOString()}*\n`;
+
+  const existingReadme = await githubClient.getFile('README.md');
+  const sha = existingReadme ? existingReadme.sha : null;
+
+  await githubClient.saveFile('README.md', readmeContent, sha);
+}
+
+module.exports = router;

package/lib/backend/routes/search.js

@@ -0,0 +1,28 @@
+/**
+ * Search Routes
+ * Handles note searching
+ */
+
+const express = require('express');
+const router = express.Router();
+
+// Search notes
+router.get('/search', async (req, res) => {
+  try {
+    const { q: query } = req.query;
+
+    if (!query) {
+      return res.status(400).json({ error: 'Query parameter "q" is required' });
+    }
+
+    const { githubClient } = req.notesEngine;
+    const results = await githubClient.searchNotes(query);
+
+    res.json({ results });
+  } catch (error) {
+    console.error('Error searching notes:', error);
+    res.status(500).json({ error: 'Failed to search notes' });
+  }
+});
+
+module.exports = router;