npm - easymd-cli - Versions diffs - 0.1.0 - Mend

easymd-cli 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/package.json ADDED Viewed

@@ -0,0 +1,55 @@
+{
+  "name": "easymd-cli",
+  "version": "0.1.0",
+  "description": "Google Docs for markdown — collaborate on the actual .md file in your repo, live with humans and AI agents. CLI: login, auto-sync, and open .md files for real-time editing.",
+  "type": "module",
+  "bin": {
+    "easymd": "./bin/easymd.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "client",
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.js",
+    "postinstall": "node scripts/build.js > /dev/null 2>&1 || true",
+    "prepublishOnly": "npm run build",
+    "start": "node bin/easymd.js",
+    "web:dev": "npm run dev --prefix web",
+    "web:build": "npm run build --prefix web"
+  },
+  "keywords": [
+    "markdown",
+    "collaboration",
+    "crdt",
+    "agents",
+    "claude",
+    "cursor"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "express": "^4.21.2",
+    "open": "^10.1.0",
+    "ws": "^8.18.0",
+    "y-websocket": "^2.1.0",
+    "yjs": "^13.6.24"
+  },
+  "devDependencies": {
+    "@codemirror/commands": "^6.8.0",
+    "@codemirror/lang-markdown": "^6.3.2",
+    "@codemirror/state": "^6.5.2",
+    "@codemirror/view": "^6.36.4",
+    "esbuild": "^0.25.0",
+    "marked": "^15.0.7",
+    "y-codemirror.next": "^0.3.5",
+    "y-protocols": "^1.0.6",
+    "y-websocket": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cli/auth.js ADDED Viewed

@@ -0,0 +1,91 @@
+import { createServer } from 'http';
+import openBrowser from 'open';
+import {
+  DEFAULT_URL,
+  getCredentials,
+  saveCredentials,
+  clearCredentials,
+  clearAuto,
+  userIdFromToken,
+} from './config.js';
+import { autoOff } from './auto.js';
+// Spin up a one-shot localhost server that the browser hands the token back to.
+function startCallbackServer() {
+  return new Promise((resolve) => {
+    let resolveToken;
+    const tokenPromise = new Promise((r) => (resolveToken = r));
+    const server = createServer((req, res) => {
+      const u = new URL(req.url, 'http://127.0.0.1');
+      if (u.pathname === '/callback') {
+        const token = u.searchParams.get('token') || '';
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end(
+          `<!doctype html><html><body style="font-family:system-ui;text-align:center;padding:4rem;background:#0b0e13;color:#e6e8eb">
+            <div style="display:inline-flex;width:48px;height:48px;align-items:center;justify-content:center;border-radius:12px;background:#c6f24e;color:#12160a;font-weight:700;font-size:20px">e</div>
+            <h2 style="margin-top:1rem">✓ easymd CLI authorized</h2>
+            <p style="color:#9aa3af">You can close this tab and return to your terminal.</p>
+          </body></html>`,
+        );
+        resolveToken(token);
+      } else {
+        res.writeHead(404);
+        res.end();
+      }
+    });
+    server.listen(0, '127.0.0.1', () => {
+      resolve({ port: server.address().port, tokenPromise, close: () => server.close() });
+    });
+  });
+}
+export async function login() {
+  const base = DEFAULT_URL;
+  const { port, tokenPromise, close } = await startCallbackServer();
+  const url = `${base}/cli-auth?port=${port}`;
+  console.log('\neasymd login');
+  console.log('─────────────────────────────────────');
+  console.log('Opening your browser to sign in with Clerk and authorize this machine:');
+  console.log(`  ${url}\n`);
+  try {
+    await openBrowser(url);
+  } catch {
+    console.log('(Could not open a browser automatically — open the URL above manually.)');
+  }
+  console.log('Waiting for authorization…  (Ctrl+C to cancel)');
+  const token = await Promise.race([
+    tokenPromise,
+    new Promise((_, rej) => setTimeout(() => rej(new Error('Timed out waiting for authorization.')), 300000)),
+  ]).finally(close);
+  if (!token) throw new Error('No token received from the browser.');
+  const { uid } = userIdFromToken(token);
+  await saveCredentials({ token, userId: uid, url: base, savedAt: new Date().toISOString() });
+  console.log(`\n✓ Logged in${uid ? ` as ${uid}` : ''}.`);
+  console.log('  Credentials saved to ~/.easymd/credentials.json');
+  console.log('  Next: `easymd auto on` to start syncing .md files to your account.\n');
+}
+export async function logout() {
+  await autoOff().catch(() => {});
+  await clearAuto().catch(() => {});
+  await clearCredentials();
+  console.log('✓ Logged out. Credentials removed.');
+}
+export async function whoami() {
+  const creds = await getCredentials();
+  if (!creds?.token) {
+    console.log('Not logged in. Run `easymd login`.');
+    return;
+  }
+  const { uid, exp } = userIdFromToken(creds.token);
+  const expired = exp && exp < Date.now();
+  console.log(`Account: ${uid || creds.userId || 'unknown'}`);
+  console.log(`Server:  ${creds.url}`);
+  console.log(`Status:  ${expired ? 'EXPIRED — run `easymd login` again' : 'active'}`);
+}

package/src/cli/auto.js ADDED Viewed

@@ -0,0 +1,65 @@
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { getAuto, saveAuto, clearAuto, requireCredentials } from './config.js';
+const BIN = fileURLToPath(new URL('../../bin/easymd.js', import.meta.url));
+const isAlive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+// Toggle the background watcher ON: spawn a detached `easymd watch` process that
+// keeps running after this command (and the terminal) exits.
+export async function autoOn(root) {
+  await requireCredentials(); // fail fast if not logged in
+  const existing = await getAuto();
+  if (existing && isAlive(existing.pid)) {
+    console.log(`Auto-sync is already ON (pid ${existing.pid}, watching ${existing.root}).`);
+    return;
+  }
+  const child = spawn(process.execPath, [BIN, 'watch', root, '--quiet'], {
+    detached: true,
+    stdio: 'ignore',
+    env: process.env,
+  });
+  child.unref();
+  await saveAuto({ pid: child.pid, root, startedAt: new Date().toISOString() });
+  console.log(`✓ Auto-sync ON — watching ${root} (pid ${child.pid}).`);
+  console.log('  Every new or changed .md file now syncs to your easymd account automatically.');
+  console.log('  Turn it off with `easymd auto off`.');
+}
+export async function autoOff() {
+  const a = await getAuto();
+  if (!a) {
+    console.log('Auto-sync is already OFF.');
+    return;
+  }
+  if (isAlive(a.pid)) {
+    try {
+      process.kill(a.pid);
+    } catch {
+      /* already gone */
+    }
+  }
+  await clearAuto();
+  console.log('✓ Auto-sync OFF.');
+}
+export async function autoStatus() {
+  const a = await getAuto();
+  if (a && isAlive(a.pid)) {
+    console.log(`Auto-sync: ON — pid ${a.pid}, watching ${a.root} (since ${a.startedAt}).`);
+  } else {
+    if (a) await clearAuto(); // stale pid file
+    console.log('Auto-sync: OFF.');
+  }
+}

package/src/cli/config.js ADDED Viewed

@@ -0,0 +1,55 @@
+import { homedir } from 'os';
+import { join } from 'path';
+import { mkdir, readFile, writeFile, rm } from 'fs/promises';
+export const CONFIG_DIR = join(homedir(), '.easymd');
+const CRED_FILE = join(CONFIG_DIR, 'credentials.json');
+const AUTO_FILE = join(CONFIG_DIR, 'auto.json');
+// Where the easymd web app lives. Override with EASYMD_URL for self-hosted / production.
+export const DEFAULT_URL = process.env.EASYMD_URL || 'http://localhost:3000';
+async function readJson(p) {
+  try {
+    return JSON.parse(await readFile(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+async function writeJson(p, obj) {
+  await mkdir(CONFIG_DIR, { recursive: true });
+  await writeFile(p, JSON.stringify(obj, null, 2), { mode: 0o600 });
+}
+export const getCredentials = () => readJson(CRED_FILE);
+export const saveCredentials = (c) => writeJson(CRED_FILE, c);
+export const clearCredentials = () => rm(CRED_FILE, { force: true });
+export const getAuto = () => readJson(AUTO_FILE);
+export const saveAuto = (a) => writeJson(AUTO_FILE, a);
+export const clearAuto = () => rm(AUTO_FILE, { force: true });
+// Decode the Clerk user id baked into a CLI token (easymd_<b64url payload>.<sig>).
+export function userIdFromToken(token) {
+  try {
+    const body = token.slice('easymd_'.length);
+    const payload = body.slice(0, body.indexOf('.'));
+    const json = JSON.parse(Buffer.from(payload.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8'));
+    return { uid: json.uid || null, exp: json.exp || 0 };
+  } catch {
+    return { uid: null, exp: 0 };
+  }
+}
+// Returns credentials if present and unexpired, else throws a helpful error.
+export async function requireCredentials() {
+  const creds = await getCredentials();
+  if (!creds?.token) {
+    throw new Error('Not logged in. Run `easymd login` first.');
+  }
+  const { exp } = userIdFromToken(creds.token);
+  if (exp && exp < Date.now()) {
+    throw new Error('Your session has expired. Run `easymd login` again.');
+  }
+  return creds;
+}

package/src/cli/sync.js ADDED Viewed

@@ -0,0 +1,109 @@
+import { readFile, readdir } from 'fs/promises';
+import { basename, join, relative } from 'path';
+import chokidar from 'chokidar';
+import { requireCredentials } from './config.js';
+const IGNORE_DIRS = new Set(['node_modules', '.git', 'dist', '.next', '.turbo', 'build', 'coverage']);
+// Document name sent to the server: repo-relative path without the .md extension.
+// The server slugs it (e.g. "docs/spec" → "docs-spec") and namespaces it to the account.
+function docNameFor(filePath, root) {
+  const rel = relative(root, filePath).replace(/\\/g, '/').replace(/\.md$/i, '');
+  return rel || basename(filePath).replace(/\.md$/i, '');
+}
+export async function uploadFile(filePath, { root, creds }) {
+  const content = await readFile(filePath, 'utf8');
+  const name = docNameFor(filePath, root);
+  const res = await fetch(`${creds.url}/api/cli/documents`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${creds.token}` },
+    body: JSON.stringify({ name, content, title: basename(name) }),
+  });
+  if (!res.ok) {
+    const j = await res.json().catch(() => ({}));
+    throw new Error(j.error || `HTTP ${res.status}`);
+  }
+  return { name, ...(await res.json().catch(() => ({}))) };
+}
+// Recursively collect .md files under root, skipping ignored dirs and dotfiles.
+async function collectMarkdown(dir, root, out = []) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (e.name.startsWith('.')) continue;
+    const full = join(dir, e.name);
+    if (e.isDirectory()) {
+      if (!IGNORE_DIRS.has(e.name)) await collectMarkdown(full, root, out);
+    } else if (e.isFile() && /\.md$/i.test(e.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+// One-shot: push every .md under `root` to the account.
+export async function syncDir(root, { quiet = false } = {}) {
+  const creds = await requireCredentials();
+  const files = await collectMarkdown(root, root);
+  if (!files.length) {
+    if (!quiet) console.log('No .md files found.');
+    return { ok: 0, fail: 0 };
+  }
+  let ok = 0;
+  let fail = 0;
+  for (const f of files) {
+    try {
+      const r = await uploadFile(f, { root, creds });
+      ok++;
+      if (!quiet) console.log(`  ✓ ${relative(root, f)} → ${r.name}`);
+    } catch (e) {
+      fail++;
+      if (!quiet) console.log(`  ✗ ${relative(root, f)} — ${e.message}`);
+    }
+  }
+  if (!quiet) console.log(`\nSynced ${ok} file(s)${fail ? `, ${fail} failed` : ''}.`);
+  return { ok, fail };
+}
+// Long-running: watch `root` and push .md files as they're added/changed.
+export async function watchDir(root, { quiet = false } = {}) {
+  const creds = await requireCredentials();
+  const log = (...a) => !quiet && console.log(...a);
+  const pending = new Map(); // path -> timer (debounce)
+  const push = (filePath) => {
+    clearTimeout(pending.get(filePath));
+    pending.set(
+      filePath,
+      setTimeout(async () => {
+        pending.delete(filePath);
+        try {
+          const r = await uploadFile(filePath, { root, creds });
+          log(`  ✓ synced ${relative(root, filePath)} → ${r.name}`);
+        } catch (e) {
+          log(`  ✗ ${relative(root, filePath)} — ${e.message}`);
+        }
+      }, 400),
+    );
+  };
+  const watcher = chokidar.watch('**/*.md', {
+    cwd: root,
+    ignored: (p) => p.split(/[\\/]/).some((seg) => IGNORE_DIRS.has(seg) || (seg.startsWith('.') && seg.length > 1)),
+    ignoreInitial: false, // also sync existing files on startup ("auto add all .md")
+    awaitWriteFinish: { stabilityThreshold: 300, pollInterval: 100 },
+  });
+  watcher
+    .on('add', (p) => push(join(root, p)))
+    .on('change', (p) => push(join(root, p)))
+    .on('ready', () => log(`Watching ${root} for .md changes. Press Ctrl+C to stop.`));
+  return watcher;
+}

package/src/file-sync.js ADDED Viewed

@@ -0,0 +1,85 @@
+import chokidar from 'chokidar';
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { dirname } from 'path';
+const DEBOUNCE_MS = 250;
+/**
+ * Keeps a Y.Text in sync with a file on disk — disk is canonical.
+ * External edits (git, agents, other tools) flow in; editor edits flow out.
+ */
+export function createFileSync(filePath, ytext) {
+  let writing = false;
+  let debounceTimer = null;
+  let destroyed = false;
+  async function readDisk() {
+    try {
+      return await readFile(filePath, 'utf-8');
+    } catch (err) {
+      if (err.code === 'ENOENT') return '';
+      throw err;
+    }
+  }
+  async function loadFromDisk() {
+    const content = await readDisk();
+    if (ytext.toString() !== content) {
+      ytext.doc.transact(() => {
+        ytext.delete(0, ytext.length);
+        if (content) ytext.insert(0, content);
+      });
+    }
+  }
+  async function writeToDisk() {
+    if (destroyed || writing) return;
+    writing = true;
+    try {
+      const content = ytext.toString();
+      await mkdir(dirname(filePath), { recursive: true });
+      await writeFile(filePath, content, 'utf-8');
+    } finally {
+      writing = false;
+    }
+  }
+  function scheduleWrite() {
+    clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      writeToDisk().catch((err) => console.error('easymd: write failed', err));
+    }, DEBOUNCE_MS);
+  }
+  const unobserve = ytext.observe(() => {
+    scheduleWrite();
+  });
+  const watcher = chokidar.watch(filePath, {
+    ignoreInitial: true,
+    awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
+  });
+  watcher.on('change', async () => {
+    if (writing || destroyed) return;
+    const disk = await readDisk();
+    if (disk !== ytext.toString()) {
+      ytext.doc.transact(() => {
+        ytext.delete(0, ytext.length);
+        if (disk) ytext.insert(0, disk);
+      });
+    }
+  });
+  watcher.on('add', loadFromDisk);
+  return {
+    loadFromDisk,
+    destroy() {
+      destroyed = true;
+      clearTimeout(debounceTimer);
+      unobserve();
+      watcher.close();
+    },
+  };
+}

package/src/server.js ADDED Viewed

@@ -0,0 +1,65 @@
+import express from 'express';
+import http from 'http';
+import { WebSocketServer } from 'ws';
+import { dirname, basename, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { getYDoc, setupWSConnection } from 'y-websocket/bin/utils';
+import { createFileSync } from './file-sync.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+/**
+ * Start a local server that binds one Yjs doc to one markdown file on disk.
+ */
+export async function startServer(filePath, options = {}) {
+  const absPath = resolve(filePath);
+  const docName = absPath;
+  const ydoc = getYDoc(docName, false);
+  const ytext = ydoc.getText('markdown');
+  const fileSync = createFileSync(absPath, ytext);
+  await fileSync.loadFromDisk();
+  const app = express();
+  app.get('/api/session', (_req, res) => {
+    res.json({
+      filePath: absPath,
+      fileName: basename(absPath),
+      docName,
+    });
+  });
+  app.use(express.static(resolve(ROOT, 'dist')));
+  app.use(express.static(resolve(ROOT, 'client')));
+  app.get('*', (_req, res) => {
+    res.sendFile(resolve(ROOT, 'client/index.html'));
+  });
+  const server = http.createServer(app);
+  const wss = new WebSocketServer({ noServer: true });
+  server.on('upgrade', (request, socket, head) => {
+    wss.handleUpgrade(request, socket, head, (ws) => {
+      setupWSConnection(ws, request, { docName, gc: false });
+    });
+  });
+  const port = await new Promise((resolvePort, reject) => {
+    server.listen(options.port ?? 0, options.host ?? '127.0.0.1', () => {
+      const addr = server.address();
+      resolvePort(typeof addr === 'object' ? addr.port : options.port);
+    });
+    server.on('error', reject);
+  });
+  const shutdown = () => {
+    fileSync.destroy();
+    wss.close();
+    server.close();
+  };
+  return { port, url: `http://127.0.0.1:${port}`, filePath: absPath, shutdown };
+}