@abraca/convert 2.11.0 → 2.14.0

package/dist/index.d.ts

@@ -60,6 +60,9 @@ interface DocPageMeta extends Record<string, unknown> {
   spModelDocId?: string;
   slidesTransition?: 'none' | 'fade' | 'slide';
   slidesTheme?: 'dark' | 'light';
+  language?: string;
+  fileExtension?: string;
+  codeTheme?: string;
   __schemaVersion?: number;
 }
 //#endregion
@@ -118,6 +121,49 @@ declare function populateYDocFromHtml(fragment: Y.XmlFragment, html: string, fal
  */
 declare function appendHtmlToFragment(fragment: Y.XmlFragment, html: string): void;
 //#endregion
+//#region packages/convert/src/code.d.ts
+/** Y.Text key holding a code document's content. */
+declare const CODE_TEXT_KEY = "code";
+/** Read a code document's raw text. Empty string when absent. */
+declare function readCodeText(doc: Y.Doc): string;
+/**
+ * Replace a code document's full text in a single transaction. `origin`
+ * is forwarded to `transact` so callers (e.g. fs-sync) can tag the write
+ * and skip their own observers.
+ */
+declare function writeCodeText(doc: Y.Doc, content: string, origin?: unknown): void;
+/** Normalize an extension: strip leading dot(s), lowercase. */
+declare function normalizeExtension(ext: string): string;
+/**
+ * Whether a file extension should import as a `code` page type. Note
+ * `md`/`markdown` are intentionally NOT code extensions here — fs-sync
+ * treats `.md` as the prose/envelope format, so it's excluded from the
+ * code-import gate even though it has a language mapping for in-editor use.
+ */
+declare function isCodeExtension(ext: string): boolean;
+/** CodeMirror language id for an extension, or undefined when unknown. */
+declare function extToLanguage(ext: string): string | undefined;
+/** Preferred on-disk extension (no dot) for a language, or undefined. */
+declare function languageToExtension(language: string): string | undefined;
+/**
+ * Derive `{ language, fileExtension }` from a filename for code import.
+ * Returns undefined when the extension is not a recognized code extension
+ * (so callers fall back to the prose/doc path).
+ */
+declare function inferCodeMetaFromFilename(filename: string): {
+  language: string;
+  fileExtension: string;
+} | undefined;
+/**
+ * Choose the on-disk extension for a code doc on export. Prefers an
+ * explicit `fileExtension`, then the language's primary extension, then
+ * `txt`.
+ */
+declare function codeFileExtension(meta?: {
+  fileExtension?: string;
+  language?: string;
+}): string;
+//#endregion
 //#region packages/convert/src/diff.d.ts
 type JsonAttr = string | number | boolean | null | JsonAttr[] | {
   [key: string]: JsonAttr;
@@ -277,6 +323,8 @@ interface ManifestEntry {
   contentHash: string;
   lastWrittenAt: number;
   lastReadAt: number;
+  codePath?: string;
+  codeHash?: string;
   uploads: UploadManifestEntry[];
 }
 interface FsSyncManifest {
@@ -329,6 +377,13 @@ declare function hasChildren(docId: string, treeData: Record<string, FsTreeEntry
  * - Collision resolution via ~XXXX suffix
  */
 declare function buildRelativePath(docId: string, treeData: Record<string, FsTreeEntry>, manifest: FsSyncManifest): string;
+/**
+ * Companion code-file path for a `code` doc, derived from its `.md`
+ * envelope path by swapping the extension. e.g.
+ * `src/main.md` + `rs` -> `src/main.rs`. A code doc never has children,
+ * so the `_index.md` form is not expected here, but is handled defensively.
+ */
+declare function codeCompanionPath(mdRelativePath: string, fileExtension: string): string;
 /**
  * Get the directory portion of a relative path for a doc.
  * For _index.md docs: returns the directory containing _index.md
@@ -353,4 +408,4 @@ declare function getTreeData(treeMap: any): Record<string, FsTreeEntry>;
  */
 declare function nextOrder(treeData: Record<string, FsTreeEntry>, parentId: string | null): number;
 //#endregion
-export { type DocPageMeta, type FrontmatterResult, type FsAdapter, type FsSyncManifest, type FsTreeEntry, type JsonAttr, MARK_SPECS, MARK_SPEC_BY_DELIM, MARK_SPEC_BY_NAME, type ManifestEntry, type MarkAttrSpec, type MarkSpec, type MarkWireKind, type MetaValueType, NODE_SPECS, NODE_SPEC_BY_NAME, type NodeAttrSpec, type NodeSpec, type NodeWireKind, UNIVERSAL_META_KEYS, UNIVERSAL_META_KEY_NAMES, type UniversalMetaKey, type UploadManifestEntry, type YjsDiff, type YjsJsonElement, type YjsJsonNode, type YjsJsonText, type YjsTextRun, appendHtmlToFragment, buildAliasMap, buildRelativePath, buildReverseLookup, conflictsDir, createEmptyManifest, diffJson, diffYjs, filenameToLabel, fsFilenameToLabel, getDocDir, getFsAdapter, getTreeData, hasChildren, jsonToYFragment, labelToFilename, loadManifest, lookupByDocId, lookupByHash, lookupByPath, manifestDir, mdcTagOf, nextOrder, orphansDir, parseFrontmatter, populateYDocFromHtml, populateYDocFromMarkdown, removeEntry, resolveParentFromPath, saveManifest, setEntry, setFsAdapter, simpleHash, stringifyJsonNode, trashDir, yfragmentToJson, yjsToHtml, yjsToMarkdown, yjsToPlainText };
+export { CODE_TEXT_KEY, type DocPageMeta, type FrontmatterResult, type FsAdapter, type FsSyncManifest, type FsTreeEntry, type JsonAttr, MARK_SPECS, MARK_SPEC_BY_DELIM, MARK_SPEC_BY_NAME, type ManifestEntry, type MarkAttrSpec, type MarkSpec, type MarkWireKind, type MetaValueType, NODE_SPECS, NODE_SPEC_BY_NAME, type NodeAttrSpec, type NodeSpec, type NodeWireKind, UNIVERSAL_META_KEYS, UNIVERSAL_META_KEY_NAMES, type UniversalMetaKey, type UploadManifestEntry, type YjsDiff, type YjsJsonElement, type YjsJsonNode, type YjsJsonText, type YjsTextRun, appendHtmlToFragment, buildAliasMap, buildRelativePath, buildReverseLookup, codeCompanionPath, codeFileExtension, conflictsDir, createEmptyManifest, diffJson, diffYjs, extToLanguage, filenameToLabel, fsFilenameToLabel, getDocDir, getFsAdapter, getTreeData, hasChildren, inferCodeMetaFromFilename, isCodeExtension, jsonToYFragment, labelToFilename, languageToExtension, loadManifest, lookupByDocId, lookupByHash, lookupByPath, manifestDir, mdcTagOf, nextOrder, normalizeExtension, orphansDir, parseFrontmatter, populateYDocFromHtml, populateYDocFromMarkdown, readCodeText, removeEntry, resolveParentFromPath, saveManifest, setEntry, setFsAdapter, simpleHash, stringifyJsonNode, trashDir, writeCodeText, yfragmentToJson, yjsToHtml, yjsToMarkdown, yjsToPlainText };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/convert",
-  "version": "2.11.0",
+  "version": "2.14.0",
   "description": "Bullet-proof Markdown ↔ Yjs/TipTap round-trip — canonical converter shared by cou-sh, abracadabra-nuxt, and @abraca/mcp.",
   "license": "MIT",
   "type": "module",

package/src/code.ts

@@ -0,0 +1,208 @@
+// Code page-type helpers for @abraca/convert.
+//
+// A `code` document stores its content in a plain `Y.Text` under the
+// `code` key (edited via CodeMirror + y-codemirror.next), separate from
+// the TipTap prose fragment that carries the `documentHeader`/
+// `documentMeta` envelope. fs-sync writes that text out to a real code
+// file (e.g. `main.rs`) alongside the `.md` envelope.
+//
+// This module owns the single source of truth for:
+//   - the `code` Y.Text key name,
+//   - reading/replacing that text,
+//   - the file-extension ↔ CodeMirror-language mapping used by both
+//     fs-sync directions and the renderer.
+//
+// `yjs` stays a type-only peer import — these helpers only call methods
+// on the Y.Doc handed in by the caller, never construct Y types.
+
+import type * as Y from 'yjs'
+
+/** Y.Text key holding a code document's content. */
+export const CODE_TEXT_KEY = 'code'
+
+/** Read a code document's raw text. Empty string when absent. */
+export function readCodeText(doc: Y.Doc): string {
+  return doc.getText(CODE_TEXT_KEY).toString()
+}
+
+/**
+ * Replace a code document's full text in a single transaction. `origin`
+ * is forwarded to `transact` so callers (e.g. fs-sync) can tag the write
+ * and skip their own observers.
+ */
+export function writeCodeText(doc: Y.Doc, content: string, origin?: unknown): void {
+  const ytext = doc.getText(CODE_TEXT_KEY)
+  doc.transact(() => {
+    if (ytext.length > 0) ytext.delete(0, ytext.length)
+    if (content.length > 0) ytext.insert(0, content)
+  }, origin)
+}
+
+// ── Extension ↔ language ─────────────────────────────────────────────────────
+//
+// Keys are lowercase extensions without the leading dot; values are the
+// canonical CodeMirror language id the renderer resolves against
+// `@codemirror/language-data`. The first extension listed for a language
+// in EXT_BY_LANGUAGE is the one fs-sync uses when writing the file.
+
+const LANGUAGE_BY_EXT: Readonly<Record<string, string>> = {
+  // JS/TS family
+  js: 'javascript',
+  mjs: 'javascript',
+  cjs: 'javascript',
+  jsx: 'jsx',
+  ts: 'typescript',
+  mts: 'typescript',
+  cts: 'typescript',
+  tsx: 'tsx',
+  // Web
+  html: 'html',
+  htm: 'html',
+  css: 'css',
+  scss: 'scss',
+  less: 'less',
+  vue: 'vue',
+  svelte: 'svelte',
+  // Data / config
+  json: 'json',
+  jsonc: 'json',
+  json5: 'json',
+  yaml: 'yaml',
+  yml: 'yaml',
+  toml: 'toml',
+  xml: 'xml',
+  ini: 'properties',
+  env: 'properties',
+  // Systems
+  rs: 'rust',
+  go: 'go',
+  c: 'c',
+  h: 'c',
+  cpp: 'cpp',
+  cc: 'cpp',
+  cxx: 'cpp',
+  hpp: 'cpp',
+  cs: 'csharp',
+  java: 'java',
+  kt: 'kotlin',
+  kts: 'kotlin',
+  swift: 'swift',
+  m: 'objective-c',
+  mm: 'objective-c',
+  // Scripting
+  py: 'python',
+  pyi: 'python',
+  rb: 'ruby',
+  php: 'php',
+  pl: 'perl',
+  lua: 'lua',
+  r: 'r',
+  // Shell
+  sh: 'shell',
+  bash: 'shell',
+  zsh: 'shell',
+  fish: 'shell',
+  // Query / misc
+  sql: 'sql',
+  graphql: 'graphql',
+  gql: 'graphql',
+  dockerfile: 'dockerfile',
+  // Markup that is genuinely "code" in a vault context
+  md: 'markdown',
+  markdown: 'markdown',
+}
+
+/** Preferred on-disk extension per language (reverse of LANGUAGE_BY_EXT). */
+const EXT_BY_LANGUAGE: Readonly<Record<string, string>> = {
+  javascript: 'js',
+  jsx: 'jsx',
+  typescript: 'ts',
+  tsx: 'tsx',
+  html: 'html',
+  css: 'css',
+  scss: 'scss',
+  less: 'less',
+  vue: 'vue',
+  svelte: 'svelte',
+  json: 'json',
+  yaml: 'yaml',
+  toml: 'toml',
+  xml: 'xml',
+  properties: 'ini',
+  rust: 'rs',
+  go: 'go',
+  c: 'c',
+  cpp: 'cpp',
+  csharp: 'cs',
+  java: 'java',
+  kotlin: 'kt',
+  swift: 'swift',
+  'objective-c': 'm',
+  python: 'py',
+  ruby: 'rb',
+  php: 'php',
+  perl: 'pl',
+  lua: 'lua',
+  r: 'r',
+  shell: 'sh',
+  sql: 'sql',
+  graphql: 'graphql',
+  dockerfile: 'dockerfile',
+  markdown: 'md',
+  plain: 'txt',
+}
+
+/** Normalize an extension: strip leading dot(s), lowercase. */
+export function normalizeExtension(ext: string): string {
+  return ext.replace(/^\.+/, '').toLowerCase()
+}
+
+/**
+ * Whether a file extension should import as a `code` page type. Note
+ * `md`/`markdown` are intentionally NOT code extensions here — fs-sync
+ * treats `.md` as the prose/envelope format, so it's excluded from the
+ * code-import gate even though it has a language mapping for in-editor use.
+ */
+export function isCodeExtension(ext: string): boolean {
+  const e = normalizeExtension(ext)
+  if (e === 'md' || e === 'markdown') return false
+  return e in LANGUAGE_BY_EXT
+}
+
+/** CodeMirror language id for an extension, or undefined when unknown. */
+export function extToLanguage(ext: string): string | undefined {
+  return LANGUAGE_BY_EXT[normalizeExtension(ext)]
+}
+
+/** Preferred on-disk extension (no dot) for a language, or undefined. */
+export function languageToExtension(language: string): string | undefined {
+  return EXT_BY_LANGUAGE[language.toLowerCase()]
+}
+
+/**
+ * Derive `{ language, fileExtension }` from a filename for code import.
+ * Returns undefined when the extension is not a recognized code extension
+ * (so callers fall back to the prose/doc path).
+ */
+export function inferCodeMetaFromFilename(
+  filename: string,
+): { language: string, fileExtension: string } | undefined {
+  const dot = filename.lastIndexOf('.')
+  if (dot < 0) return undefined
+  const ext = normalizeExtension(filename.slice(dot + 1))
+  if (!isCodeExtension(ext)) return undefined
+  const language = LANGUAGE_BY_EXT[ext]
+  if (!language) return undefined
+  return { language, fileExtension: ext }
+}
+
+/**
+ * Choose the on-disk extension for a code doc on export. Prefers an
+ * explicit `fileExtension`, then the language's primary extension, then
+ * `txt`.
+ */
+export function codeFileExtension(meta?: { fileExtension?: string, language?: string }): string {
+  if (meta?.fileExtension) return normalizeExtension(meta.fileExtension)
+  if (meta?.language) return languageToExtension(meta.language) ?? 'txt'
+  return 'txt'
+}

package/src/file-blocks/manifest.ts

@@ -58,6 +58,11 @@ export interface ManifestEntry {
   contentHash: string // hash of last-written/read markdown
   lastWrittenAt: number
   lastReadAt: number
+  // Code page type: the companion code file written alongside the `.md`
+  // envelope (e.g. "src/main.rs"), and the hash of its last-synced text.
+  // Present only for `code` docs.
+  codePath?: string
+  codeHash?: string
   uploads: UploadManifestEntry[]
 }
 

package/src/file-blocks/paths.ts

@@ -126,6 +126,23 @@ export function buildRelativePath(
   return `${parentPath}${parentPath ? '/' : ''}${resolvedFilename}.md`
 }
 
+/**
+ * Companion code-file path for a `code` doc, derived from its `.md`
+ * envelope path by swapping the extension. e.g.
+ * `src/main.md` + `rs` -> `src/main.rs`. A code doc never has children,
+ * so the `_index.md` form is not expected here, but is handled defensively.
+ */
+export function codeCompanionPath(mdRelativePath: string, fileExtension: string): string {
+  const ext = fileExtension.replace(/^\.+/, '').toLowerCase() || 'txt'
+  if (mdRelativePath.endsWith('/_index.md')) {
+    return `${mdRelativePath.slice(0, -'/_index.md'.length)}/_index.${ext}`
+  }
+  if (mdRelativePath.endsWith('.md')) {
+    return `${mdRelativePath.slice(0, -'.md'.length)}.${ext}`
+  }
+  return `${mdRelativePath}.${ext}`
+}
+
 /**
  * Get the directory portion of a relative path for a doc.
  * For _index.md docs: returns the directory containing _index.md

package/src/index.ts

@@ -24,6 +24,20 @@ export {
 
 export type { DocPageMeta } from './types.ts'
 
+// Code page-type helpers — Y.Text('code') accessors + the canonical
+// extension ↔ CodeMirror-language mapping shared by fs-sync and renderers.
+export {
+  CODE_TEXT_KEY,
+  readCodeText,
+  writeCodeText,
+  normalizeExtension,
+  isCodeExtension,
+  extToLanguage,
+  languageToExtension,
+  inferCodeMetaFromFilename,
+  codeFileExtension,
+} from './code.ts'
+
 // Structural Y.XmlFragment ↔ JSON converter + diff. Used by the
 // integration test suite and available to consumers who want to
 // author golden fixtures or do their own assertions.
@@ -94,6 +108,7 @@ export {
   fsFilenameToLabel,
   hasChildren,
   buildRelativePath,
+  codeCompanionPath,
   getDocDir,
   resolveParentFromPath,
   simpleHash,

package/src/markdown-to-yjs.ts

@@ -146,6 +146,14 @@ export function parseFrontmatter(markdown: string): FrontmatterResult {
   const url = getStr(['url'])
   if (url) meta.url = url
 
+  // Code page type meta.
+  const language = getStr(['language'])
+  if (language) meta.language = language
+  const fileExtension = getStr(['fileExtension'])
+  if (fileExtension) meta.fileExtension = fileExtension
+  const codeTheme = getStr(['codeTheme'])
+  if (codeTheme) meta.codeTheme = codeTheme
+
   const ratingRaw = getStr(['rating'])
   if (ratingRaw !== undefined) {
     const n = Number(ratingRaw)

package/src/types.ts

@@ -84,6 +84,11 @@ export interface DocPageMeta extends Record<string, unknown> {
   slidesTransition?: 'none' | 'fade' | 'slide'
   slidesTheme?: 'dark' | 'light'
 
+  // Code page type
+  language?: string
+  fileExtension?: string
+  codeTheme?: string
+
   // Schema migration version
   __schemaVersion?: number
 }

package/src/yjs-to-markdown.ts

@@ -503,6 +503,11 @@ function generateFrontmatter(label: string | undefined, meta?: DocPageMeta, type
   }
 
   if (meta.checked !== undefined) lines.push(`checked: ${meta.checked}`)
+  // Code page type: syntax-highlight language + on-disk extension. These
+  // round-trip the `.md` envelope so the companion code file can be re-derived.
+  if (meta.language) lines.push(`language: ${yamlScalar(meta.language)}`)
+  if (meta.fileExtension) lines.push(`fileExtension: ${yamlScalar(meta.fileExtension)}`)
+  if (meta.codeTheme) lines.push(`codeTheme: ${yamlScalar(meta.codeTheme)}`)
   if (meta.dateStart) lines.push(`dateStart: "${escapeYaml(meta.dateStart)}"`)
   if (meta.dateEnd) lines.push(`dateEnd: "${escapeYaml(meta.dateEnd)}"`)
   if (meta.subtitle) lines.push(`subtitle: "${escapeYaml(meta.subtitle)}"`)