markshift 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# markshift
+
+Smart format router and transformer for AI context files.
+
+Converts between Markdown, HTML, and plain text based on *where the content is going*:
+- Human-facing deliverables → HTML
+- Agent loops and git-bound files → Markdown
+- Terminal output → plain text
+
+Includes a token audit command and a watch mode.
+
+## Install
+
+```bash
+npm install -g markshift
+```
+
+## Commands
+
+```bash
+markshift route <file>                   # Auto-detect context type and transform
+markshift to-html <file>                 # Markdown → HTML
+markshift to-html --optimize-tokens <file>  # Markdown → HTML (token-optimized)
+markshift to-md <file>                   # HTML → Markdown
+markshift to-text <file>                 # HTML/MD → plain text
+markshift audit <file>                   # Token count comparison across formats
+markshift watch <dir>                    # Watch directory, auto-route on save
+```
+
+## Token Audit Example
+
+```
+$ markshift audit context.md
+
+┌─────────────────┬────────────┬──────────┐
+│ Format          │ Tokens     │ Delta    │
+├─────────────────┼────────────┼──────────┤
+│ Original        │ 1,240      │ —        │
+│ → HTML          │ 1,890      │ +650     │
+│ → HTML (opt)    │ 1,420      │ +180     │
+│ → Markdown      │   980      │ -260     │
+│ → Plain text    │   740      │ -500     │
+└─────────────────┴────────────┴──────────┘
+```
+
+## License
+
+MIT

