markymark 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f86eabf718d44dbbe9900aba654a581b36ad66d9271e42aef392cfcc8027db3a
+  data.tar.gz: a91f7cea3b15d2e2875fa6a39ffb7f3a3753284a543688193c1f3865692a305f
+SHA512:
+  metadata.gz: ef7ef07208828a85d061410cbfb45ef874fdcf6026876073bbf6508848f7d87aa98117b7e44fe93f3f066f9247ead30b5680f24e5731dee22cf32eed372fa3fc
+  data.tar.gz: 141fa5b4dd0f86725504a51ec9075dbcaee5bbcf0a8b13728ad26c1fb5bf15e990eb5b2e95969f0304b7f8f6c2601fdf98343a8309fad6dd8f38555073cdc5e8

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2025-12-19
+
+### Added
+- Initial release
+- GitHub-Flavored Markdown rendering with Kramdown
+- Mermaid diagram support
+- Syntax highlighting with Rouge
+- Dark/Light theme toggle with localStorage persistence
+- Accordion file organization grouped by directory
+- Directory browser with bookmarks
+- Smart directory switching without server restart
+- `markymark <filename>` to open specific files directly
+- **macOS Native Integration**:
+  - `markymark init` setup wizard
+  - Markymark.app installation to ~/Applications
+  - Double-click `.md` files in Finder
+  - Cmd-click paths in iTerm
+  - `open` command support
+  - Default file handler registration via duti
+- Pumadev integration for `.test` domain support
+- Standalone server mode on port 4545
+
+### Requirements
+- Ruby >= 2.7
+- macOS native integration requires Xcode Command Line Tools

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Forrest Chang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,255 @@
+# markymark <img src="assets/marky-mark-icon2.png" alt="Markymark icon" width="40" style="vertical-align: middle"/>
+
+<p align="center">
+  <img src="assets/marky-mark-dj.jpg" alt="Marky Mark spinning docs" width="500"/>
+</p>
+
+> *Say hi to your docs* 👋
+> **Your personal documentation DJ - one server, always spinning**
+
+## Finally, a Dedicated Markdown Viewer That Works Everywhere
+
+**Double-click a `.md` file in Finder? Opens in markymark.**
+**Cmd-click a path in iTerm? Opens in markymark.**
+**Run `open README.md` in terminal? Opens in markymark.**
+
+No more markdown files opening in Xcode, VS Code, or raw text editors. markymark gives you a beautiful, dedicated markdown viewer with navigation that integrates seamlessly with macOS - just like Preview for PDFs or QuickTime for videos.
+
+**markymark** is a lightweight local markdown documentation browser that stays running in the background. Call it once from any directory, and it's always ready. Switch directories on the fly without starting new servers. Perfect for Claude Code workflows where you're constantly documenting and exploring context engineering prompts.
+
+## Quick Start (2 Steps)
+
+```bash
+# Step 1: Install the gem
+gem install markymark
+
+# Step 2: Run the setup wizard
+markymark init
+```
+
+That's it! The wizard will:
+- Install **Markymark.app** to ~/Applications
+- Set markymark as the **default app for .md files**
+- Configure your preferred server mode
+
+Now double-click any `.md` file or cmd-click paths in iTerm - they'll open beautifully rendered in markymark.
+
+### Scripted Install
+
+For automated setups, accept all defaults:
+
+```bash
+gem install markymark && markymark init -y
+```
+
+## Features
+
+- 🍎 **Native macOS integration** - Double-click `.md` files, cmd-click in iTerm, `open` command support
+- 🔄 **Smart directory switching** - Run `markymark` from any directory to switch existing server
+- 📁 **Auto-discovery** - Recursively finds all your markdown files
+- 📂 **Accordion file organization** - Files grouped by directory with expand/collapse controls
+- 🔖 **Bookmarks** - Save frequently-used directories for quick access
+- 🌐 **Directory browser** - Navigate to any folder via the UI with quick shortcuts
+- 🎨 **GitHub-Flavored Markdown** - Tables, task lists, syntax highlighting
+- 📊 **Mermaid diagrams** - Flowcharts, sequence diagrams render beautifully
+- 🌙 **Dark/Light theme toggle** - One-click switching, persisted in localStorage
+- 🔗 **Bookmarkable URLs** - Share links to specific docs
+- 🖼️ **Image support** - Images in `assets/` folders render properly
+- 🌐 **Pumadev integration** - Optional `.test` domain support
+
+## Usage
+
+### Opening Files Directly
+
+```bash
+# Open a specific markdown file (the killer feature!)
+markymark README.md
+markymark ~/docs/ARCHITECTURE.md
+
+# Browse current directory
+markymark
+
+# Browse specific directory
+markymark ~/my-docs
+```
+
+When you open a file directly, markymark:
+1. Sets the root to the file's directory
+2. Opens the browser with that file displayed
+3. Shows all other markdown files in the sidebar
+
+### Server Management
+
+```bash
+# Check server status
+markymark --status
+
+# Stop running server
+markymark --stop
+
+# Custom port
+markymark --port 8080
+
+# Don't open browser automatically
+markymark --no-browser
+```
+
+### Setup Commands
+
+```bash
+# Interactive setup wizard
+markymark init
+
+# Individual setup commands
+markymark --install-app     # Install Markymark.app
+markymark --uninstall-app   # Remove Markymark.app
+markymark --set-default     # Set as default .md handler
+```
+
+## One Server, All Your Docs
+
+**markymark runs as a single background process.** Once started, it stays running and responds to all your commands:
+
+```bash
+# Start once from anywhere
+cd ~/docs/project-a
+markymark
+
+# Switch to different docs instantly - same server!
+cd ~/work/api-docs
+markymark  # Server switches to api-docs, no restart
+
+# Open a specific file from anywhere
+markymark ~/notes/TODO.md  # Switches to ~/notes, opens TODO.md
+```
+
+**One server. Any directory. Always ready.**
+
+## Browse & Bookmarks
+
+markymark includes a built-in directory browser accessible via the sidebar:
+
+- **Quick shortcuts**: Jump to Home, Downloads, Desktop, or Work directories
+- **Bookmarks**: Save frequently-accessed directories for one-click access
+- **Full navigation**: Browse to any directory on your system
+
+Bookmarks are stored in `~/.markymark/bookmarks.json` and persist across sessions.
+
+## Why markymark?
+
+If you work with AI coding assistants like Claude Code, you're probably generating documentation constantly. Design docs, implementation plans, debugging notes, context engineering prompts - all in markdown, all needing quick reference.
+
+### Claude Code Workflow
+
+```bash
+# Claude creates ARCHITECTURE.md, IMPLEMENTATION_PLAN.md, etc.
+# Double-click any of them → beautifully rendered in markymark
+
+# Exploring Claude's built-in skills?
+markymark ~/.claude/commands
+
+# Check out your AI framework prompts
+markymark ~/bmad-agent
+```
+
+### Context Engineering Made Visual
+
+Modern AI frameworks use markdown for prompts and skills:
+- **Claude Code**: Skills and commands in `~/.claude/`
+- **BMAD**: Agent method prompts and templates
+- **AgentOS / OpenSpec**: Specification documents
+- **Custom frameworks**: Your own prompt libraries
+
+markymark renders these beautifully with:
+- Formatted tables and lists
+- Mermaid diagrams for workflows
+- Syntax-highlighted code blocks
+- Accordion navigation for nested directories
+
+## Pumadev Integration
+
+For those who prefer `.test` domains over remembering ports:
+
+```bash
+# Set up pumadev integration
+markymark --setup-pumadev
+
+# Now always available at http://markymark.test
+```
+
+See `markymark --pumadev-info` for detailed setup instructions.
+
+## Requirements
+
+- **Ruby >= 2.7**
+
+### Installing Ruby
+
+markymark requires Ruby 2.7 or higher. macOS includes Ruby 2.6, which is too old. Install a modern Ruby via:
+
+```bash
+# Homebrew
+brew install ruby
+
+# Or use a version manager (rbenv, rvm, asdf)
+rbenv install 3.3.0
+```
+
+## Platform Support
+
+**markymark's core markdown viewer works on any platform with Ruby** - macOS, Linux, Windows.
+
+```bash
+# Works everywhere
+markymark ~/docs
+markymark README.md
+```
+
+### macOS Native Integration
+
+The native app integration (double-click `.md` files, cmd-click in iTerm, `open` command) is **macOS only** and requires:
+- **Xcode Command Line Tools** (for Swift compilation during `markymark init`)
+
+```bash
+# Install Xcode Command Line Tools if you don't have them
+xcode-select --install
+
+# Then run the setup wizard
+markymark init
+```
+
+### Contributing Cross-Platform Native Integration
+
+We'd love native file associations on other platforms! Contributions welcome for:
+
+- **Linux**: `.desktop` file integration, xdg-open support
+- **Windows**: Registry associations, shell integration
+
+## Development
+
+```bash
+git clone https://github.com/fkchang/markymark.git
+cd markymark
+bundle install
+
+# Run locally
+bundle exec exe/markymark /path/to/docs
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/fkchang/markymark.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+---
+
+<p align="center">
+  ♪ ♫ ♪<br>
+  ♫ <img src="assets/marky-mark-icon2.png" alt="Markymark" width="60"/> ♪<br>
+  ♫ ♪ ♫<br>
+  <br>
+  <i>Built with good vibrations</i> 🎵
+</p>

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/assets/README.md

@@ -0,0 +1,3 @@
+# Assets Directory
+
+Place the marky-mark-dj.jpg image here for the README.

data/config.ru

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'lib/markymark'
+
+# For pumadev: Load root path from PumadevManager if in pumadev mode
+if Markymark::PumadevManager.active?
+  # Load from pumadev configuration
+  root_file = Markymark::PumadevManager.env_file_path
+  root = File.exist?(root_file) ? File.read(root_file).strip : Dir.pwd
+else
+  # Fall back to environment variable or current directory
+  root = ENV['MARKYMARK_ROOT'] || Dir.pwd
+end
+
+root = File.expand_path(root)
+Markymark::ServerSimple.root_path = root
+Markymark::ServerSimple.real_root_path = File.realpath(root)
+
+run Markymark::ServerSimple

data/docs/for_llms.md

@@ -0,0 +1,141 @@
+# markymark - LLM Context Guide
+
+This document helps LLMs understand markymark's architecture and how to work with the codebase effectively.
+
+## What is markymark?
+
+markymark is a **dedicated local markdown viewer** that runs on any platform with Ruby. On macOS, it integrates with the operating system like a native app - double-click a `.md` file in Finder, cmd-click in iTerm, or run `open file.md` and it opens beautifully rendered in markymark.
+
+## Quick Reference
+
+### Installation & Setup
+```bash
+gem install markymark
+markymark init        # Interactive setup wizard
+markymark init -y     # Accept all defaults
+```
+
+### Common Commands
+```bash
+markymark                    # Browse current directory
+markymark README.md          # Open specific file
+markymark ~/docs             # Browse specific directory
+markymark --status           # Check server status
+markymark --stop             # Stop server
+markymark --install-app      # Install macOS app
+markymark --set-default      # Set as default .md handler
+```
+
+## Architecture Overview
+
+### Core Components
+
+| File | Purpose |
+|------|---------|
+| `lib/markymark/cli.rb` | Command-line interface, argument parsing, server management |
+| `lib/markymark/server_simple.rb` | Sinatra-based web server, markdown rendering, file discovery |
+| `lib/markymark/app_installer.rb` | macOS app bundle creation, Swift launcher compilation |
+| `lib/markymark/init_wizard.rb` | Interactive setup wizard |
+| `lib/markymark/pumadev_manager.rb` | puma-dev integration for `.test` domains |
+
+### Key Files
+
+- `exe/markymark` - Entry point executable
+- `lib/views/simple.erb` - Main HTML template
+- `lib/public/css/style.css` - Styling
+- `lib/public/js/theme.js` - Dark/light theme toggle
+- `assets/Markymark.icns` - macOS app icon
+
+### How the macOS App Works
+
+The app bundle at `~/Applications/Markymark.app` contains:
+1. **Swift launcher** (`Contents/MacOS/markymark-launcher`) - Compiled binary that receives files from Launch Services via `NSApplicationDelegate.application(_:openFile:)`
+2. **Shell helper** (`Contents/MacOS/markymark-helper`) - Called by Swift launcher, sets up Ruby environment and invokes markymark CLI
+3. **Info.plist** - Declares file type associations (`.md`, `.markdown`, `.mdown`, `.mkd`)
+
+This architecture is necessary because:
+- AppleScript droplets don't receive files from macOS `open` command
+- Ruby scripts can't be registered as file handlers directly
+- Swift properly implements the Launch Services file-opening protocol
+
+### Server Architecture
+
+markymark runs as a **single persistent server**:
+- PID tracked in `~/.markymark/server.pid`
+- Supports directory switching without restart via `/switch` endpoint
+- Can run in standalone mode (port 4545) or pumadev mode (markymark.test)
+
+### Data Storage
+
+All persistent data stored in `~/.markymark/`:
+- `server.pid` - Running server info (port, PID, directory)
+- `bookmarks.json` - Saved directory bookmarks
+- `launcher.log` - Debug log from app launcher
+- `root_path` - Current root for pumadev mode
+
+## Common Development Tasks
+
+### Rebuilding the Gem
+```bash
+gem build markymark.gemspec
+gem install markymark-0.1.0.gem
+```
+
+### Reinstalling the App
+```bash
+echo 'y' | markymark --install-app
+xattr -cr ~/Applications/Markymark.app  # Clear quarantine
+```
+
+### Testing the Launcher
+```bash
+# Clear log and test
+: > ~/.markymark/launcher.log
+open -a ~/Applications/Markymark.app /path/to/file.md
+cat ~/.markymark/launcher.log
+```
+
+### Debugging App Issues
+1. Check `~/.markymark/launcher.log` for helper script output
+2. Verify paths in `~/Applications/Markymark.app/Contents/MacOS/markymark-helper`
+3. Test Swift launcher receives files: the log should show "Helper called with: /path/to/file"
+
+## Key Implementation Details
+
+### File Discovery
+- Uses `Dir.glob` with fallback to manual traversal for permission-protected directories
+- Skips `~/Library/` and other protected macOS directories
+- Groups files by directory with accordion UI
+
+### Markdown Rendering
+- Kramdown with GFM (GitHub Flavored Markdown) parser
+- Rouge for syntax highlighting
+- Mermaid.js for diagrams (client-side rendering)
+- UTF-8 encoding for international character support
+
+### Ruby Environment Setup
+The macOS app helper script bakes in:
+- `RUBY_PATH` - Full path to Ruby executable
+- `MARKYMARK_PATH` - Path to markymark executable in gem
+- `GEM_HOME` / `GEM_PATH` - Gem environment for require resolution
+- `RUBYLIB` - Path to markymark lib directory
+
+This is necessary because the Swift launcher doesn't inherit shell environment (no RVM/rbenv setup).
+
+## Dependencies
+
+- `sinatra` ~> 3.0 - Web framework
+- `puma` ~> 6.0 - Web server
+- `kramdown` ~> 2.4 - Markdown parser
+- `kramdown-parser-gfm` - GitHub Flavored Markdown
+- `rouge` ~> 4.0 - Syntax highlighting
+- `listen` ~> 3.8 - File watching (for future live reload)
+- `launchy` ~> 2.5 - Browser opening
+
+## Platform Support
+
+**The core markdown viewer works on any platform with Ruby** (macOS, Linux, Windows).
+
+The **native app integration** (double-click to open, cmd-click in terminal) is **macOS only**. Cross-platform native integration contributions welcome:
+- **Linux**: Need `.desktop` file integration, `xdg-open` support
+- **Windows**: Need registry associations, shell integration

data/docs/plans/2025-12-18-macos-app-installer-design.md

@@ -0,0 +1,149 @@
+# macOS App Installer & Init Wizard Design
+
+**Date:** 2025-12-18
+**Status:** Approved
+
+## Overview
+
+Add the ability to install Markymark as a macOS application that can be registered as the default handler for `.md` files. Includes an interactive setup wizard and standalone CLI flags.
+
+## CLI Interface
+
+### New Commands
+
+```bash
+markymark init              # Interactive setup wizard
+markymark init -y           # Accept all defaults (scripted)
+markymark --install-app     # Install macOS app bundle only
+markymark --set-default     # Set as default .md handler only
+markymark --uninstall-app   # Remove the app bundle
+```
+
+### Init Wizard Flow
+
+1. "Install Markymark.app for macOS file handling? [Y/n]"
+2. "Set Markymark as default app for .md files? [Y/n]" (only if step 1 was yes)
+3. "Setup server mode?" → choices: standalone (port 4545) / pumadev / skip
+4. Summary of what was configured
+
+**Defaults for `-y` flag:** Install app, set as default, skip server setup.
+
+## macOS App Bundle
+
+### Location
+
+`~/Applications/Markymark.app` - User's Applications folder, no sudo needed, persists across gem updates.
+
+### Structure
+
+```
+Markymark.app/
+├── Contents/
+│   ├── Info.plist          # App metadata, file associations
+│   ├── MacOS/
+│   │   └── markymark-launcher  # Shell script with baked-in Ruby paths
+│   └── Resources/
+│       └── Markymark.icns  # App icon
+```
+
+### Info.plist Key Elements
+
+- `CFBundleDocumentTypes` - Registers for `.md`, `.markdown` files
+- `CFBundleIdentifier` - `com.markymark.app`
+- `CFBundleURLTypes` - Optional URL scheme `markymark://`
+
+### Launcher Script Strategy
+
+At install time, capture the current Ruby environment and bake it into the launcher:
+
+```bash
+# During install, detect:
+RUBY_PATH=$(which ruby)
+MARKYMARK_PATH=$(which markymark)
+
+# Generated launcher uses exact paths:
+#!/bin/bash
+exec /path/to/ruby /path/to/markymark "$@"
+```
+
+**Benefits:**
+- No runtime version manager detection needed
+- Works with any Ruby setup (rvm, rbenv, asdf, homebrew, system)
+- Guaranteed to use the same Ruby that installed the gem
+
+**Caveat:** If user changes Ruby versions, they need to run `markymark --install-app` again.
+
+## Implementation Structure
+
+### New Files
+
+**`lib/markymark/app_installer.rb`**
+
+Handles:
+- Creating the `.app` bundle structure
+- Generating `Info.plist` with file associations
+- Writing the launcher script with baked-in Ruby paths
+- Copying the icon from gem assets
+- Setting executable permissions
+- Registering as default handler (via `duti` or `lsregister`)
+
+**`lib/markymark/init_wizard.rb`**
+
+Handles:
+- Interactive prompts
+- `-y` flag for accepting defaults
+- Calling `AppInstaller` and `PumadevManager` as needed
+
+### CLI Additions (`lib/markymark/cli.rb`)
+
+```ruby
+opts.on('--install-app', 'Install macOS app bundle to ~/Applications')
+opts.on('--uninstall-app', 'Remove macOS app bundle')
+opts.on('--set-default', 'Set as default handler for .md files')
+# init handled as subcommand
+```
+
+## Error Handling
+
+### Pre-flight Checks for `--install-app`
+
+- macOS only (fail gracefully on Linux/Windows with helpful message)
+- Check `~/Applications` exists (create if not)
+- Warn if app already exists, ask to overwrite
+
+### Pre-flight Checks for `--set-default`
+
+- App must be installed first
+- Check if `duti` is available; if not, fall back to manual instructions
+
+### Launcher Script Errors
+
+- If baked-in Ruby path no longer exists → show error dialog via `osascript`
+- Pass through markymark errors to Console.app for debugging
+
+### Version Mismatch Detection
+
+On `markymark --status`:
+- Check if installed app's Ruby path still exists
+- Warn: "Markymark.app may need reinstalling (Ruby path changed)"
+
+## Web UI & README Updates
+
+### Sidebar Header (simple.erb)
+
+- Add `marky-mark-icon2.png` as small logo (~48px)
+- Position above or beside "Markymark" title
+
+### README.md
+
+- Add DJ image (`marky-mark-dj.jpg`) at top as project banner
+- Add "Installation" section covering `markymark init`
+- Document all new flags
+
+## Assets
+
+Already prepared:
+- `assets/marky-mark-icon2.png` - 1024x1024 source icon
+- `assets/Markymark.icns` - macOS app icon bundle
+- `assets/Markymark.iconset/` - All icon sizes (16-1024)
+- `assets/marky-mark-dj.jpg` - README banner image

data/exe/markymark

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "markymark"
+
+Markymark::CLI.run(ARGV)