mrmd-project 0.1.0

package/src/links.js

@@ -0,0 +1,198 @@
+/**
+ * Links module - Internal link parsing and resolution
+ *
+ * Handles [[wiki-style links]] used in mrmd documents.
+ *
+ * @module Links
+ */
+
+/**
+ * Parse all internal links from content
+ *
+ * @param {string} content - Document content
+ * @returns {object[]} Array of parsed links
+ *
+ * @example
+ * Links.parse('See [[installation]] and [[config#advanced|advanced config]].')
+ * // Returns [
+ * //   { raw: '[[installation]]', target: 'installation', anchor: null, display: null, start: 4, end: 20 },
+ * //   { raw: '[[config#advanced|advanced config]]', target: 'config', anchor: 'advanced', display: 'advanced config', start: 25, end: 61 }
+ * // ]
+ */
+export function parse(content) {
+  if (!content) return [];
+
+  const links = [];
+  // Match [[target]], [[target#anchor]], [[target|display]], [[target#anchor|display]]
+  const regex = /\[\[([^\]|#]+)(?:#([^\]|]+))?(?:\|([^\]]+))?\]\]/g;
+  let match;
+
+  while ((match = regex.exec(content)) !== null) {
+    links.push({
+      raw: match[0],
+      target: match[1].trim(),
+      anchor: match[2] ? match[2].trim() : null,
+      display: match[3] ? match[3].trim() : null,
+      start: match.index,
+      end: match.index + match[0].length,
+    });
+  }
+
+  return links;
+}
+
+/**
+ * Resolve a link target to an actual file path
+ *
+ * Resolution rules:
+ * 1. Exact match (with or without .md)
+ * 2. Fuzzy match on filename
+ * 3. Special links: next, prev, home, up
+ *
+ * @param {string} target - Link target
+ * @param {string} fromDocument - Document containing the link
+ * @param {string[]} projectFiles - All files in project
+ * @returns {string | null} Resolved path or null
+ */
+export function resolve(target, fromDocument, projectFiles) {
+  if (!target || !projectFiles || projectFiles.length === 0) return null;
+
+  const sortedFiles = [...projectFiles].sort();
+
+  // Handle special links
+  const specialLinks = ['next', 'prev', 'home', 'up'];
+  if (specialLinks.includes(target.toLowerCase())) {
+    return resolveSpecialLink(target.toLowerCase(), fromDocument, sortedFiles);
+  }
+
+  // Normalize target (remove .md if present, lowercase for matching)
+  const targetNorm = target.replace(/\.md$/, '').toLowerCase();
+
+  // 1. Try exact path match
+  for (const file of projectFiles) {
+    const fileNorm = file.replace(/\.md$/, '').toLowerCase();
+    if (fileNorm === targetNorm || fileNorm === targetNorm + '/index') {
+      return file;
+    }
+  }
+
+  // 2. Try matching just the filename part of target against filenames
+  const targetFilename = targetNorm.split('/').pop();
+  for (const file of projectFiles) {
+    const filename = file.replace(/\.md$/, '').split('/').pop().toLowerCase();
+    // Remove numeric prefix for matching
+    const filenameNoPrefix = filename.replace(/^\d+-/, '');
+    if (filenameNoPrefix === targetFilename || filename === targetFilename) {
+      return file;
+    }
+  }
+
+  // 3. Try fuzzy matching - look for files containing the target name
+  for (const file of projectFiles) {
+    const fileLower = file.toLowerCase();
+    if (fileLower.includes(targetNorm)) {
+      return file;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Resolve special links (next, prev, home, up)
+ * @private
+ */
+function resolveSpecialLink(target, fromDocument, sortedFiles) {
+  // Filter to only .md files (content files)
+  const mdFiles = sortedFiles.filter(f => f.endsWith('.md') && f !== 'mrmd.md');
+
+  // Sort by FSML order
+  const sorted = mdFiles.sort((a, b) => {
+    const aMatch = a.match(/^(\d+)-/);
+    const bMatch = b.match(/^(\d+)-/);
+    const aOrder = aMatch ? parseInt(aMatch[1]) : Infinity;
+    const bOrder = bMatch ? parseInt(bMatch[1]) : Infinity;
+    if (aOrder !== bOrder) return aOrder - bOrder;
+    return a.localeCompare(b);
+  });
+
+  const currentIndex = sorted.indexOf(fromDocument);
+
+  switch (target) {
+    case 'next':
+      return currentIndex >= 0 && currentIndex < sorted.length - 1
+        ? sorted[currentIndex + 1]
+        : null;
+
+    case 'prev':
+      return currentIndex > 0
+        ? sorted[currentIndex - 1]
+        : null;
+
+    case 'home':
+      return sorted[0] || null;
+
+    case 'up': {
+      // Go to parent directory's index or first file
+      const parts = fromDocument.split('/');
+      if (parts.length > 1) {
+        const parentDir = parts.slice(0, -1).join('/');
+        // Look for index.md in parent
+        const parentIndex = sorted.find(f => f === parentDir + '/index.md');
+        if (parentIndex) return parentIndex;
+        // Or first file in parent
+        const parentFile = sorted.find(f => f.startsWith(parentDir + '/'));
+        if (parentFile) return parentFile;
+      }
+      return sorted[0] || null;
+    }
+
+    default:
+      return null;
+  }
+}
+
+/**
+ * Update links in content when files are moved/renamed
+ *
+ * @param {string} content - Document content
+ * @param {object[]} moves - Array of { from, to } moves
+ * @param {string} currentDocPath - Path of document being refactored
+ * @returns {string} Content with updated links
+ */
+export function refactor(content, moves, currentDocPath) {
+  if (!content || !moves || moves.length === 0) return content;
+
+  // Build a map of old names to new names
+  const renameMap = new Map();
+  for (const move of moves) {
+    // Extract just the filename without path and extension
+    const oldName = move.from.replace(/\.md$/, '').split('/').pop().replace(/^\d+-/, '');
+    const newName = move.to.replace(/\.md$/, '').split('/').pop().replace(/^\d+-/, '');
+    renameMap.set(oldName.toLowerCase(), newName);
+  }
+
+  // Find and replace links
+  let result = content;
+  const links = parse(content);
+
+  // Process links in reverse order to preserve positions
+  for (let i = links.length - 1; i >= 0; i--) {
+    const link = links[i];
+    const targetName = link.target.split('/').pop().replace(/^\d+-/, '').toLowerCase();
+
+    if (renameMap.has(targetName)) {
+      const newName = renameMap.get(targetName);
+
+      // Build new link
+      let newLink = `[[${newName}`;
+      if (link.anchor) newLink += `#${link.anchor}`;
+      if (link.display) newLink += `|${link.display}`;
+      newLink += ']]';
+
+      result = result.slice(0, link.start) + newLink + result.slice(link.end);
+    }
+  }
+
+  return result;
+}

package/src/project.js

@@ -0,0 +1,293 @@
+/**
+ * Project module - Configuration parsing and session resolution
+ *
+ * @module Project
+ */
+
+import YAML from 'yaml';
+
+/**
+ * Default project configuration values
+ */
+const DEFAULTS = {
+  session: {
+    python: {
+      venv: '.venv',
+      cwd: '.',
+      name: 'default',
+      auto_start: true,
+    },
+  },
+  assets: {
+    directory: '_assets',
+  },
+};
+
+/**
+ * Find the project root by walking up from startPath looking for mrmd.md
+ *
+ * @param {string} startPath - Path to start searching from
+ * @param {(path: string) => boolean} hasFile - Function to check if mrmd.md exists at path
+ * @returns {string | null} Project root path or null if not found
+ *
+ * @example
+ * const root = Project.findRoot('/home/user/thesis/chapter/doc.md', (p) => fs.existsSync(p + '/mrmd.md'));
+ * // Returns '/home/user/thesis' if mrmd.md exists there
+ */
+export function findRoot(startPath, hasFile) {
+  if (!startPath) return null;
+
+  // Normalize path (remove trailing slash)
+  let current = startPath.replace(/\/+$/, '');
+
+  // If startPath is a file, start from its directory
+  // We detect this heuristically - if it has an extension, treat as file
+  if (/\.[^/]+$/.test(current)) {
+    const lastSlash = current.lastIndexOf('/');
+    if (lastSlash > 0) {
+      current = current.slice(0, lastSlash);
+    }
+  }
+
+  // Walk up the directory tree
+  while (current && current !== '/') {
+    if (hasFile(current)) {
+      return current;
+    }
+
+    // Go up one level
+    const lastSlash = current.lastIndexOf('/');
+    if (lastSlash <= 0) break;
+    current = current.slice(0, lastSlash);
+  }
+
+  // Check root as well
+  if (current === '/' && hasFile('/')) {
+    return '/';
+  }
+
+  return null;
+}
+
+/**
+ * Parse yaml config blocks from mrmd.md content
+ *
+ * Extracts all ```yaml config blocks and deep merges them in document order.
+ *
+ * @param {string} content - Content of mrmd.md file
+ * @returns {object} Merged configuration object
+ *
+ * @example
+ * const config = Project.parseConfig(`
+ * # My Project
+ * \`\`\`yaml config
+ * name: "My Thesis"
+ * session:
+ *   python:
+ *     venv: ".venv"
+ * \`\`\`
+ * `);
+ * // Returns { name: 'My Thesis', session: { python: { venv: '.venv' } } }
+ */
+export function parseConfig(content) {
+  if (!content) return {};
+
+  // Match ```yaml config blocks (with optional whitespace)
+  const regex = /```yaml\s+config\s*\n([\s\S]*?)```/g;
+  let match;
+  let config = {};
+
+  while ((match = regex.exec(content)) !== null) {
+    const yamlContent = match[1];
+    try {
+      const parsed = YAML.parse(yamlContent);
+      if (parsed && typeof parsed === 'object') {
+        config = deepMerge(config, parsed);
+      }
+    } catch (e) {
+      // Invalid YAML, skip this block
+      console.warn('Failed to parse yaml config block:', e.message);
+    }
+  }
+
+  return config;
+}
+
+/**
+ * Parse YAML frontmatter from document content
+ *
+ * @param {string} content - Document content
+ * @returns {object | null} Parsed frontmatter or null if none
+ *
+ * @example
+ * const fm = Project.parseFrontmatter(`---
+ * title: "Chapter 1"
+ * session:
+ *   python:
+ *     name: "gpu"
+ * ---
+ * # Content
+ * `);
+ * // Returns { title: 'Chapter 1', session: { python: { name: 'gpu' } } }
+ */
+export function parseFrontmatter(content) {
+  if (!content) return null;
+
+  // Frontmatter must start at the very beginning of the file
+  if (!content.startsWith('---')) return null;
+
+  // Find the closing ---
+  const endMatch = content.slice(3).indexOf('\n---');
+  if (endMatch === -1) return null;
+
+  const yamlContent = content.slice(4, endMatch + 3);
+
+  try {
+    const parsed = YAML.parse(yamlContent);
+    if (parsed && typeof parsed === 'object') {
+      return parsed;
+    }
+    return null;
+  } catch (e) {
+    // Invalid YAML
+    return null;
+  }
+}
+
+/**
+ * Deep merge project config with document frontmatter
+ *
+ * Document frontmatter values override project config.
+ *
+ * @param {object} projectConfig - Project configuration
+ * @param {object | null} frontmatter - Document frontmatter
+ * @returns {object} Merged configuration
+ */
+export function mergeConfig(projectConfig, frontmatter) {
+  if (!frontmatter) return projectConfig || {};
+  if (!projectConfig) return frontmatter;
+
+  return deepMerge(projectConfig, frontmatter);
+}
+
+/**
+ * Resolve full session configuration for a document
+ *
+ * Computes absolute paths and full session name.
+ *
+ * @param {string} documentPath - Absolute path to document
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {object} mergedConfig - Merged configuration
+ * @returns {object} Resolved session config with absolute paths
+ *
+ * @example
+ * const session = Project.resolveSession(
+ *   '/home/user/thesis/chapter/doc.md',
+ *   '/home/user/thesis',
+ *   { name: 'thesis', session: { python: { venv: '.venv', cwd: '.', name: 'default' } } }
+ * );
+ * // Returns { name: 'thesis:default', venv: '/home/user/thesis/.venv', cwd: '/home/user/thesis', autoStart: true }
+ */
+export function resolveSession(documentPath, projectRoot, mergedConfig) {
+  const pythonConfig = mergedConfig?.session?.python || {};
+  const defaults = DEFAULTS.session.python;
+
+  // Get values with defaults
+  const venvRelative = pythonConfig.venv || defaults.venv;
+  const cwdRelative = pythonConfig.cwd || defaults.cwd;
+  const sessionName = pythonConfig.name || defaults.name;
+  const autoStart = pythonConfig.auto_start !== undefined ? pythonConfig.auto_start : defaults.auto_start;
+  const projectName = mergedConfig?.name || 'unnamed';
+
+  // Resolve paths relative to project root
+  const venv = resolvePath(projectRoot, venvRelative);
+  const cwd = resolvePath(projectRoot, cwdRelative);
+
+  return {
+    name: `${projectName}:${sessionName}`,
+    venv,
+    cwd,
+    autoStart,
+  };
+}
+
+/**
+ * Resolve a potentially relative path against a base directory
+ * @private
+ */
+function resolvePath(basePath, relativePath) {
+  if (!relativePath) return basePath;
+
+  // If already absolute, return as-is
+  if (relativePath.startsWith('/')) {
+    return relativePath;
+  }
+
+  // Handle . as current directory
+  if (relativePath === '.') {
+    return basePath;
+  }
+
+  // Split paths into segments
+  const baseSegments = basePath.split('/').filter(Boolean);
+  const relativeSegments = relativePath.split('/').filter(Boolean);
+
+  // Process relative path segments
+  const resultSegments = [...baseSegments];
+
+  for (const segment of relativeSegments) {
+    if (segment === '..') {
+      resultSegments.pop();
+    } else if (segment !== '.') {
+      resultSegments.push(segment);
+    }
+  }
+
+  return '/' + resultSegments.join('/');
+}
+
+/**
+ * Get default configuration values
+ *
+ * @returns {object} Default configuration
+ */
+export function getDefaults() {
+  return JSON.parse(JSON.stringify(DEFAULTS));
+}
+
+// ============================================================================
+// Internal helpers
+// ============================================================================
+
+/**
+ * Deep merge two objects (source into target)
+ * @private
+ */
+function deepMerge(target, source) {
+  if (!source) return target;
+  if (!target) return source;
+
+  const result = { ...target };
+
+  for (const key of Object.keys(source)) {
+    const sourceVal = source[key];
+    const targetVal = target[key];
+
+    if (
+      sourceVal !== null &&
+      typeof sourceVal === 'object' &&
+      !Array.isArray(sourceVal) &&
+      targetVal !== null &&
+      typeof targetVal === 'object' &&
+      !Array.isArray(targetVal)
+    ) {
+      // Both are objects, recurse
+      result[key] = deepMerge(targetVal, sourceVal);
+    } else {
+      // Source wins (including arrays)
+      result[key] = sourceVal;
+    }
+  }
+
+  return result;
+}

package/src/scaffold.js

@@ -0,0 +1,136 @@
+/**
+ * Scaffold module - Project and document templates
+ *
+ * Generates scaffolding content for new projects and standalone files.
+ *
+ * @module Scaffold
+ */
+
+/**
+ * Generate project scaffold
+ *
+ * @param {string} name - Project name
+ * @returns {object} Scaffold with files array and venvPath
+ *
+ * @example
+ * Scaffold.project('my-research')
+ * // Returns {
+ * //   files: [
+ * //     { path: 'mrmd.md', content: '# my-research\n...' },
+ * //     { path: '01-index.md', content: '# my-research\n...' },
+ * //     { path: '_assets/.gitkeep', content: '' }
+ * //   ],
+ * //   venvPath: '.venv'
+ * // }
+ */
+export function project(name) {
+  const safeName = name.replace(/[^a-zA-Z0-9-_]/g, '-');
+
+  const mrmdMd = `# ${name}
+
+Welcome to your new mrmd project.
+
+## Configuration
+
+\`\`\`yaml config
+name: "${name}"
+\`\`\`
+
+## Session Setup
+
+We use a shared session for all documents in this project.
+
+\`\`\`yaml config
+session:
+  python:
+    venv: ".venv"
+    cwd: "."
+    name: "default"
+    auto_start: true
+\`\`\`
+
+## Getting Started
+
+- Edit this file to configure your project
+- Create new documents with \`Ctrl+P\`
+- Run code blocks with \`Ctrl+Enter\`
+
+## Environment Check
+
+\`\`\`python
+import sys
+print(f"Python: {sys.version}")
+print(f"Working directory: {__import__('os').getcwd()}")
+\`\`\`
+`;
+
+  const indexMd = `# ${name}
+
+This is your project's main document.
+
+## Quick Start
+
+\`\`\`python
+print("Hello from mrmd!")
+\`\`\`
+
+## Project Structure
+
+| Path | Purpose |
+|------|---------|
+| \`mrmd.md\` | Project configuration |
+| \`_assets/\` | Images and data files |
+| \`.venv/\` | Python environment |
+
+## Next Steps
+
+- Create new documents with \`Ctrl+P\`
+- Organize with folders: \`02-section/01-document.md\`
+- Add images to \`_assets/\` and reference with \`![](_assets/image.png)\`
+`;
+
+  return {
+    files: [
+      { path: 'mrmd.md', content: mrmdMd },
+      { path: '01-index.md', content: indexMd },
+      { path: '_assets/.gitkeep', content: '' },
+    ],
+    venvPath: '.venv',
+  };
+}
+
+/**
+ * Generate frontmatter for standalone files
+ *
+ * @param {object} config - Configuration
+ * @param {string} config.venv - Absolute path to venv
+ * @param {string} config.cwd - Absolute path to working directory
+ * @param {string} [config.title] - Optional title
+ * @returns {string} YAML frontmatter string
+ *
+ * @example
+ * Scaffold.standaloneFrontmatter({
+ *   venv: '/home/user/.venv',
+ *   cwd: '/home/user/work',
+ *   title: 'Quick Analysis'
+ * })
+ * // Returns '---\ntitle: "Quick Analysis"\nsession:\n  python:\n    venv: "/home/user/.venv"\n    cwd: "/home/user/work"\n---\n'
+ */
+export function standaloneFrontmatter(config) {
+  const { venv, cwd, title } = config;
+
+  let yaml = '---\n';
+
+  if (title) {
+    yaml += `title: "${title}"\n`;
+  }
+
+  yaml += `session:
+  python:
+    venv: "${venv}"
+    cwd: "${cwd}"
+---
+`;
+
+  return yaml;
+}