package/bin/markshift.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+// CLI entry point — wires commander.js commands to src/ handlers
+// Each command imports its handler lazily to keep startup fast
+
+import { program } from 'commander';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+
+program
+  .name('markshift')
+  .description('Smart format router and transformer for AI context files')
+  .version(pkg.version);
+
+// markshift route <file>
+// Auto-detect context type (human/agent/terminal) and transform accordingly
+program
+  .command('route <path>')
+  .description('Auto-detect context type and transform to best format. Accepts file or directory.')
+  .option('--recursive', 'Process all files in directory recursively')
+  .action(async (target, opts) => {
+    const { stat } = await import('node:fs/promises');
+    const { route, routeDir } = await import('../src/router.js');
+    let info;
+    try {
+      info = await stat(target);
+    } catch (err) {
+      process.stderr.write(`[markshift] error: ${target}: ${err.message}\n`);
+      process.exit(1);
+    }
+    if (info.isDirectory()) {
+      await routeDir(target, opts);
+    } else {
+      await route(target);
+    }
+  });
+
+// markshift to-html <file>
+// Convert Markdown → structured HTML
+// --optimize-tokens: strip redundant markup, extract inline CSS
+program
+  .command('to-html <file>')
+  .description('Convert Markdown to structured HTML')
+  .option('--optimize-tokens', 'Strip redundant markup to reduce token count')
+  .action(async (file, opts) => {
+    const { toHtml } = await import('../src/transforms/toHtml.js');
+    await toHtml(file, opts);
+  });
+
+// markshift to-md <file>
+// Convert HTML → clean Markdown
+program
+  .command('to-md <file>')
+  .description('Convert HTML to clean Markdown')
+  .action(async (file) => {
+    const { toMd } = await import('../src/transforms/toMd.js');
+    await toMd(file);
+  });
+
+// markshift to-text <file>
+// Convert HTML or Markdown → terminal-safe plain text (strips all markup)
+program
+  .command('to-text <file>')
+  .description('Convert HTML/MD to terminal-safe plain text')
+  .action(async (file) => {
+    const { toText } = await import('../src/transforms/toText.js');
+    await toText(file);
+  });
+
+// markshift audit <file>
+// Compare token counts: original vs each possible transform output
+program
+  .command('audit <file>')
+  .description('Compare token counts before and after each transform')
+  .action(async (file) => {
+    const { audit } = await import('../src/audit.js');
+    await audit(file);
+  });
+
+// markshift watch <dir>
+// Watch directory for file saves and auto-route each changed file
+program
+  .command('watch <dir>')
+  .description('Watch directory and auto-route files on save')
+  .option('--ext <extensions>', 'Comma-separated file extensions to watch', 'md,html')
+  .action(async (dir, opts) => {
+    const { watch } = await import('../src/watcher.js');
+    await watch(dir, opts);
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "markshift",
+  "version": "0.1.0",
+  "description": "Smart format router and transformer for AI context files",
+  "bin": {
+    "markshift": "bin/markshift.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test tests/transforms/toHtml.test.js tests/transforms/toMd.test.js tests/transforms/toText.test.js tests/optimizer.test.js tests/audit.test.js tests/router.test.js",
+    "audit:braindump": "node -e \"import('./src/audit.js').then(m => m.audit('project-braindump.html'))\"",
+    "audit:claude": "node -e \"import('./src/audit.js').then(m => m.audit('CLAUDE.md'))\"",
+    "start": "node bin/markshift.js"
+  },
+  "keywords": [
+    "markdown",
+    "html",
+    "cli",
+    "ai",
+    "token",
+    "transform",
+    "router"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "chokidar": "^3.6.0",
+    "commander": "^12.0.0",
+    "marked": "^12.0.0",
+    "tiktoken": "^1.0.15",
+    "turndown": "^7.2.0"
+  }
+}

package/src/audit.js

@@ -0,0 +1,119 @@
+// Token audit — compare token counts across transform outputs
+//
+// Uses `tiktoken` with the cl100k_base encoding (GPT-4 / Claude compatible).
+//
+// For a given input file, reports:
+//   ┌─────────────────────┬─────────┬─────────┐
+//   │ Format              │  Tokens │   Delta │
+//   ├─────────────────────┼─────────┼─────────┤
+//   │ Original            │   1,240 │      —  │
+//   │ → HTML              │   1,890 │  +650   │
+//   │ → HTML (optimized)  │   1,420 │  +180   │
+//   │ → Markdown          │     980 │  -260   │
+//   │ → Plain text        │     740 │  -500   │
+//   └─────────────────────┴─────────┴─────────┘
+//
+// Exit code 0 always — audit is informational only.
+
+import { extname } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { get_encoding } from 'tiktoken';
+import { htmlFromMd } from './transforms/toHtml.js';
+import { mdFromHtml } from './transforms/toMd.js';
+import { textFrom } from './transforms/toText.js';
+import { optimizeHtml } from './optimizer.js';
+
+let _enc = null;
+function getEncoder() {
+  if (!_enc) _enc = get_encoding('cl100k_base');
+  return _enc;
+}
+
+/**
+ * Count tokens in a string using cl100k_base encoding (GPT-4 / Claude compatible).
+ * @param {string} text
+ * @returns {number}
+ */
+export function countTokens(text) {
+  if (!text) return 0;
+  return getEncoder().encode(text).length;
+}
+
+function fmt(n) {
+  return String(n).padStart(7);
+}
+
+function delta(base, n) {
+  const d = n - base;
+  if (d === 0) return '    —  ';
+  const sign = d > 0 ? '+' : '';
+  return `${sign}${d}`.padStart(7);
+}
+
+/**
+ * Run token audit on a file and print comparison table to stdout.
+ * @param {string} filePath
+ */
+export async function audit(filePath) {
+  let content;
+  try {
+    content = await readFile(filePath, 'utf8');
+  } catch (err) {
+    process.stderr.write(`[markshift] error: ${err.message}\n`);
+    process.exit(1);
+  }
+  const ext = extname(filePath).toLowerCase();
+
+  const isMd = ext === '.md' || ext === '.markdown';
+  const isHtml = ext === '.html' || ext === '.htm';
+
+  const originalTokens = countTokens(content);
+  const rows = [{ label: 'Original', tokens: originalTokens }];
+
+  if (!isMd && !isHtml) {
+    console.warn(`[markshift] audit: unsupported extension "${ext}" — showing token count only (no transforms run).`);
+  }
+
+  if (isMd) {
+    const html = htmlFromMd(content);
+    const htmlOpt = htmlFromMd(content, { optimizeTokens: true });
+    const txt = textFrom(content, ext);
+    rows.push(
+      { label: '→ HTML', tokens: countTokens(html) },
+      { label: '→ HTML (optimized)', tokens: countTokens(htmlOpt) },
+      { label: '→ Plain text', tokens: countTokens(txt) },
+    );
+  } else if (isHtml) {
+    const htmlOpt = optimizeHtml(content);
+    const md = mdFromHtml(content);
+    const txt = textFrom(content, ext);
+    rows.push(
+      { label: '→ HTML (optimized)', tokens: countTokens(htmlOpt) },
+      { label: '→ Markdown', tokens: countTokens(md) },
+      { label: '→ Plain text', tokens: countTokens(txt) },
+    );
+  }
+
+  const base = rows[0].tokens;
+  const labelW = 21;
+
+  const top  = `┌${'─'.repeat(labelW)}┬${'─'.repeat(9)}┬${'─'.repeat(9)}┐`;
+  const sep  = `├${'─'.repeat(labelW)}┼${'─'.repeat(9)}┼${'─'.repeat(9)}┤`;
+  const bot  = `└${'─'.repeat(labelW)}┴${'─'.repeat(9)}┴${'─'.repeat(9)}┘`;
+  const head = `│ ${'Format'.padEnd(labelW - 2)} │ ${'Tokens'.padStart(7)} │ ${'Delta'.padStart(7)} │`;
+
+  const lines = [
+    `\nToken audit: ${filePath}\n`,
+    top, head, sep,
+  ];
+
+  for (const row of rows) {
+    const label = row.label.padEnd(labelW - 2);
+    const tok = fmt(row.tokens);
+    const d = row === rows[0] ? '    —  ' : delta(base, row.tokens);
+    lines.push(`│ ${label} │ ${tok} │ ${d} │`);
+  }
+
+  lines.push(bot, '');
+  console.log(lines.join('\n'));
+}

package/src/optimizer.js

@@ -0,0 +1,110 @@
+/**
+ * Token optimizer for HTML output.
+ *
+ * Goal: reduce token count of HTML without changing rendered output.
+ *
+ * Techniques (in pipeline order):
+ *   1. Strip HTML comments
+ *   2. Strip <script>/<style> block content (agent context never needs them)
+ *   3. Collapse inter-tag whitespace (non-pre contexts)
+ *   4. Extract repeated inline styles (3+ occurrences) to <style> block
+ *
+ * Known limitation: collapseWhitespace uses regex and does not distinguish
+ * <pre> from non-<pre> contexts. Whitespace inside <pre> blocks may be
+ * incorrectly collapsed. YAGNI for now — markshift context files rarely
+ * contain pre-formatted whitespace-sensitive content.
+ */
+
+/**
+ * Full optimization pipeline. Runs all techniques in order.
+ * @param {string} html
+ * @returns {string}
+ */
+export function optimizeHtml(html) {
+  let result = removeComments(html);
+  result = stripScriptStyle(result);
+  result = collapseWhitespace(result);
+  result = extractInlineStyles(result);
+  return result;
+}
+
+function removeComments(html) {
+  return html.replace(/<!--[\s\S]*?-->/g, '');
+}
+
+function stripScriptStyle(html) {
+  return html
+    .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+    .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '');
+}
+
+function collapseWhitespace(html) {
+  // Normalize CRLF → LF first so regex patterns work on Windows
+  const normalized = html.replace(/\r\n/g, '\n');
+  return normalized
+    .replace(/>[ \t]*\n[ \t]*/g, '>')
+    .replace(/\n[ \t]*</g, '<')
+    .replace(/[ \t]{2,}/g, ' ');
+}
+
+/**
+ * Extract repeated inline styles (3+ occurrences) into a <style> block.
+ * Injects the <style> block before the first tag if no <head>, or inside <head>.
+ * @param {string} html
+ * @returns {string}
+ */
+export function extractInlineStyles(html) {
+  const styleAttrPattern = / style="([^"]+)"/g;
+  const freq = new Map();
+  let match;
+
+  // Count frequency of each style declaration
+  while ((match = styleAttrPattern.exec(html)) !== null) {
+    const val = match[1];
+    freq.set(val, (freq.get(val) ?? 0) + 1);
+  }
+
+  // Only extract styles appearing 3+ times
+  const toExtract = new Map();
+  let classIndex = 0;
+  for (const [style, count] of freq) {
+    if (count >= 3) {
+      toExtract.set(style, `ms${classIndex++}`);
+    }
+  }
+
+  if (toExtract.size === 0) return html;
+
+  // NOTE: assumes ms0..msN class names are not already in use in this HTML.
+  // Build <style> block
+  const rules = [...toExtract.entries()]
+    .map(([style, cls]) => `.${cls}{${style}}`)
+    .join('');
+  const styleBlock = `<style>${rules}</style>`;
+
+  // Replace extracted inline styles with class references.
+  // Two-pass: first append to existing class attrs, then add new ones.
+  let result = html;
+  for (const [style, cls] of toExtract) {
+    const escaped = style.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // Pass 1: element already has a class attr — append to it
+    result = result.replace(
+      new RegExp(`(class="[^"]*")([^>]*) style="${escaped}"`, 'g'),
+      (_, classAttr, between) => `${classAttr.slice(0, -1)} ${cls}"${between}`
+    );
+    // Pass 2: element has no class attr yet — add one
+    result = result.replace(
+      new RegExp(` style="${escaped}"`, 'g'),
+      ` class="${cls}"`
+    );
+  }
+
+  // Inject <style> block
+  if (result.includes('</head>')) {
+    result = result.replace('</head>', `${styleBlock}</head>`);
+  } else {
+    result = styleBlock + result;
+  }
+
+  return result;
+}

