@moxn/kb-migrate 0.4.35 → 0.4.37

package/dist/api-error.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Format a failed `/api/v1/kb/*` response body into a single error message.
+ *
+ * The app's error envelope is `{ error?: string, code?: string, details?: unknown }`.
+ * `details` is frequently a structured OBJECT (e.g. a 409's conflicting path),
+ * so the old `\`...: ${body.details}\`` interpolation rendered the useless
+ * "[object Object]". Prefer the human `error` string; fall back to `details`
+ * (JSON-stringified when it's an object); finally just the status.
+ */
+export declare function formatApiError(status: number, body: {
+    error?: unknown;
+    details?: unknown;
+    [key: string]: unknown;
+} | null | undefined): string;

package/dist/api-error.js

@@ -0,0 +1,19 @@
+/**
+ * Format a failed `/api/v1/kb/*` response body into a single error message.
+ *
+ * The app's error envelope is `{ error?: string, code?: string, details?: unknown }`.
+ * `details` is frequently a structured OBJECT (e.g. a 409's conflicting path),
+ * so the old `\`...: ${body.details}\`` interpolation rendered the useless
+ * "[object Object]". Prefer the human `error` string; fall back to `details`
+ * (JSON-stringified when it's an object); finally just the status.
+ */
+export function formatApiError(status, body) {
+    const detail = typeof body?.error === 'string' && body.error.length > 0
+        ? body.error
+        : body?.details != null
+            ? typeof body.details === 'string'
+                ? body.details
+                : JSON.stringify(body.details)
+            : '';
+    return detail ? `API error ${status}: ${detail}` : `API error: ${status}`;
+}

package/dist/api-error.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/api-error.test.js

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest';
+import { formatApiError } from './api-error.js';
+describe('formatApiError', () => {
+    it('renders a structured `details` object as JSON, not "[object Object]"', () => {
+        // The 409 the import path used to surface: { error, code, details: {...} }.
+        const msg = formatApiError(409, {
+            error: 'Path already exists',
+            code: 'CONFLICT',
+            details: { path: '/imports/runbook', conflictingId: 'abc' },
+        });
+        // Prefer the human message; never leak "[object Object]".
+        expect(msg).not.toContain('[object Object]');
+        expect(msg).toContain('409');
+        expect(msg).toContain('Path already exists');
+    });
+    it('falls back to a JSON-stringified details when there is no error string', () => {
+        const msg = formatApiError(400, { details: { reason: 'bad input' } });
+        expect(msg).toBe('API error 400: {"reason":"bad input"}');
+    });
+    it('uses a plain string detail as-is', () => {
+        expect(formatApiError(500, { details: 'boom' })).toBe('API error 500: boom');
+    });
+    it('degrades to a bare status when the body carries no error/details', () => {
+        expect(formatApiError(503, {})).toBe('API error: 503');
+    });
+});

package/dist/client.d.ts

@@ -3,6 +3,31 @@
  */
 import type { ExtractedDocument, MigrationOptions, MigrationResult, DocumentListItem, DocumentDetail, ExportOptions } from './types.js';
 import type { DateFilter } from './date-filter.js';
+/**
+ * Grammar-markdown export of a document (`get_document_markdown` action on
+ * /api/v1/kb/export). `markdown` is the moxn-grammar interchange: front-matter
+ * + body + `:::image/:::csv/:::file/:::db` embeds with STORAGE refs.
+ */
+export interface DocumentMarkdownResponse {
+    id: string;
+    branchName: string;
+    markdown: string;
+}
+/**
+ * Result of an `import_markdown` UPSERT (action on /api/v1/kb/import).
+ * Mirrors the server's KBDocumentImportMarkdownResult.
+ */
+export interface ImportMarkdownResult {
+    id: string;
+    /** The CANONICAL path the doc landed at (`<parent>/<slug(name)>`), not the requested path. */
+    path: string;
+    outcome: 'created' | 'updated' | 'skipped';
+    existed: boolean;
+    /** The resolved document name (front-matter name, first H1, or filename stem). */
+    name?: string;
+    /** True when a front-matter block was present but NOT applied (no name → body-only import). */
+    frontMatterIgnored?: boolean;
+}
 export declare class MoxnClient {
     private apiUrl;
     private apiKey;
@@ -22,6 +47,42 @@ export declare class MoxnClient {
      * Get full document detail with sections and content.
      */
     getDocument(documentId: string): Promise<DocumentDetail>;
+    /**
+     * Get a document's GRAMMAR markdown (front-matter + body + `:::image/:::csv/
+     * :::file/:::db` embeds with STORAGE refs) via the `get_document_markdown`
+     * export action. This is the grammar interchange the local file-adapter
+     * writes to disk (Phase 9a-3) — the export IS the MCP `read`.
+     *
+     * `forEdit: true` keeps the H2 `{#id}` section anchors so a re-import can
+     * address sections stably.
+     */
+    getDocumentMarkdown(documentId: string, opts?: {
+        forEdit?: boolean;
+    }): Promise<DocumentMarkdownResponse | null>;
+    /**
+     * Build a `storageKey → signedDownloadUrl` map for a document's media, by
+     * reusing the `get_document_content` export action (the blocks read, which
+     * resolves each storage ref to a fresh signed URL). The grammar markdown
+     * carries storage KEYS in its embed `ref`s — this is how the file-adapter
+     * turns a key into a downloadable URL WITHOUT a new server endpoint.
+     * Returns an empty map when the document has no resolvable media.
+     */
+    getDocumentMediaUrls(documentId: string): Promise<Map<string, string>>;
+    /**
+     * UPSERT a document from GRAMMAR markdown via the `import_markdown` action.
+     * The inverse of {@link getDocumentMarkdown}: front-matter → name/path/tags/
+     * refs/properties, body → sections, all via the shipped `replace_document`
+     * verb. Media refs in the markdown must already be valid STORAGE keys (the
+     * file-adapter uploads local files + rewrites refs BEFORE calling this).
+     *
+     *   onConflict 'skip'   → skip if the path exists
+     *   onConflict 'update' → replace_document (full-set PUT)
+     */
+    importMarkdown(input: {
+        markdown: string;
+        path?: string;
+        onConflict: 'skip' | 'update';
+    }): Promise<ImportMarkdownResult>;
     /**
      * Download a file from a URL to a local path.
      */

package/dist/client.js

@@ -2,6 +2,7 @@
  * API client for Moxn KB
  */
 import * as fs from 'fs/promises';
+import { formatApiError } from './api-error.js';
 export class MoxnClient {
     apiUrl;
     apiKey;
@@ -166,6 +167,101 @@ export class MoxnClient {
         }
         return response.json();
     }
+    /**
+     * Get a document's GRAMMAR markdown (front-matter + body + `:::image/:::csv/
+     * :::file/:::db` embeds with STORAGE refs) via the `get_document_markdown`
+     * export action. This is the grammar interchange the local file-adapter
+     * writes to disk (Phase 9a-3) — the export IS the MCP `read`.
+     *
+     * `forEdit: true` keeps the H2 `{#id}` section anchors so a re-import can
+     * address sections stably.
+     */
+    async getDocumentMarkdown(documentId, opts) {
+        const response = await fetch(`${this.apiUrl}/api/v1/kb/export`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey,
+            },
+            body: JSON.stringify({
+                action: 'get_document_markdown',
+                documentId,
+                forEdit: opts?.forEdit ?? false,
+            }),
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(`Failed to get document markdown ${documentId}: ${response.status} ${body}`);
+        }
+        const data = await response.json();
+        return (data.result?.document ?? null);
+    }
+    /**
+     * Build a `storageKey → signedDownloadUrl` map for a document's media, by
+     * reusing the `get_document_content` export action (the blocks read, which
+     * resolves each storage ref to a fresh signed URL). The grammar markdown
+     * carries storage KEYS in its embed `ref`s — this is how the file-adapter
+     * turns a key into a downloadable URL WITHOUT a new server endpoint.
+     * Returns an empty map when the document has no resolvable media.
+     */
+    async getDocumentMediaUrls(documentId) {
+        const response = await fetch(`${this.apiUrl}/api/v1/kb/export`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey,
+            },
+            body: JSON.stringify({ action: 'get_document_content', documentId }),
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(`Failed to get document content ${documentId}: ${response.status} ${body}`);
+        }
+        const data = await response.json();
+        const doc = data.result?.document;
+        const map = new Map();
+        if (!doc)
+            return map;
+        for (const section of doc.sections) {
+            for (const block of section.content) {
+                if (block.storageKey && block.url && !block.url.startsWith('data:')) {
+                    map.set(block.storageKey, block.url);
+                }
+            }
+        }
+        return map;
+    }
+    /**
+     * UPSERT a document from GRAMMAR markdown via the `import_markdown` action.
+     * The inverse of {@link getDocumentMarkdown}: front-matter → name/path/tags/
+     * refs/properties, body → sections, all via the shipped `replace_document`
+     * verb. Media refs in the markdown must already be valid STORAGE keys (the
+     * file-adapter uploads local files + rewrites refs BEFORE calling this).
+     *
+     *   onConflict 'skip'   → skip if the path exists
+     *   onConflict 'update' → replace_document (full-set PUT)
+     */
+    async importMarkdown(input) {
+        const response = await fetch(`${this.apiUrl}/api/v1/kb/import`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey,
+            },
+            body: JSON.stringify({
+                action: 'import_markdown',
+                markdown: input.markdown,
+                path: input.path,
+                onConflict: input.onConflict,
+            }),
+        });
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({}));
+            throw new Error(formatApiError(response.status, body));
+        }
+        const data = await response.json();
+        return data.result;
+    }
     /**
      * Download a file from a URL to a local path.
      */
