@rarusoft/dendrite-wiki 0.1.0-alpha.0

package/src/binder-export.ts

@@ -0,0 +1,437 @@
+/**
+ * Compile-to-Binder export — R6 of the retro-editor experiment.
+ *
+ * Produces a single self-contained HTML file from selected wiki pages,
+ * styled to print well on paper: cover page with project name and
+ * timestamp, table of contents, page-break rules between sections, claim
+ * and source citations distinguished even in B/W. Open the output in a
+ * browser and File → Print → Save as PDF for the binder workflow.
+ *
+ * Driven by `dendrite-wiki binder:export [--all | --pages a,b,c]
+ * [--theme selectric|amber|wordperfect|modern] [--output path]
+ * [--title text]`. Default output: `docs/public/binder.html` (gitignored
+ * via `docs/public/*.html` patterns the operator may already have).
+ *
+ * Intentionally does NOT shell out to headless Chrome — Puppeteer adds
+ * ~150 MB to the install footprint, and the browser-as-print-engine path
+ * works on every machine without any new install. If a future R6.1 wants
+ * one-step PDF, it can layer Puppeteer on top of this HTML output.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import MarkdownIt from 'markdown-it';
+import { listWikiPages, readWikiPage } from './store.js';
+
+export type BinderTheme = 'selectric' | 'amber' | 'wordperfect' | 'modern';
+
+export interface BinderExportOptions {
+  root?: string;
+  slugs?: string[];
+  all?: boolean;
+  theme?: BinderTheme;
+  outputPath?: string;
+  title?: string;
+}
+
+export interface BinderExportResult {
+  outputPath: string;
+  pageCount: number;
+  bytesWritten: number;
+  pages: Array<{ slug: string; title: string }>;
+  theme: BinderTheme;
+}
+
+const DEFAULT_TITLE = 'Dendrite Wiki MCP — Binder';
+
+export async function exportBinderHtml(options: BinderExportOptions = {}): Promise<BinderExportResult> {
+  const root = path.resolve(options.root ?? process.cwd());
+  const outputPath = path.resolve(options.outputPath ?? path.join(root, 'docs', 'public', 'binder.html'));
+  const theme: BinderTheme = options.theme ?? 'selectric';
+  const title = options.title ?? DEFAULT_TITLE;
+
+  const allPages = await listWikiPages();
+  const allBySlug = new Map(allPages.map((p) => [p.slug, p] as const));
+
+  let selectedSlugs: string[];
+  if (options.all || !options.slugs || options.slugs.length === 0) {
+    // Default: every page except generated reference (api/*) — those
+    // are noisy in a binder and the operator can opt them in via --pages.
+    selectedSlugs = allPages
+      .filter((p) => !p.slug.startsWith('api/'))
+      .map((p) => p.slug)
+      .sort();
+  } else {
+    selectedSlugs = options.slugs;
+  }
+
+  const pages: Array<{ slug: string; title: string; html: string }> = [];
+  for (const slug of selectedSlugs) {
+    const summary = allBySlug.get(slug);
+    if (!summary) {
+      throw new Error(`Unknown wiki page slug: ${slug}`);
+    }
+    const raw = await readWikiPage(slug);
+    const stripped = stripFrontmatter(raw);
+    const html = renderMarkdown(stripped);
+    pages.push({ slug, title: summary.title, html });
+  }
+
+  const html = renderBinderHtml({ title, theme, pages });
+
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.writeFile(outputPath, html, 'utf8');
+  const stat = await fs.stat(outputPath);
+
+  return {
+    outputPath,
+    pageCount: pages.length,
+    bytesWritten: stat.size,
+    pages: pages.map(({ slug, title: t }) => ({ slug, title: t })),
+    theme
+  };
+}
+
+function stripFrontmatter(content: string): string {
+  const match = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/);
+  return match ? content.slice(match[0].length) : content;
+}
+
+function renderMarkdown(markdown: string): string {
+  const md = new MarkdownIt({
+    html: false,
+    linkify: true,
+    typographer: true,
+    breaks: false
+  });
+  return md.render(markdown);
+}
+
+interface RenderInput {
+  title: string;
+  theme: BinderTheme;
+  pages: Array<{ slug: string; title: string; html: string }>;
+}
+
+function renderBinderHtml({ title, theme, pages }: RenderInput): string {
+  const generatedAt = new Date();
+  const generatedHuman = generatedAt.toLocaleString('en-US', {
+    weekday: 'long',
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit'
+  });
+  const generatedIso = generatedAt.toISOString();
+
+  const palette = themePalette(theme);
+  const tocItems = pages
+    .map((p, idx) => `        <li><a href="#page-${idx + 1}"><span class="toc-num">${String(idx + 1).padStart(2, '0')}</span> <span class="toc-title">${escapeHtml(p.title)}</span> <span class="toc-slug">${escapeHtml(p.slug)}</span></a></li>`)
+    .join('\n');
+
+  const sections = pages
+    .map(
+      (p, idx) => `      <section class="binder-page" id="page-${idx + 1}">
+        <header class="binder-page-header">
+          <span class="binder-page-num">PAGE ${String(idx + 1).padStart(2, '0')} OF ${String(pages.length).padStart(2, '0')}</span>
+          <span class="binder-page-slug">${escapeHtml(p.slug)}.md</span>
+        </header>
+        <div class="binder-page-body">
+${p.html}
+        </div>
+      </section>`
+    )
+    .join('\n');
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>
+${binderStyles(palette)}
+</style>
+</head>
+<body data-theme="${theme}">
+  <main class="binder">
+    <section class="binder-cover">
+      <div class="binder-cover-frame">
+        <p class="binder-cover-eyebrow">Dendrite Wiki MCP</p>
+        <h1 class="binder-cover-title">${escapeHtml(title)}</h1>
+        <p class="binder-cover-meta">
+          Compiled <strong>${escapeHtml(generatedHuman)}</strong>
+          · ${pages.length} page${pages.length === 1 ? '' : 's'}
+          · theme: <em>${escapeHtml(theme)}</em>
+        </p>
+        <p class="binder-cover-iso"><code>${escapeHtml(generatedIso)}</code></p>
+      </div>
+    </section>
+
+    <section class="binder-toc">
+      <h2 class="binder-toc-title">Contents</h2>
+      <ol class="binder-toc-list">
+${tocItems}
+      </ol>
+    </section>
+
+${sections}
+
+    <footer class="binder-foot">
+      <p>Generated by <strong>Dendrite Wiki MCP</strong> · binder:export · ${escapeHtml(theme)} theme · ${escapeHtml(generatedIso)}</p>
+    </footer>
+  </main>
+</body>
+</html>
+`;
+}
+
+interface ThemePalette {
+  bg: string;
+  fg: string;
+  accent: string;
+  muted: string;
+  divider: string;
+  bgAlt: string;
+  fontBody: string;
+  fontMono: string;
+  bodyJustify: boolean;
+  uppercaseHeadings: boolean;
+}
+
+function themePalette(theme: BinderTheme): ThemePalette {
+  switch (theme) {
+    case 'amber':
+      return {
+        bg: '#150a00',
+        fg: '#ffb000',
+        accent: '#ffd166',
+        muted: '#a06900',
+        divider: '#4a2a00',
+        bgAlt: '#1f0e00',
+        fontBody: "'VT323', 'Courier New', monospace",
+        fontMono: "'VT323', 'Courier New', monospace",
+        bodyJustify: false,
+        uppercaseHeadings: true
+      };
+    case 'wordperfect':
+      return {
+        bg: '#0000aa',
+        fg: '#f0f0f0',
+        accent: '#ffff55',
+        muted: '#a0a0c0',
+        divider: '#5555cc',
+        bgAlt: '#00008b',
+        fontBody: "'IBM Plex Mono', 'Courier New', monospace",
+        fontMono: "'IBM Plex Mono', 'Courier New', monospace",
+        bodyJustify: false,
+        uppercaseHeadings: false
+      };
+    case 'modern':
+      return {
+        bg: '#ffffff',
+        fg: '#1a1a1a',
+        accent: '#1f6feb',
+        muted: '#666666',
+        divider: '#e6e6e6',
+        bgAlt: '#fafafa',
+        fontBody: "'Inter', system-ui, -apple-system, 'Segoe UI', Helvetica, Arial, sans-serif",
+        fontMono: "'JetBrains Mono', 'Consolas', monospace",
+        bodyJustify: false,
+        uppercaseHeadings: false
+      };
+    case 'selectric':
+    default:
+      return {
+        bg: '#f5f0e1',
+        fg: '#1a1410',
+        accent: '#8b1a1a',
+        muted: '#5e4f40',
+        divider: '#c4b89e',
+        bgAlt: '#ede6d2',
+        fontBody: "'Special Elite', 'Cutive Mono', 'Courier New', monospace",
+        fontMono: "'Cutive Mono', 'Courier New', monospace",
+        bodyJustify: true,
+        uppercaseHeadings: true
+      };
+  }
+}
+
+function binderStyles(p: ThemePalette): string {
+  return `
+@import url('https://fonts.googleapis.com/css2?family=VT323&family=IBM+Plex+Mono:wght@400;500;600;700&family=Special+Elite&family=Cutive+Mono&family=Inter:wght@400;500;600;700&display=swap');
+
+:root {
+  --bg: ${p.bg};
+  --fg: ${p.fg};
+  --accent: ${p.accent};
+  --muted: ${p.muted};
+  --divider: ${p.divider};
+  --bg-alt: ${p.bgAlt};
+  --font-body: ${p.fontBody};
+  --font-mono: ${p.fontMono};
+}
+
+* { box-sizing: border-box; }
+
+html, body {
+  margin: 0;
+  padding: 0;
+  background: var(--bg);
+  color: var(--fg);
+  font-family: var(--font-body);
+  line-height: 1.6;
+}
+
+.binder {
+  max-width: 7.5in;
+  margin: 0 auto;
+  padding: 0.6in 0.75in;
+}
+
+a { color: var(--accent); text-decoration: underline; text-underline-offset: 2px; }
+code { font-family: var(--font-mono); background: var(--bg-alt); padding: 0.05rem 0.3rem; border-radius: 2px; font-size: 0.92em; }
+pre { background: var(--bg-alt); border: 1px solid var(--divider); padding: 0.6rem 0.8rem; overflow-x: auto; border-radius: 3px; font-size: 0.85em; line-height: 1.5; }
+pre code { background: transparent; padding: 0; }
+blockquote { border-left: 3px solid var(--accent); margin: 1em 0; padding: 0.2em 1em; color: var(--muted); font-style: italic; }
+hr { border: none; border-top: 1px solid var(--divider); margin: 1.5em 0; }
+table { border-collapse: collapse; width: 100%; margin: 1em 0; font-size: 0.92em; }
+th, td { border: 1px solid var(--divider); padding: 0.4em 0.6em; text-align: left; }
+th { background: var(--bg-alt); }
+
+h1, h2, h3, h4, h5, h6 {
+  font-family: var(--font-body);
+  color: var(--fg);
+  ${p.uppercaseHeadings ? 'text-transform: uppercase; letter-spacing: 0.06em; font-weight: 400;' : 'font-weight: 700;'}
+}
+h1 { font-size: 1.7em; border-bottom: 2px solid var(--fg); padding-bottom: 0.3em; margin-top: 0; }
+h2 { font-size: 1.3em; border-bottom: 1px solid var(--divider); padding-bottom: 0.2em; margin-top: 1.6em; }
+h3 { font-size: 1.1em; margin-top: 1.4em; }
+
+${p.bodyJustify ? '.binder-page-body p, .binder-page-body li { text-align: justify; hyphens: auto; }' : ''}
+
+/* Cover */
+.binder-cover {
+  min-height: 9in;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  page-break-after: always;
+  border-bottom: 1px solid var(--divider);
+}
+.binder-cover-frame {
+  border: 4px double var(--fg);
+  padding: 1.4in 1.1in;
+  text-align: center;
+  max-width: 6in;
+}
+.binder-cover-eyebrow {
+  margin: 0 0 0.6em 0;
+  font-size: 0.85em;
+  letter-spacing: 0.4em;
+  text-transform: uppercase;
+  color: var(--muted);
+}
+.binder-cover-title {
+  font-size: 2.2em;
+  margin: 0 0 1em 0;
+  border: none;
+  padding: 0;
+  ${p.uppercaseHeadings ? '' : 'font-weight: 700;'}
+}
+.binder-cover-meta {
+  margin: 0.4em 0;
+  font-size: 0.95em;
+  color: var(--muted);
+}
+.binder-cover-meta strong { color: var(--fg); }
+.binder-cover-meta em { color: var(--accent); font-style: normal; }
+.binder-cover-iso {
+  margin: 1em 0 0 0;
+  font-size: 0.78em;
+  color: var(--muted);
+}
+.binder-cover-iso code { background: transparent; }
+
+/* TOC */
+.binder-toc {
+  page-break-after: always;
+  padding: 0 0 0.5in 0;
+}
+.binder-toc-title {
+  margin-top: 0;
+}
+.binder-toc-list {
+  list-style: none;
+  padding: 0;
+  margin: 1em 0;
+  font-family: var(--font-mono);
+  font-size: 0.95em;
+}
+.binder-toc-list li {
+  margin: 0.3em 0;
+  border-bottom: 1px dotted var(--divider);
+  padding: 0.2em 0;
+}
+.binder-toc-list a {
+  display: grid;
+  grid-template-columns: 2.5em 1fr auto;
+  gap: 0.5em;
+  text-decoration: none;
+  color: var(--fg);
+}
+.binder-toc-list a:hover { color: var(--accent); }
+.toc-num { color: var(--muted); }
+.toc-slug { color: var(--muted); font-size: 0.85em; }
+
+/* Pages */
+.binder-page {
+  page-break-before: always;
+  padding-top: 0.4in;
+}
+.binder-page-header {
+  display: flex;
+  justify-content: space-between;
+  font-family: var(--font-mono);
+  font-size: 0.78em;
+  letter-spacing: 0.08em;
+  color: var(--muted);
+  border-bottom: 1px solid var(--divider);
+  padding-bottom: 0.4em;
+  margin-bottom: 1em;
+}
+.binder-page-body h1 { margin-top: 0.2em; }
+.binder-page-body img { max-width: 100%; }
+
+.binder-foot {
+  margin-top: 2em;
+  padding-top: 1em;
+  border-top: 1px solid var(--divider);
+  color: var(--muted);
+  font-size: 0.78em;
+  text-align: center;
+}
+
+/* Print rules */
+@media print {
+  html, body { background: #ffffff !important; color: #000 !important; }
+  body[data-theme="amber"], body[data-theme="amber"] * { background: #ffffff !important; color: #000000 !important; }
+  body[data-theme="wordperfect"], body[data-theme="wordperfect"] * { background: #ffffff !important; color: #000000 !important; }
+  a { color: #000 !important; text-decoration: underline; }
+  pre, table { page-break-inside: avoid; }
+  h1, h2, h3 { page-break-after: avoid; }
+  .binder { padding: 0; max-width: none; }
+  .binder-cover { min-height: 95vh; }
+  .binder-page { padding-top: 0; }
+}
+`;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}

package/src/canonical-target.ts

@@ -0,0 +1,192 @@
+/**
+ * WikiCanonicalTarget — the markdown-wiki implementation of `CanonicalTarget`.
+ *
+ * Phase 4 slice B wave 3 of the Library Extraction Roadmap split this file. The
+ * `CanonicalTarget` interface itself lives in `@rarusoft/dendrite-memory` so the brain's
+ * promotion path is backend-agnostic; this file holds only the wiki-flavored
+ * implementation plus the wiki-specific defaults. The constant
+ * `DEFAULT_WIKI_PROMOTION_TARGET_SLUG` stays here (wiki-specific) and is also
+ * imported by `auto-promote.ts` and `consolidate.ts` for trust gating.
+ *
+ * The module registers `WikiCanonicalTarget` as the brain's default target at
+ * the bottom of this file via a top-level side effect, so any code path that
+ * loads the wiki tier (everything that goes through `src/server.ts` → `./store.js`
+ * → here) auto-wires the default. Tests that bypass the wiki tier and exercise
+ * brain promotion directly must either `setDefaultCanonicalTarget(...)` with a
+ * mock or `import './canonical-target.js'` for the side effect.
+ */
+import path from 'node:path';
+import { setDefaultCanonicalTarget, type CanonicalTarget, type ProjectMemoryRecord } from '@rarusoft/dendrite-memory';
+import { appendProjectLog, listWikiPages, pagePathFromSlug, readWikiPage, writeWikiPage } from './store.js';
+
+/**
+ * Default target id when the records don't suggest one and no caller-supplied id
+ * is provided. Wiki-specific.
+ */
+export const DEFAULT_WIKI_PROMOTION_TARGET_SLUG = 'architecture';
+
+/**
+ * The markdown-wiki implementation of `CanonicalTarget`. Wraps the existing
+ * `readWikiPage` / `writeWikiPage` / `appendProjectLog` plus the markdown
+ * formatting rules that used to live inline in `memory-promotion.ts`.
+ */
+export class WikiCanonicalTarget implements CanonicalTarget {
+  async readContent(targetId: string): Promise<string> {
+    return readWikiPage(targetId).catch(() => '');
+  }
+
+  async writeContent(targetId: string, content: string): Promise<void> {
+    await writeWikiPage(targetId, content);
+  }
+
+  async appendChangeLog(entry: string): Promise<void> {
+    await appendProjectLog(entry);
+  }
+
+  async listAvailableTargetIds(): Promise<string[]> {
+    const pages = await listWikiPages();
+    return pages.map((page) => page.slug);
+  }
+
+  formatTargetPath(targetId: string): string {
+    return `docs/wiki/${targetId}.md`;
+  }
+
+  resolveTitle(targetId: string, currentContent: string): string {
+    const fromContent = currentContent.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? '';
+    if (fromContent) return fromContent;
+    // Slug → Title Case fallback. Mirrors the legacy `titleFromSlug` exactly so the
+    // preview UI sees the same string before and after the Phase 2 refactor.
+    const slugTitle = targetId
+      .split('/')
+      .pop()
+      ?.split('-')
+      .map((segment) => (segment ? segment[0].toUpperCase() + segment.slice(1) : segment))
+      .join(' ');
+    return slugTitle ?? path.basename(pagePathFromSlug(targetId), '.md');
+  }
+
+  resolveTargetId(
+    records: Pick<ProjectMemoryRecord, 'relatedPages' | 'sources'>[],
+    requestedTargetId?: string
+  ): string {
+    const requested = requestedTargetId?.trim();
+    if (requested) {
+      return requested;
+    }
+
+    // Rank candidate target slugs by how many records mention them in relatedPages.
+    // Ties broken alphabetically for deterministic output. Mirrors the legacy
+    // `resolvePromotionTargetSlug` exactly.
+    const relatedPageCounts = new Map<string, number>();
+    for (const record of records) {
+      for (const page of record.relatedPages) {
+        relatedPageCounts.set(page, (relatedPageCounts.get(page) ?? 0) + 1);
+      }
+    }
+    const rankedRelatedPage = [...relatedPageCounts.entries()].sort(
+      (left, right) => right[1] - left[1] || left[0].localeCompare(right[0])
+    )[0]?.[0];
+    if (rankedRelatedPage) {
+      return rankedRelatedPage;
+    }
+
+    // Second-choice fallback: the first wiki-kinded source slug across all records.
+    const wikiSource = records
+      .flatMap((record) => record.sources)
+      .find((source) => source.kind === 'wiki')?.slug;
+    if (wikiSource) {
+      return wikiSource;
+    }
+
+    // Default to 'architecture' rather than 'project-log' — the project log is for
+    // chronological change history, not durable lessons. Architecture is the
+    // seeded canonical page in every dendrite-wiki project and is the right
+    // fallback for general project facts. The operator can always override by
+    // passing requestedTargetId explicitly.
+    return DEFAULT_WIKI_PROMOTION_TARGET_SLUG;
+  }
+
+  resolveSectionHeading(records: ProjectMemoryRecord[]): string {
+    const kinds = new Set(records.map((record) => record.kind));
+    if (kinds.size === 1 && kinds.has('warning')) {
+      return '## Promoted Warnings';
+    }
+    if (kinds.size === 1 && kinds.has('handoff')) {
+      return '## Promoted Handoff Notes';
+    }
+    return '## Promoted Lessons';
+  }
+
+  formatPromotionBlock(sectionHeading: string, records: ProjectMemoryRecord[]): string {
+    const lines = [sectionHeading, ''];
+    for (const record of records) {
+      const provenance = this.buildProvenanceLine(record);
+      lines.push(`- ${escapeMarkdownForVue(record.text)}`);
+      if (provenance) {
+        lines.push(`  - ${provenance}`);
+      }
+    }
+    return `${lines.join('\n')}\n`;
+  }
+
+  composeNewContent(existingContent: string, proposedText: string, fallbackTitle: string): string {
+    if (existingContent === '') {
+      return `# ${fallbackTitle}\n\n${proposedText.trim()}\n`;
+    }
+    const trimmed = existingContent.replace(/\s+$/g, '');
+    return `${trimmed}\n\n${proposedText.trim()}\n`;
+  }
+
+  isPromotionAlreadyApplied(existingContent: string, proposedText: string): boolean {
+    return existingContent.includes(proposedText.trim());
+  }
+
+  anchorForHeading(heading: string): string {
+    return heading
+      .replace(/^#+\s*/, '')
+      .toLowerCase()
+      .replace(/[^a-z0-9\s-]/g, '')
+      .trim()
+      .replace(/\s+/g, '-');
+  }
+
+  // ─── Wiki-specific internals ──────────────────────────────────────────────
+
+  private buildProvenanceLine(record: ProjectMemoryRecord): string {
+    const segments: string[] = [`kind: ${record.kind}`];
+    if (record.recallCount > 0) {
+      segments.push(`recalled ${record.recallCount}x`);
+    }
+    if (record.sources.length > 0) {
+      segments.push(`Sources: ${record.sources.map((source) => `${source.kind}:${source.slug}`).join(', ')}`);
+    } else {
+      segments.push('Sources: none');
+    }
+    return `_Provenance: ${segments.join(' · ')}_`;
+  }
+}
+
+/**
+ * Factory: build a WikiCanonicalTarget. Mirrors the `createFilesystemMemoryStorage`
+ * pattern from Phase 1 so call sites in `memory-promotion.ts`, `auto-promote.ts`,
+ * and `consolidate.ts` look uniform.
+ */
+export function createWikiCanonicalTarget(): CanonicalTarget {
+  return new WikiCanonicalTarget();
+}
+
+// VitePress parses every markdown page as a Vue SFC, so any literal `<word>` substring
+// (e.g. `.github/agents/<name>.agent.md` from a memory body) trips the Vue tag parser
+// with "Element is missing end tag" and breaks docs:build. Centralized here as a
+// module-level helper rather than a method because the same rule applies to anything
+// the wiki adapter emits into a VitePress-rendered page.
+function escapeMarkdownForVue(value: string): string {
+  return value.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+// Slice B wave 3: register WikiCanonicalTarget as the brain's default at module
+// load. Any code path that imports this file (or any wiki-side module that
+// transitively imports it) auto-wires the DI surface so brain promotion functions
+// resolve to the wiki adapter.
+setDefaultCanonicalTarget(createWikiCanonicalTarget());