package/src/router.js

@@ -0,0 +1,133 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { basename, extname, join } from 'node:path';
+import { htmlFromMd } from './transforms/toHtml.js';
+import { mdFromHtml } from './transforms/toMd.js';
+
+// Agent-loop filenames — always stay as MD
+const AGENT_NAMES = new Set([
+  'claude.md', 'agents.md', 'skill.md', 'gemini.md',
+  'readme.md', 'changelog.md', 'contributing.md',
+  'license.md', 'security.md', 'codeowners',
+]);
+
+// Path segments that signal agent context
+const AGENT_PATHS = ['.claude/', 'prompts/', 'context/', 'skills/'];
+
+// Path segments that signal human-facing context.
+// Matched as bare substrings after normalization — paths containing these
+// segments anywhere (e.g. node_modules/some-docs/) will match. Known limitation.
+const HUMAN_PATHS = ['deliverables/', 'docs/', 'reports/', 'output/', 'dist/'];
+
+/**
+ * Detect the context type of a file.
+ * Returns 'human' (→ HTML) or 'agent' (→ MD).
+ * Terminal/plain-text output is handled by the explicit `to-text` command,
+ * not by auto-detection (runtime context, not a file property).
+ * Pure function — no file I/O, no side effects.
+ * @param {string} filePath
+ * @param {string} content
+ * @returns {'human'|'agent'}
+ */
+export function detectContextType(filePath, content) {
+  content = content ?? '';
+  const name = basename(filePath).toLowerCase();
+  const normalized = filePath.replace(/\\/g, '/').toLowerCase();
+  const ext = extname(filePath).toLowerCase();
+
+  // Agent-loop filenames
+  if (AGENT_NAMES.has(name)) return 'agent';
+
+  // Agent path signals
+  if (AGENT_PATHS.some(p => normalized.includes(p))) return 'agent';
+
+  // HTML extension → human-facing by definition
+  if (ext === '.html' || ext === '.htm') return 'human';
+
+  // Human-facing path signals
+  if (HUMAN_PATHS.some(p => normalized.includes(p))) return 'human';
+
+  // Content signal: MD file containing HTML tags → human-facing
+  if ((ext === '.md' || ext === '.markdown') && /<[a-z][^>]*>/i.test(content)) {
+    return 'human';
+  }
+
+  // Default: MD stays as MD (agent context)
+  return 'agent';
+}
+
+/**
+ * Detect context type for a file and transform it to the best format.
+ * Prints the result to stdout.
+ * @param {string} filePath
+ */
+export async function route(filePath) {
+  let content;
+  try {
+    content = await readFile(filePath, 'utf8');
+  } catch (err) {
+    process.stderr.write(`[markshift] error: ${err.message}\n`);
+    process.exit(1);
+  }
+  const ext = extname(filePath).toLowerCase();
+
+  const supportedExts = new Set(['.md', '.markdown', '.html', '.htm']);
+  if (!supportedExts.has(ext)) {
+    process.stderr.write(`[markshift] route: unsupported file type "${ext}", skipping ${filePath}\n`);
+    return;
+  }
+
+  const contextType = detectContextType(filePath, content);
+
+  if (contextType === 'human') {
+    // HTML input stays HTML; MD input converts to HTML
+    const html = (ext === '.html' || ext === '.htm')
+      ? content
+      : htmlFromMd(content);
+    process.stdout.write(html);
+    return;
+  }
+
+  // agent → MD
+  const md = (ext === '.md' || ext === '.markdown')
+    ? content
+    : mdFromHtml(content);
+  process.stdout.write(md + '\n');
+}
+
+/**
+ * Route all matching files in a directory.
+ * @param {string} dir
+ * @param {{ recursive?: boolean }} opts
+ */
+export async function routeDir(dir, opts = {}) {
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch (err) {
+    process.stderr.write(`[markshift] error reading directory ${dir}: ${err.message}\n`);
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.startsWith('.') || entry === 'node_modules') continue;
+    const fullPath = join(dir, entry);
+    let info;
+    try {
+      info = await stat(fullPath);
+    } catch (err) {
+      process.stderr.write(`[markshift] error: ${err.message}\n`);
+      continue;
+    }
+    if (info.isDirectory()) {
+      if (opts.recursive) await routeDir(fullPath, opts);
+      continue;
+    }
+    const ext = extname(entry).toLowerCase();
+    if (ext === '.md' || ext === '.markdown' || ext === '.html' || ext === '.htm') {
+      try {
+        await route(fullPath);
+      } catch (err) {
+        process.stderr.write(`[markshift] error routing ${fullPath}: ${err.message}\n`);
+      }
+    }
+  }
+}

