easymd-cli 0.1.0

package/README.md

@@ -0,0 +1,110 @@
+# easymd
+
+**Google Docs for markdown — except the file on disk stays canonical.**
+
+Collaborate on `CLAUDE.md`, `AGENTS.md`, or any `.md` file in real time. The document on screen is the actual file in your repo. No import/export round-trip, no copy-paste tax.
+
+## Web app (landing + demo)
+
+Professional landing page with **token savings** messaging, **Clerk auth** for signups, and a **protected live demo** at `/demo`.
+
+```bash
+cd web
+cp .env.example .env.local   # add Clerk keys from dashboard.clerk.com
+npm install
+npm run dev                  # Next.js + collab WebSocket server
+```
+
+Open [http://localhost:3000](http://localhost:3000) → Sign up → Live collaborative editor.
+
+### Token savings (why markdown for AI)
+
+Converting PDFs, Word/DOCX, or HTML to clean `.md` cuts token usage dramatically:
+
+| Format | Typical savings |
+|--------|-----------------|
+| Raw HTML | 75–90% |
+| Word / DOCX | 50–70% |
+| Text-based PDF | 40–65% |
+
+Markdown strips hidden formatting metadata while keeping structure agents need — then reference `@CLAUDE.md` on demand instead of pasting every prompt.
+
+## CLI (local file editing)
+
+```bash
+npm install
+npm run build
+easymd open CLAUDE.md
+```
+
+Share the URL with a teammate. Edits sync live via CRDT. Changes land straight back to the file on disk and into git.
+
+## CLI auto-sync (push every .md into your account)
+
+Sign in once, then have every markdown file in your repo sync into your easymd account
+automatically — so anything you or an AI agent writes to disk shows up in the dashboard
+and is editable live.
+
+```bash
+npx easymd-cli login          # opens your browser, sign in with Clerk, authorize this machine
+npx easymd-cli auto on        # background watcher: every new/changed .md syncs to your account
+npx easymd-cli auto status    # check it's running
+npx easymd-cli auto off       # stop it
+```
+
+Other commands:
+
+```bash
+easymd sync ./docs        # one-shot push of all .md under a folder
+easymd watch .            # foreground watcher (what `auto on` runs detached)
+easymd whoami             # show the logged-in account
+easymd logout             # remove credentials + stop auto-sync
+```
+
+Credentials live in `~/.easymd/credentials.json` (a long-lived token bound to your Clerk
+user id — secrets stay on the server). Point the CLI at a self-hosted/production instance
+with `EASYMD_URL=https://your-easymd.example.com`.
+
+## AI agents (MCP)
+
+easymd ships an MCP server so AI agents edit the **same live documents** humans do — changes sync in real time and persist to Supabase.
+
+```bash
+cd web
+npm run mcp          # stdio MCP server (needs the collab server running + Supabase env)
+```
+
+Tools: `list_documents`, `read_document`, `create_document`, `update_document`, `append_to_document`. Docs an agent creates show up in the app's document switcher for everyone; edits an agent makes appear live in any open editor. Register it with Cursor/Claude via `.cursor/mcp.json`.
+
+## Why
+
+AI agents made markdown load-bearing. `AGENTS.md` and `CLAUDE.md` are now the single source of truth for how your project works — but collaborating on them still means pull requests for engineers or copy-paste between Google Docs and your repo for everyone else.
+
+easymd fixes the one painful shared file:
+
+- **Canonical file stays canonical** — edit the real `.md` on disk, not a hosted copy
+- **Real-time multiplayer** — live cursors, presence, CRDT conflict resolution
+- **CLI keeps it honest** — `easymd open path/to/file.md` from your terminal
+- **Agents stay in the loop** — the same file humans edit is what agents read and write
+- **Token-efficient by design** — lightweight `.md` beats bloated DOCX/HTML/PDF for agent context
+
+## Project structure
+
+```
+web/                Next.js landing, Clerk auth, protected demo
+bin/easymd.js       CLI entry point
+src/server.js       Local HTTP + WebSocket server
+src/file-sync.js    Disk ↔ Yjs sync
+client/             CLI browser editor UI
+```
+
+## Clerk setup
+
+1. Create an app at [dashboard.clerk.com](https://dashboard.clerk.com)
+2. Copy keys into `web/.env.local` (see `web/.env.example`)
+3. Enable Email + Google sign-in (recommended)
+4. Set redirect URLs: after sign-in/sign-up → `/demo`
+
+## License
+
+MIT

package/bin/easymd.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+
+import { resolve } from 'path';
+import { access } from 'fs/promises';
+import openBrowser from 'open';
+import { startServer } from '../src/server.js';
+import { login, logout, whoami } from '../src/cli/auth.js';
+import { syncDir, watchDir } from '../src/cli/sync.js';
+import { autoOn, autoOff, autoStatus } from '../src/cli/auto.js';
+import { getCredentials } from '../src/cli/config.js';
+
+const HELP = `
+easymd — collaborate on markdown files in your repo, live with humans and AI agents
+
+Usage:
+  easymd login                 Sign in with Clerk (opens your browser) and authorize this machine
+  easymd logout                Remove stored credentials and stop auto-sync
+  easymd whoami                Show the logged-in account
+
+  easymd auto on [dir]         Start background auto-sync: every .md is pushed to your account
+  easymd auto off              Stop background auto-sync
+  easymd auto status           Show whether auto-sync is running
+
+  easymd sync [dir]            One-shot: push all .md files under dir (default: .) to your account
+  easymd watch [dir]           Foreground watcher (what 'auto on' runs in the background)
+
+  easymd open <file>           Open a local .md for real-time collaborative editing in the browser
+  easymd open <file> --port N  Use a fixed port (default: random)
+
+Environment:
+  EASYMD_URL                   easymd web app URL (default: http://localhost:3000)
+
+Examples:
+  easymd login
+  easymd auto on               # auto-sync the current repo's markdown into your account
+  easymd sync ./docs
+  easymd open CLAUDE.md
+`.trim();
+
+function flag(args, name) {
+  return args.includes(name);
+}
+
+async function cmdOpen(args) {
+  const file = args[0];
+  if (!file) {
+    console.error('Missing file path.\n');
+    console.log(HELP);
+    process.exit(1);
+  }
+  let port;
+  const portIdx = args.indexOf('--port');
+  if (portIdx !== -1) {
+    port = Number(args[portIdx + 1]);
+    if (!Number.isFinite(port) || port < 1) {
+      console.error('Invalid --port value.');
+      process.exit(1);
+    }
+  }
+
+  const absPath = resolve(file);
+  try {
+    await access(absPath);
+  } catch {
+    console.log(`Note: ${absPath} does not exist yet — it will be created on save.`);
+  }
+
+  const { url, shutdown } = await startServer(absPath, { port });
+  console.log('');
+  console.log('  easymd');
+  console.log('  ─────────────────────────────────────');
+  console.log(`  File:  ${absPath}`);
+  console.log(`  Local: ${url}`);
+  console.log('  Share this URL with teammates on your network.');
+  console.log('  Press Ctrl+C to stop.');
+  console.log('');
+  await openBrowser(url);
+
+  const onExit = () => {
+    shutdown();
+    process.exit(0);
+  };
+  process.on('SIGINT', onExit);
+  process.on('SIGTERM', onExit);
+}
+
+async function cmdAuto(args) {
+  const sub = args[0];
+  if (sub === 'on') {
+    // One command does it all: log in via the browser if needed, then start auto-sync.
+    const creds = await getCredentials();
+    if (!creds?.token) {
+      console.log('Not logged in yet — opening the browser to sign in first…\n');
+      await login();
+    }
+    return autoOn(resolve(args[1] || '.'));
+  }
+  if (sub === 'off') return autoOff();
+  if (sub === 'status' || !sub) return autoStatus();
+  console.error(`Unknown: easymd auto ${sub}\n`);
+  console.log('Use: easymd auto on|off|status');
+  process.exit(1);
+}
+
+async function cmdWatch(args) {
+  const dirArgs = args.filter((a) => !a.startsWith('-'));
+  const root = resolve(dirArgs[0] || '.');
+  const quiet = flag(args, '--quiet');
+  const watcher = await watchDir(root, { quiet });
+  const onExit = async () => {
+    await watcher.close();
+    process.exit(0);
+  };
+  process.on('SIGINT', onExit);
+  process.on('SIGTERM', onExit);
+}
+
+async function cmdSync(args) {
+  const dirArgs = args.filter((a) => !a.startsWith('-'));
+  const root = resolve(dirArgs[0] || '.');
+  await syncDir(root, { quiet: flag(args, '--quiet') });
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const command = argv[0];
+  const rest = argv.slice(1);
+
+  if (!command || command === '-h' || command === '--help' || command === 'help') {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  switch (command) {
+    case 'login':
+      return login();
+    case 'logout':
+      return logout();
+    case 'whoami':
+      return whoami();
+    case 'auto':
+      return cmdAuto(rest);
+    case 'watch':
+      return cmdWatch(rest);
+    case 'sync':
+      return cmdSync(rest);
+    case 'open':
+      return cmdOpen(rest);
+    default:
+      console.error(`Unknown command: ${command}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('easymd:', err.message);
+  process.exit(1);
+});

package/client/index.html

@@ -0,0 +1,49 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>easymd</title>
+    <link rel="stylesheet" href="/styles.css" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=Inter:wght@400;500;600&display=swap"
+      rel="stylesheet"
+    />
+  </head>
+  <body>
+    <header class="toolbar">
+      <div class="brand">
+        <span class="logo">easymd</span>
+        <span class="filename" id="filename">loading…</span>
+      </div>
+      <div class="toolbar-right">
+        <div class="presence" id="presence"></div>
+        <div class="view-toggle" role="tablist" aria-label="View mode">
+          <button class="toggle-btn active" data-view="edit" role="tab" aria-selected="true">
+            Edit
+          </button>
+          <button class="toggle-btn" data-view="split" role="tab" aria-selected="false">
+            Split
+          </button>
+          <button class="toggle-btn" data-view="preview" role="tab" aria-selected="false">
+            Preview
+          </button>
+        </div>
+        <span class="sync-status" id="sync-status" title="Sync status">●</span>
+      </div>
+    </header>
+
+    <main class="workspace" id="workspace">
+      <section class="editor-pane" id="editor-pane">
+        <div id="editor"></div>
+      </section>
+      <section class="preview-pane hidden" id="preview-pane">
+        <article class="markdown-body" id="preview"></article>
+      </section>
+    </main>
+
+    <script type="module" src="/client.js"></script>
+  </body>
+</html>

package/client/main.js

@@ -0,0 +1,169 @@
+import * as Y from 'yjs';
+import { WebsocketProvider } from 'y-websocket';
+import { EditorState } from '@codemirror/state';
+import { EditorView, keymap, lineNumbers, drawSelection } from '@codemirror/view';
+import { defaultKeymap, history, historyKeymap } from '@codemirror/commands';
+import { markdown } from '@codemirror/lang-markdown';
+import { yCollab } from 'y-codemirror.next';
+import { marked } from 'marked';
+
+const COLORS = ['#58a6ff', '#3fb950', '#d2a8ff', '#f0883e', '#ff7b72', '#79c0ff', '#e3b341'];
+
+const filenameEl = document.getElementById('filename');
+const presenceEl = document.getElementById('presence');
+const syncStatusEl = document.getElementById('sync-status');
+const workspaceEl = document.getElementById('workspace');
+const editorPaneEl = document.getElementById('editor-pane');
+const previewPaneEl = document.getElementById('preview-pane');
+const previewEl = document.getElementById('preview');
+const toggleButtons = document.querySelectorAll('.toggle-btn');
+
+function randomName() {
+  const names = ['Alex', 'Sam', 'Jordan', 'Riley', 'Casey', 'Morgan', 'Taylor', 'Quinn'];
+  return names[Math.floor(Math.random() * names.length)];
+}
+
+function colorForUser(userId) {
+  let hash = 0;
+  for (let i = 0; i < userId.length; i++) {
+    hash = userId.charCodeAt(i) + ((hash << 5) - hash);
+  }
+  return COLORS[Math.abs(hash) % COLORS.length];
+}
+
+function setSyncStatus(state) {
+  syncStatusEl.className = 'sync-status';
+  if (state === 'connected') {
+    syncStatusEl.textContent = '●';
+    syncStatusEl.title = 'Connected — changes save to disk';
+  } else if (state === 'connecting') {
+    syncStatusEl.classList.add('connecting');
+    syncStatusEl.textContent = '●';
+    syncStatusEl.title = 'Connecting…';
+  } else {
+    syncStatusEl.classList.add('disconnected');
+    syncStatusEl.textContent = '●';
+    syncStatusEl.title = 'Disconnected';
+  }
+}
+
+function renderPreview(markdownText) {
+  previewEl.innerHTML = marked.parse(markdownText, { gfm: true, breaks: false });
+}
+
+function setView(mode) {
+  workspaceEl.classList.remove('split', 'preview');
+  editorPaneEl.classList.remove('hidden');
+  previewPaneEl.classList.add('hidden');
+
+  toggleButtons.forEach((btn) => {
+    const active = btn.dataset.view === mode;
+    btn.classList.toggle('active', active);
+    btn.setAttribute('aria-selected', String(active));
+  });
+
+  if (mode === 'split') {
+    workspaceEl.classList.add('split');
+    previewPaneEl.classList.remove('hidden');
+  } else if (mode === 'preview') {
+    workspaceEl.classList.add('preview');
+    previewPaneEl.classList.remove('hidden');
+  }
+}
+
+toggleButtons.forEach((btn) => {
+  btn.addEventListener('click', () => setView(btn.dataset.view));
+});
+
+async function init() {
+  setSyncStatus('connecting');
+
+  const sessionRes = await fetch('/api/session');
+  const session = await sessionRes.json();
+  filenameEl.textContent = session.fileName;
+  filenameEl.title = session.filePath;
+  document.title = `${session.fileName} — easymd`;
+
+  const ydoc = new Y.Doc();
+  const ytext = ydoc.getText('markdown');
+
+  const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+  const provider = new WebsocketProvider(
+    `${wsProtocol}//${location.host}`,
+    session.docName,
+    ydoc,
+    { connect: true }
+  );
+
+  const userId = crypto.randomUUID();
+  const userName = randomName();
+  const userColor = colorForUser(userId);
+
+  provider.awareness.setLocalStateField('user', {
+    name: userName,
+    color: userColor,
+  });
+
+  provider.on('status', ({ status }) => {
+    setSyncStatus(status === 'connected' ? 'connected' : 'connecting');
+  });
+
+  provider.on('connection-close', () => setSyncStatus('disconnected'));
+
+  function renderPresence() {
+    const states = provider.awareness.getStates();
+    presenceEl.innerHTML = '';
+
+    states.forEach((state) => {
+      const user = state.user;
+      if (!user) return;
+      const avatar = document.createElement('span');
+      avatar.className = 'presence-avatar';
+      avatar.style.background = user.color;
+      avatar.textContent = user.name.slice(0, 1).toUpperCase();
+      avatar.title = user.name;
+      presenceEl.appendChild(avatar);
+    });
+  }
+
+  provider.awareness.on('change', renderPresence);
+  renderPresence();
+
+  const undoManager = new Y.UndoManager(ytext);
+
+  const state = EditorState.create({
+    doc: ytext.toString(),
+    extensions: [
+      lineNumbers(),
+      drawSelection(),
+      history(),
+      markdown(),
+      keymap.of([...defaultKeymap, ...historyKeymap]),
+      yCollab(ytext, provider.awareness, { undoManager }),
+      EditorView.updateListener.of((update) => {
+        if (update.docChanged) {
+          renderPreview(update.state.doc.toString());
+        }
+      }),
+      EditorView.theme({
+        '&': { backgroundColor: 'transparent', color: 'var(--text)' },
+        '.cm-gutters': { backgroundColor: 'var(--bg)', color: 'var(--muted)' },
+      }),
+    ],
+  });
+
+  const view = new EditorView({ state, parent: document.getElementById('editor') });
+  renderPreview(view.state.doc.toString());
+
+  ytext.observe(() => {
+    renderPreview(ytext.toString());
+  });
+
+  return { view, provider };
+}
+
+init().catch((err) => {
+  console.error(err);
+  filenameEl.textContent = 'Failed to connect';
+  setSyncStatus('disconnected');
+});