@@ -299,12 +395,7 @@ export class MoxnClient {
                 error.branchId = body.branchId;
                 throw error;
             }
-            const message = body.details
-                ? `API error ${response.status}: ${body.details}`
-                : body.error
-                    ? `API error ${response.status}: ${body.error}`
-                    : `API error: ${response.status}`;
-            throw new Error(message);
+            throw new Error(formatApiError(response.status, body));
         }
         return response.json();
     }
@@ -319,12 +410,7 @@ export class MoxnClient {
         });
         if (!response.ok) {
             const body = await response.json().catch(() => ({}));
-            const message = body.details
-                ? `API error ${response.status}: ${body.details}`
-                : body.error
-                    ? `API error ${response.status}: ${body.error}`
-                    : `API error: ${response.status}`;
-            throw new Error(message);
+            throw new Error(formatApiError(response.status, body));
         }
         return response.json();
     }

package/dist/export.d.ts

@@ -1,8 +1,16 @@
 /**
- * Export runner for Moxn KB
+ * Export runner for Moxn KB (Phase 9a-3 — grammar markdown).
  *
- * Exports documents from Moxn Knowledge Base to local markdown files
- * with downloaded media assets (images, PDFs, CSVs).
+ * Exports documents from Moxn Knowledge Base to local GRAMMAR markdown files
+ * (front-matter + body + `:::image/:::csv/:::file/:::db` embeds), with
+ * downloaded media assets and embed `ref`s rewritten to RELATIVE paths so the
+ * exported folder is self-contained and re-imports identically.
+ *
+ * This is the inverse of the local import (`runMigration` over the LocalSource):
+ *   - export: `get_document_markdown` → write `.md`; download media; rewrite
+ *     `:::…{ref="<storage-key>"}` → `ref="<relative-path>"`.
+ *   - import: read `.md`; upload media; rewrite `ref` back to a storage key;
+ *     `import_markdown`.
  */
 import type { ExportOptions, ExportLog } from './types.js';
 export declare function runExport(outputDir: string, options: ExportOptions): Promise<ExportLog>;