package/src/transforms/toHtml.js

@@ -0,0 +1,42 @@
+// Markdown → structured HTML transform
+//
+// --optimize-tokens mode:
+//   - Strips HTML comments and script/style blocks
+//   - Collapses inter-tag whitespace
+//   - Extracts repeated inline styles into a <style> block
+//
+// Output written to stdout by default.
+
+import { readFile } from 'node:fs/promises';
+import { marked } from 'marked';
+import { optimizeHtml } from '../optimizer.js';
+
+/**
+ * Pure transform: Markdown string → HTML string.
+ * Returns fragment HTML (no <!DOCTYPE>), suitable for agent context.
+ * @param {string} content
+ * @param {{ optimizeTokens?: boolean }} opts
+ * @returns {string}
+ */
+export function htmlFromMd(content, opts = {}) {
+  let html = marked(content);
+  if (opts.optimizeTokens) html = optimizeHtml(html);
+  return html;
+}
+
+/**
+ * CLI wrapper: reads filePath, transforms, writes to stdout.
+ * process.stdout.write — no trailing newline (HTML fragment output for piping).
+ * @param {string} filePath
+ * @param {{ optimizeTokens?: boolean }} opts
+ */
+export async function toHtml(filePath, opts = {}) {
+  let content;
+  try {
+    content = await readFile(filePath, 'utf8');
+  } catch (err) {
+    process.stderr.write(`[markshift] error: ${err.message}\n`);
+    process.exit(1);
+  }
+  process.stdout.write(htmlFromMd(content, opts));
+}

package/src/transforms/toMd.js

@@ -0,0 +1,52 @@
+// HTML → clean Markdown transform
+//
+// Uses `turndown` with these options:
+//   - headingStyle: 'atx'         (# H1, ## H2, ...)
+//   - codeBlockStyle: 'fenced'    (``` fences)
+//   - bulletListMarker: '-'
+//
+// Post-processing:
+//   - Collapse 3+ blank lines → 2
+//   - Trim trailing whitespace per line
+//   - Strip HTML comments
+//
+// Output written to stdout.
+
+import { readFile } from 'node:fs/promises';
+import TurndownService from 'turndown';
+
+const td = new TurndownService({
+  headingStyle: 'atx',
+  codeBlockStyle: 'fenced',
+  bulletListMarker: '-',
+});
+
+/**
+ * Pure transform: HTML string → clean Markdown string.
+ * @param {string} html
+ * @returns {string}
+ */
+export function mdFromHtml(html) {
+  // Strip HTML comments before turndown sees them
+  const stripped = html.replace(/<!--[\s\S]*?-->/g, '');
+  let md = td.turndown(stripped);
+  // Collapse 3+ blank lines → 2, trim trailing whitespace per line
+  md = md.replace(/\n{3,}/g, '\n\n').replace(/[ \t]+$/gm, '');
+  return md;
+}
+
+/**
+ * CLI wrapper: reads filePath, transforms, writes to stdout.
+ * process.stdout.write — no trailing newline for piped output.
+ * @param {string} filePath
+ */
+export async function toMd(filePath) {
+  let content;
+  try {
+    content = await readFile(filePath, 'utf8');
+  } catch (err) {
+    process.stderr.write(`[markshift] error: ${err.message}\n`);
+    process.exit(1);
+  }
+  process.stdout.write(mdFromHtml(content) + '\n');
+}