package/dist/export.js

@@ -1,140 +1,51 @@
 /**
- * Export runner for Moxn KB
+ * Export runner for Moxn KB (Phase 9a-3 — grammar markdown).
  *
- * Exports documents from Moxn Knowledge Base to local markdown files
- * with downloaded media assets (images, PDFs, CSVs).
+ * Exports documents from Moxn Knowledge Base to local GRAMMAR markdown files
+ * (front-matter + body + `:::image/:::csv/:::file/:::db` embeds), with
+ * downloaded media assets and embed `ref`s rewritten to RELATIVE paths so the
+ * exported folder is self-contained and re-imports identically.
+ *
+ * This is the inverse of the local import (`runMigration` over the LocalSource):
+ *   - export: `get_document_markdown` → write `.md`; download media; rewrite
+ *     `:::…{ref="<storage-key>"}` → `ref="<relative-path>"`.
+ *   - import: read `.md`; upload media; rewrite `ref` back to a storage key;
+ *     `import_markdown`.
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import { MoxnClient } from './client.js';
 import { matchesDateFilter } from './date-filter.js';
+import { extractMediaRefs, rewriteMediaRefs, } from './grammar-media.js';
 // ──────────────────────────────────────────────
 // Utility functions
 // ──────────────────────────────────────────────
-/** Strip <moxn:comment> tags from text, preserving the inner text. */
-function stripCommentTags(text) {
-    return text.replace(/<moxn:comment[^>]*>([\s\S]*?)<\/moxn:comment>/g, '$1');
-}
-/** Derive a local filename from a storage key or URL. */
-function deriveFilename(storageKey, url, fallbackExt) {
-    if (storageKey) {
-        const parts = storageKey.split('/');
-        return parts[parts.length - 1];
-    }
-    try {
-        const urlPath = new URL(url).pathname;
-        const basename = urlPath.split('/').pop();
-        if (basename && basename.includes('.')) {
-            return basename;
-        }
-    }
-    catch {
-        // Not a valid URL
+/** Derive a local filename from a storage key (the key's basename). */
+function filenameFromStorageKey(storageKey, fallbackExt) {
+    const basename = storageKey.split('/').pop();
+    if (basename && basename.length > 0) {
+        return basename.includes('.') ? basename : `${basename}${fallbackExt}`;
     }
     return `export-${Date.now()}${fallbackExt}`;
 }
-/** Get file extension from MIME type. */
-function mimeToExt(mimeType) {
-    const map = {
-        'image/png': '.png',
-        'image/jpeg': '.jpg',
-        'image/gif': '.gif',
-        'image/webp': '.webp',
-        'application/pdf': '.pdf',
-        'text/csv': '.csv',
-    };
-    return map[mimeType] || '';
+/** Map an embed directive to its output media dir + a fallback extension. */
+function mediaTargetForDirective(directive, options) {
+    switch (directive) {
+        case 'image':
+            return { dir: options.imageDir, fallbackExt: '' };
+        case 'csv':
+            return { dir: options.csvDir, fallbackExt: '.csv' };
+        case 'file':
+        default:
+            // `file` embeds are generic attachments (PDFs and everything else).
+            return { dir: options.pdfDir, fallbackExt: '' };
+    }
 }
-/** Convert a document path to a local file path. */
+/** Convert a KB document path to a local `.md` file path. */
 function docPathToFilePath(docPath) {
     return `${docPath.replace(/^\//, '')}.md`;
 }
 // ──────────────────────────────────────────────
-// Markdown builder
-// ──────────────────────────────────────────────
-function buildMarkdown(doc, mediaMap, mdFilePath) {
-    const lines = [];
-    lines.push(`# ${doc.name}`);
-    lines.push('');
-    if (doc.description) {
-        lines.push(doc.description);
-        lines.push('');
-    }
-    for (const section of doc.sections) {
-        lines.push(`## ${section.name}`);
-        lines.push('');
-        for (const block of section.content) {
-            if (block.blockType === 'text' && block.text) {
-                lines.push(stripCommentTags(block.text));
-                lines.push('');
-            }
-            else if (block.blockType === 'image' && block.url) {
-                const key = block.storageKey || block.url;
-                const localPath = mediaMap.get(key);
-                if (localPath) {
-                    const relativePath = path.relative(path.dirname(mdFilePath), localPath);
-                    lines.push(`![${block.alt || ''}](${relativePath})`);
-                }
-                else {
-                    lines.push(`![${block.alt || ''}](${block.url})`);
-                }
-                lines.push('');
-            }
-            else if (block.blockType === 'document' && block.url) {
-                const key = block.storageKey || block.url;
-                const localPath = mediaMap.get(key);
-                if (localPath) {
-                    const relativePath = path.relative(path.dirname(mdFilePath), localPath);
-                    lines.push(`[${block.filename || 'document'}](${relativePath})`);
-                }
-                else {
-                    lines.push(`[${block.filename || 'document'}](${block.url})`);
-                }
-                lines.push('');
-            }
-            else if (block.blockType === 'csv' && block.url) {
-                const key = block.storageKey || block.url;
-                const localPath = mediaMap.get(key);
-                if (localPath) {
-                    const relativePath = path.relative(path.dirname(mdFilePath), localPath);
-                    lines.push(`[${block.filename || 'data.csv'}](${relativePath})`);
-                }
-                else {
-                    lines.push(`[${block.filename || 'data.csv'}](${block.url})`);
-                }
-                lines.push('');
-            }
-        }
-    }
-    // Trim trailing blank lines, end with single newline
-    while (lines.length > 0 && lines[lines.length - 1].trim() === '') {
-        lines.pop();
-    }
-    lines.push('');
-    return lines.join('\n');
-}
-// ──────────────────────────────────────────────
-// Media helpers
-// ──────────────────────────────────────────────
-function getMediaTarget(block, options) {
-    if (block.blockType === 'image') {
-        return {
-            targetDir: options.imageDir,
-            fallbackExt: mimeToExt(block.mimeType || 'image/png'),
-        };
-    }
-    else if (block.blockType === 'document') {
-        return {
-            targetDir: options.pdfDir,
-            fallbackExt: mimeToExt(block.mimeType || 'application/pdf'),
-        };
-    }
-    else if (block.blockType === 'csv') {
-        return { targetDir: options.csvDir, fallbackExt: '.csv' };
-    }
-    return null;
-}
-// ──────────────────────────────────────────────
 // Main export runner
 // ──────────────────────────────────────────────
 export async function runExport(outputDir, options) {
@@ -192,64 +103,90 @@ export async function runExport(outputDir, options) {
         const mediaFiles = [];
         console.error(`Processing: ${docItem.path}`);
         try {
-            const doc = await client.getDocument(docItem.id);
-            const mdRelativePath = docPathToFilePath(doc.path);
+            // 1. Grammar markdown body (front-matter + body + embeds with storage refs).
+            //    CLEAN export (no `forEdit`): the H2 `{#id}` section anchors are
+            //    DROPPED. Those ids belong to THIS source document; the local import
+            //    feeds the grammar straight to `replace_document`, which on a re-home
+            //    (import to a NEW path / new doc) REJECTS foreign ids
+            //    (`section id … not found on branch main`). `replace_document`'s
+            //    diff-derived identity already preserves ids on a same-path UPDATE by
+            //    content-matching, so the anchors buy nothing there and only break the
+            //    CREATE/re-home case. Matches the `/api/v1/kb/export` default contract
+            //    and the kb-import-markdown round-trip test (both use the clean export).
+            const doc = await client.getDocumentMarkdown(docItem.id);
+            if (!doc) {
+                throw new Error('document is not a grammar-markdown document (no body)');
+            }
+            const mdRelativePath = docPathToFilePath(docItem.path);
             const mdFullPath = path.join(outputDir, mdRelativePath);
-            const mediaMap = new Map();
-            // Download media
-            for (const section of doc.sections) {
-                for (const block of section.content) {
-                    if (block.blockType === 'text')
-                        continue;
-                    if (!block.url)
-                        continue;
-                    if (block.url.startsWith('data:'))
-                        continue;
-                    const target = getMediaTarget(block, options);
-                    if (!target)
-                        continue;
-                    const filename = deriveFilename(block.storageKey, block.url, target.fallbackExt);
-                    const localRelativePath = path.join(target.targetDir, filename);
-                    const localFullPath = path.join(outputDir, localRelativePath);
-                    const mapKey = block.storageKey || block.url;
-                    mediaMap.set(mapKey, path.join(outputDir, localRelativePath));
-                    if (!options.dryRun) {
-                        if (!fs.existsSync(localFullPath)) {
-                            try {
-                                await client.downloadFile(block.url, localFullPath);
-                                totalMediaDownloaded++;
-                            }
-                            catch (err) {
-                                const msg = err instanceof Error ? err.message : String(err);
-                                console.error(`  \u2717 Download failed: ${filename}: ${msg}`);
-                            }
+            // 2. Discover the media storage keys referenced in the body.
+            const mediaRefs = extractMediaRefs(doc.markdown);
+            // 3. Resolve storage keys → signed download URLs (reuses the blocks read).
+            //    Only fetch when there's media to download.
+            const signedUrls = mediaRefs.length
+                ? await client.getDocumentMediaUrls(docItem.id)
+                : new Map();
+            // 4. Download each unique media key + build a key → relative-path map.
+            const keyToRelPath = new Map();
+            for (const { directive, ref } of mediaRefs) {
+                // Skip non-storage refs (e.g. an external URL someone hand-authored)
+                // and refs we've already handled.
+                if (keyToRelPath.has(ref))
+                    continue;
+                const signedUrl = signedUrls.get(ref);
+                if (!signedUrl) {
+                    // No signed URL for this ref — leave it as-is (rewrite skips null).
+                    continue;
+                }
+                const target = mediaTargetForDirective(directive, options);
+                const filename = filenameFromStorageKey(ref, target.fallbackExt);
+                const localRelativePath = path.join(target.dir, filename);
+                const localFullPath = path.join(outputDir, localRelativePath);
+                if (!options.dryRun) {
+                    if (!fs.existsSync(localFullPath)) {
+                        try {
+                            await client.downloadFile(signedUrl, localFullPath);
+                            totalMediaDownloaded++;
+                        }
+                        catch (err) {
+                            const msg = err instanceof Error ? err.message : String(err);
+                            console.error(`  ✗ Download failed: ${filename}: ${msg}`);
+                            // Leave the embed ref pointing at the storage key (no rewrite).
+                            continue;
                         }
                     }
-                    else {
-                        totalMediaDownloaded++;
-                    }
-                    mediaFiles.push(localRelativePath);
                 }
+                else {
+                    totalMediaDownloaded++;
+                }
+                // The embed ref is rewritten to a path RELATIVE to the .md file.
+                const refRelativeToMd = path.relative(path.dirname(mdFullPath), localFullPath);
+                keyToRelPath.set(ref, refRelativeToMd);
+                mediaFiles.push(localRelativePath);
             }
-            const markdown = buildMarkdown(doc, mediaMap, mdFullPath);
+            // 5. Rewrite the embed refs (storage key → relative path). Refs with no
+            //    download (keyToRelPath miss) are left untouched.
+            const markdown = rewriteMediaRefs(doc.markdown, (ref) => keyToRelPath.get(ref) ?? null);
             if (!options.dryRun) {
                 fs.mkdirSync(path.dirname(mdFullPath), { recursive: true });
                 fs.writeFileSync(mdFullPath, markdown, 'utf-8');
             }
-            console.error(`  \u2713 ${mdRelativePath} (${doc.sections.length} sections, ${mediaFiles.length} media)`);
+            console.error(`  ✓ ${mdRelativePath} (${mediaFiles.length} media)`);
             results.push({
-                documentId: doc.id,
-                documentPath: doc.path,
+                documentId: docItem.id,
+                documentPath: docItem.path,
                 outputFile: mdRelativePath,
                 status: 'exported',
-                sectionsCount: doc.sections.length,
+                // Grammar export is body-grain, not section-grain; sections are no
+                // longer enumerated client-side.
+                sectionsCount: 0,
                 mediaFiles,
                 duration: Date.now() - docStart,
             });
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            console.error(`  \u2717 Failed: ${message}`);
+            console.error(`  ✗ Failed: ${message}`);
             results.push({
                 documentId: docItem.id,
                 documentPath: docItem.path,

package/dist/export.test.d.ts

@@ -0,0 +1 @@
+export {};