package/src/transforms/toText.js

@@ -0,0 +1,97 @@
+import { readFile } from 'node:fs/promises';
+import { extname } from 'node:path';
+import { marked } from 'marked';
+
+const ENTITIES = {
+  '&': '&',
+  '&lt;': '<',
+  '&gt;': '>',
+  '&quot;': '"',
+  '&#39;': "'",
+  '&nbsp;': ' ',
+};
+
+/**
+ * Decode HTML entities to their character equivalents.
+ * @param {string} str
+ * @returns {string}
+ */
+function decodeEntities(str) {
+  return str.replace(/&[a-z#0-9]+;/gi, e => ENTITIES[e] ?? e);
+}
+
+/**
+ * Word-wrap text to specified column width.
+ * Force-breaks words that exceed width.
+ * @param {string} text
+ * @param {number} width
+ * @returns {string}
+ */
+function wordWrap(text, width = 80) {
+  return text.split('\n').map(line => {
+    if (line.length <= width) return line;
+    const words = line.split(' ');
+    const out = [];
+    let cur = '';
+    for (const word of words) {
+      // Force-break words that exceed width on their own
+      const chunks = word.match(new RegExp(`.{1,${width}}`, 'g')) ?? [word];
+      for (const chunk of chunks) {
+        const next = cur ? `${cur} ${chunk}` : chunk;
+        if (next.length > width) { if (cur) out.push(cur); cur = chunk; }
+        else cur = next;
+      }
+    }
+    if (cur) out.push(cur);
+    return out.join('\n');
+  }).join('\n');
+}
+
+/**
+ * Pure transform: HTML or Markdown string → terminal-safe plain text.
+ * Strips tags, decodes entities, normalizes whitespace, wraps to 80 columns.
+ * @param {string} content
+ * @param {string} ext  File extension including dot, e.g. '.md' or '.html'
+ * @returns {string}
+ */
+export function textFrom(content, ext) {
+  let html = content;
+
+  // Convert Markdown to HTML if needed
+  if (ext === '.md' || ext === '.markdown') {
+    html = marked(content);
+  }
+
+  // Strip script/style blocks (content would otherwise appear as plain text)
+  html = html.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, ' ');
+  html = html.replace(/<style[^>]*>[\s\S]*?<\/style>/gi, ' ');
+
+  // Strip HTML tags
+  let text = html.replace(/<[^>]+>/gs, ' ');
+
+  // Decode HTML entities
+  text = decodeEntities(text);
+
+  // Normalize whitespace: collapse runs, trim lines, collapse excessive newlines
+  text = text.replace(/[ \t]+/g, ' ').replace(/\n{3,}/g, '\n\n').trim();
+
+  // Word-wrap to 80 columns
+  return wordWrap(text);
+}
+
+/**
+ * CLI wrapper: reads filePath, transforms, writes to stdout.
+ * process.stdout.write with trailing newline (POSIX convention for text output).
+ * @param {string} filePath
+ */
+export async function toText(filePath) {
+  let content;
+  try {
+    content = await readFile(filePath, 'utf8');
+  } catch (err) {
+    process.stderr.write(`[markshift] error: ${err.message}\n`);
+    process.exit(1);
+  }
+  const ext = extname(filePath).toLowerCase();
+  process.stdout.write(textFrom(content, ext) + '\n');
+}

package/src/watcher.js

@@ -0,0 +1,60 @@
+// Directory watcher — auto-routes files on save
+//
+// Uses `chokidar` (cross-platform fs watch with debounce).
+//
+// Behavior:
+//   - Watches *.md and *.html files in the target directory (recursive)
+//   - On change: calls router.route(filePath)
+//   - Debounce: 300ms (avoid double-fire on editor atomic saves)
+//   - Prints a log line per event: [HH:MM:SS] routed path/to/file
+//   - Ignores: node_modules, .git, hidden files
+//
+// Runs until SIGINT (Ctrl+C).
+
+import chokidar from 'chokidar';
+import { route } from './router.js';
+
+/**
+ * Watch a directory and auto-route files on save.
+ * Logs events to stderr (not stdout) so transform output stays clean for piping.
+ * @param {string} dir
+ * @param {{ ext?: string }} opts  ext = comma-separated extensions, e.g. 'md,html'
+ */
+export async function watch(dir, opts = {}) {
+  const extensions = opts.ext
+    ? opts.ext.split(',').map(e => e.trim().replace(/^\./, ''))
+    : ['md', 'html'];
+
+  const normalizedDir = dir.replace(/\\/g, '/');
+  const patterns = extensions.map(e => `${normalizedDir}/**/*.${e}`);
+
+  const watcher = chokidar.watch(patterns, {
+    ignored: [/node_modules/, /\.git/, /(^|[/\\])\../],
+    persistent: true,
+    ignoreInitial: true,
+  });
+
+  const debounceMap = new Map();
+
+  watcher.on('change', (filePath) => {
+    if (debounceMap.has(filePath)) clearTimeout(debounceMap.get(filePath));
+    debounceMap.set(filePath, setTimeout(async () => {
+      debounceMap.delete(filePath);
+      const time = new Date().toTimeString().slice(0, 8);
+      try {
+        await route(filePath);
+        process.stderr.write(`[${time}] routed ${filePath}\n`);
+      } catch (err) {
+        process.stderr.write(`[${time}] error ${filePath} — ${err.message}\n`);
+      }
+    }, 300));
+  });
+
+  process.once('SIGINT', () => {
+    for (const id of debounceMap.values()) clearTimeout(id);
+    debounceMap.clear();
+    watcher.close().then(() => process.exit(0));
+  });
+
+  process.stderr.write(`watching ${normalizedDir} for ${extensions.map(e => `*.${e}`).join(', ')} changes...\n`);
+}