@moxn/kb-migrate 0.4.34 → 0.4.36

package/dist/export.test.js

@@ -0,0 +1,107 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { runExport } from './export.js';
+import { MoxnClient } from './client.js';
+/**
+ * Issue 1 (Phase 9a) — the export must emit CLEAN grammar (no H2 `{#id}`
+ * section anchors), so a re-home import (`replace_document` to a NEW path /
+ * doc) doesn't reject the foreign ids. Previously the export passed
+ * `forEdit: true`, which keeps the source doc's section anchors and breaks
+ * the CREATE/re-home path. These tests pin the export at the clean contract.
+ */
+describe('runExport — clean grammar (no {#id} anchors, Issue 1)', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    function makeOptions() {
+        return {
+            apiUrl: 'http://localhost:3001',
+            apiKey: 'test-key',
+            basePath: '',
+            imageDir: 'images',
+            pdfDir: 'pdfs',
+            csvDir: 'csvs',
+            dryRun: false,
+        };
+    }
+    it('calls getDocumentMarkdown WITHOUT forEdit (clean export)', async () => {
+        const outputDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-export-clean-'));
+        // One document, no media — isolate the forEdit assertion.
+        vi.spyOn(MoxnClient.prototype, 'listDocuments').mockResolvedValue([
+            {
+                id: 'doc-1',
+                path: '/guides/intro',
+                name: 'intro',
+                description: null,
+                createdAt: '2026-01-01T00:00:00.000Z',
+                updatedAt: null,
+            },
+        ]);
+        const getMd = vi
+            .spyOn(MoxnClient.prototype, 'getDocumentMarkdown')
+            .mockResolvedValue({
+            id: 'doc-1',
+            branchName: 'main',
+            markdown: [
+                '---',
+                'name: intro',
+                'path: /guides/intro',
+                '---',
+                '',
+                '## Setup',
+                '',
+                'body',
+            ].join('\n'),
+        });
+        await runExport(outputDir, makeOptions());
+        expect(getMd).toHaveBeenCalledTimes(1);
+        const [, opts] = getMd.mock.calls[0];
+        // The load-bearing assertion: NO forEdit (undefined, or explicitly falsy).
+        // A clean export must not request the source doc's section anchors.
+        expect(opts?.forEdit ?? false).toBe(false);
+        fs.rmSync(outputDir, { recursive: true, force: true });
+    });
+    it('writes a body with no H2 {#id} anchors (re-home import would not reject)', async () => {
+        const outputDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-export-noanchor-'));
+        vi.spyOn(MoxnClient.prototype, 'listDocuments').mockResolvedValue([
+            {
+                id: 'doc-2',
+                path: '/guides/deep/topic',
+                name: 'topic',
+                description: null,
+                createdAt: '2026-01-01T00:00:00.000Z',
+                updatedAt: null,
+            },
+        ]);
+        // The CLEAN grammar a forEdit:false read emits — H2s carry NO `{#id}`.
+        const cleanMarkdown = [
+            '---',
+            'name: topic',
+            'path: /guides/deep/topic',
+            '---',
+            '',
+            '## Overview',
+            '',
+            'overview prose',
+            '',
+            '## Details',
+            '',
+            'details prose',
+        ].join('\n');
+        vi.spyOn(MoxnClient.prototype, 'getDocumentMarkdown').mockResolvedValue({
+            id: 'doc-2',
+            branchName: 'main',
+            markdown: cleanMarkdown,
+        });
+        await runExport(outputDir, makeOptions());
+        const written = fs.readFileSync(path.join(outputDir, 'guides/deep/topic.md'), 'utf-8');
+        // No `{#<id>}` heading anchor of any form survives in the exported body.
+        expect(written).not.toMatch(/\{#[^}]+\}/);
+        // Sanity: the headings + prose are still present (we didn't drop content).
+        expect(written).toContain('## Overview');
+        expect(written).toContain('## Details');
+        fs.rmSync(outputDir, { recursive: true, force: true });
+    });
+});

package/dist/grammar-media.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Grammar media embed helpers (Phase 9a-3).
+ *
+ * The moxn grammar markdown the `/api/v1/kb/export` `get_document_markdown`
+ * action emits carries media as line-leading directives:
+ *
+ *   :::image{ref="<storage-key>" alt="…" w="…" align="…" mime="…"}
+ *   :::file{ref="<storage-key>" filename="…" mime="…" size=123 …}
+ *   :::csv{ref="<storage-key>" filename="…" headers=[a,b] rowCount=10 …}
+ *   :::db{ref="<database-id>"}
+ *
+ * For a SELF-CONTAINED local export, the file-adapter downloads each media file
+ * and rewrites the embed `ref` from the storage key to a RELATIVE path; on
+ * import it uploads the local file and rewrites the `ref` back to the storage
+ * key BEFORE handing the grammar to `import_markdown` (which ingests refs as-is,
+ * exactly like the MCP `read`).
+ *
+ * This module is a deliberately FOCUSED regex over the embed lines — kb-migrate
+ * is a separate package and cannot import the in-`src` grammar codec
+ * (`src/lib/kb/grammar/embeds.ts`). It reads/rewrites ONLY the `ref` attribute
+ * and preserves every other attribute and its order verbatim.
+ *
+ * IMPORTANT: `:::db` refs are DATABASE IDs (the embed travels by reference, not
+ * as a file) — they are NEVER treated as media. Only `image | file | csv` are.
+ */
+/** Embed directive names that carry a media file via `ref` (NOT `db`). */
+export declare const MEDIA_DIRECTIVES: readonly ["image", "file", "csv"];
+export type MediaDirective = (typeof MEDIA_DIRECTIVES)[number];
+/** A media embed discovered in a grammar markdown string. */
+export interface MediaEmbedRef {
+    /** Directive name: 'image' | 'file' | 'csv'. */
+    directive: MediaDirective;
+    /** The current value of the `ref` attribute (a storage key or a relative path). */
+    ref: string;
+}
+/**
+ * Extract every media embed `ref` (image/file/csv) from a grammar markdown
+ * string, in document order. `:::db` embeds are intentionally excluded (their
+ * ref is a database id, not a file). Duplicate refs are returned once each
+ * occurrence — callers that want uniqueness should dedupe on `ref`.
+ */
+export declare function extractMediaRefs(markdown: string): MediaEmbedRef[];
+/**
+ * Rewrite the `ref` attribute of every media embed (image/file/csv) using
+ * `mapRef`, preserving the directive name, every other attribute, and their
+ * order. `:::db` embeds are left untouched.
+ *
+ * `mapRef(currentRef, directive)` returns the replacement ref, or `null` /
+ * `undefined` to leave that embed's ref unchanged (e.g. an external URL we
+ * chose not to localize, or a missing upload).
+ */
+export declare function rewriteMediaRefs(markdown: string, mapRef: (ref: string, directive: MediaDirective) => string | null | undefined): string;

package/dist/grammar-media.js

@@ -0,0 +1,77 @@
+/**
+ * Grammar media embed helpers (Phase 9a-3).
+ *
+ * The moxn grammar markdown the `/api/v1/kb/export` `get_document_markdown`
+ * action emits carries media as line-leading directives:
+ *
+ *   :::image{ref="<storage-key>" alt="…" w="…" align="…" mime="…"}
+ *   :::file{ref="<storage-key>" filename="…" mime="…" size=123 …}
+ *   :::csv{ref="<storage-key>" filename="…" headers=[a,b] rowCount=10 …}
+ *   :::db{ref="<database-id>"}
+ *
+ * For a SELF-CONTAINED local export, the file-adapter downloads each media file
+ * and rewrites the embed `ref` from the storage key to a RELATIVE path; on
+ * import it uploads the local file and rewrites the `ref` back to the storage
+ * key BEFORE handing the grammar to `import_markdown` (which ingests refs as-is,
+ * exactly like the MCP `read`).
+ *
+ * This module is a deliberately FOCUSED regex over the embed lines — kb-migrate
+ * is a separate package and cannot import the in-`src` grammar codec
+ * (`src/lib/kb/grammar/embeds.ts`). It reads/rewrites ONLY the `ref` attribute
+ * and preserves every other attribute and its order verbatim.
+ *
+ * IMPORTANT: `:::db` refs are DATABASE IDs (the embed travels by reference, not
+ * as a file) — they are NEVER treated as media. Only `image | file | csv` are.
+ */
+/** Embed directive names that carry a media file via `ref` (NOT `db`). */
+export const MEDIA_DIRECTIVES = ['image', 'file', 'csv'];
+/**
+ * Matches a single media embed line and captures:
+ *   [1] directive name (image|file|csv)
+ *   [2] the attrs before `ref="…"` (may be empty)
+ *   [3] the ref value (inside the quotes)
+ *   [4] the attrs after the ref (may be empty)
+ *
+ * Anchored to the start of a line (multiline) so it only ever matches a
+ * line-leading directive, never `:::image{…}` appearing inside prose/code.
+ * `ref` is the first attribute the serializer emits for every media node, so a
+ * leading-`ref` match covers the export's output; we still allow attrs before
+ * `ref` for robustness against hand-authored files.
+ *
+ * The `before` group `((?:[^}]*?\s)?)` is either empty (ref is the first attr)
+ * or ends in whitespace, so `ref=` only matches a whole-attribute key — never
+ * the tail of another key like `href=`/`xref=`.
+ */
+const MEDIA_EMBED_RE = /^(:::(image|file|csv)\{)((?:[^}]*?\s)?)ref="([^"]*)"([^}]*)(\})/gm;
+/**
+ * Extract every media embed `ref` (image/file/csv) from a grammar markdown
+ * string, in document order. `:::db` embeds are intentionally excluded (their
+ * ref is a database id, not a file). Duplicate refs are returned once each
+ * occurrence — callers that want uniqueness should dedupe on `ref`.
+ */
+export function extractMediaRefs(markdown) {
+    const refs = [];
+    // Use a fresh regex (global state is per-RegExp); reset lastIndex defensively.
+    const re = new RegExp(MEDIA_EMBED_RE.source, 'gm');
+    let m;
+    while ((m = re.exec(markdown)) !== null) {
+        refs.push({ directive: m[2], ref: m[4] });
+    }
+    return refs;
+}
+/**
+ * Rewrite the `ref` attribute of every media embed (image/file/csv) using
+ * `mapRef`, preserving the directive name, every other attribute, and their
+ * order. `:::db` embeds are left untouched.
+ *
+ * `mapRef(currentRef, directive)` returns the replacement ref, or `null` /
+ * `undefined` to leave that embed's ref unchanged (e.g. an external URL we
+ * chose not to localize, or a missing upload).
+ */
+export function rewriteMediaRefs(markdown, mapRef) {
+    return markdown.replace(MEDIA_EMBED_RE, (_full, open, directive, before, ref, after, close) => {
+        const next = mapRef(ref, directive);
+        const value = next == null ? ref : next;
+        return `${open}${before}ref="${value}"${after}${close}`;
+    });
+}

package/dist/grammar-media.test.d.ts

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

package/dist/grammar-media.test.js

@@ -0,0 +1,108 @@
+import { describe, it, expect } from 'vitest';
+import { extractMediaRefs, rewriteMediaRefs, } from './grammar-media.js';
+describe('extractMediaRefs', () => {
+    it('returns [] for a doc with no embeds', () => {
+        const md = `---\nname: Plain\npath: /plain\n---\n\n## Body\n\nJust prose.\n`;
+        expect(extractMediaRefs(md)).toEqual([]);
+    });
+    it('extracts a single image ref', () => {
+        const md = `## Pics\n\n:::image{ref="org_t1/a.png" alt="A" w="100%" align="center" mime="image/png"}\n`;
+        expect(extractMediaRefs(md)).toEqual([{ directive: 'image', ref: 'org_t1/a.png' }]);
+    });
+    it('extracts image, file, and csv refs in document order', () => {
+        const md = [
+            ':::image{ref="org_t1/a.png" alt="A"}',
+            ':::file{ref="org_t1/b.pdf" filename="b.pdf" mime="application/pdf"}',
+            ':::csv{ref="org_t1/c.csv" filename="c.csv" headers=[x,y] rowCount=3}',
+        ].join('\n\n');
+        expect(extractMediaRefs(md)).toEqual([
+            { directive: 'image', ref: 'org_t1/a.png' },
+            { directive: 'file', ref: 'org_t1/b.pdf' },
+            { directive: 'csv', ref: 'org_t1/c.csv' },
+        ]);
+    });
+    it('does NOT extract :::db embeds (db ref is a database id, not media)', () => {
+        const md = `:::db{ref="11111111-2222-3333-4444-555555555555"}\n\n:::image{ref="org_t1/a.png"}`;
+        expect(extractMediaRefs(md)).toEqual([{ directive: 'image', ref: 'org_t1/a.png' }]);
+    });
+    it('ignores a :::image directive that is not line-leading (inside prose)', () => {
+        const md = `Inline mention of :::image{ref="x"} should not match.\n`;
+        expect(extractMediaRefs(md)).toEqual([]);
+    });
+    it('returns each occurrence of a duplicate ref', () => {
+        const md = `:::image{ref="org_t1/a.png"}\n\n:::image{ref="org_t1/a.png" alt="again"}`;
+        expect(extractMediaRefs(md)).toEqual([
+            { directive: 'image', ref: 'org_t1/a.png' },
+            { directive: 'image', ref: 'org_t1/a.png' },
+        ]);
+    });
+    it('matches the real `ref` attr even when a prior attr key ends in "ref"', () => {
+        // A hypothetical leading attr whose key ends in "ref" must NOT be captured
+        // as the ref (boundary hardening: ref= only matches a whole attr key).
+        const md = `:::image{xref="decoy" ref="org_t1/a.png" alt="A"}`;
+        expect(extractMediaRefs(md)).toEqual([{ directive: 'image', ref: 'org_t1/a.png' }]);
+    });
+});
+describe('rewriteMediaRefs', () => {
+    it('is a no-op for a doc with no embeds', () => {
+        const md = `## Body\n\nNo media here.\n`;
+        expect(rewriteMediaRefs(md, () => 'WRONG')).toBe(md);
+    });
+    it('rewrites an image ref storage-key → relative path, preserving other attrs + order', () => {
+        const md = `:::image{ref="org_t1/a.png" alt="A" w="100%" align="center" mime="image/png"}`;
+        const out = rewriteMediaRefs(md, (ref) => ref === 'org_t1/a.png' ? 'images/a.png' : null);
+        expect(out).toBe(`:::image{ref="images/a.png" alt="A" w="100%" align="center" mime="image/png"}`);
+    });
+    it('rewrites a relative path back to a storage key (the import direction)', () => {
+        const md = `:::csv{ref="csvs/c.csv" filename="c.csv" headers=[x,y] rowCount=3}`;
+        const out = rewriteMediaRefs(md, (ref) => ref === 'csvs/c.csv' ? 'org_t1/uploaded.csv' : null);
+        expect(out).toBe(`:::csv{ref="org_t1/uploaded.csv" filename="c.csv" headers=[x,y] rowCount=3}`);
+    });
+    it('rewrites multiple embeds independently and routes by directive', () => {
+        const md = [
+            ':::image{ref="org_t1/a.png" alt="A"}',
+            ':::file{ref="org_t1/b.pdf" filename="b.pdf"}',
+            ':::csv{ref="org_t1/c.csv" filename="c.csv"}',
+        ].join('\n\n');
+        const seen = [];
+        const out = rewriteMediaRefs(md, (ref, directive) => {
+            seen.push([ref, directive]);
+            return `${directive}s/${ref.split('/').pop()}`;
+        });
+        expect(out).toBe([
+            ':::image{ref="images/a.png" alt="A"}',
+            ':::file{ref="files/b.pdf" filename="b.pdf"}',
+            ':::csv{ref="csvs/c.csv" filename="c.csv"}',
+        ].join('\n\n'));
+        expect(seen).toEqual([
+            ['org_t1/a.png', 'image'],
+            ['org_t1/b.pdf', 'file'],
+            ['org_t1/c.csv', 'csv'],
+        ]);
+    });
+    it('leaves the ref unchanged when mapRef returns null or undefined', () => {
+        const md = `:::image{ref="https://external/x.png" alt="ext"}`;
+        expect(rewriteMediaRefs(md, () => null)).toBe(md);
+        expect(rewriteMediaRefs(md, () => undefined)).toBe(md);
+    });
+    it('never rewrites a :::db ref', () => {
+        const md = `:::db{ref="db-uuid-123"}\n\n:::image{ref="org_t1/a.png"}`;
+        const out = rewriteMediaRefs(md, () => 'images/a.png');
+        expect(out).toBe(`:::db{ref="db-uuid-123"}\n\n:::image{ref="images/a.png"}`);
+    });
+    it('round-trips: export rewrite (key→path) then import rewrite (path→key) restores the original', () => {
+        const original = `:::image{ref="org_t1/a.png" alt="A" mime="image/png"}\n\n:::file{ref="org_t1/b.pdf" filename="b.pdf"}`;
+        const keyToPath = new Map([
+            ['org_t1/a.png', 'images/a.png'],
+            ['org_t1/b.pdf', 'files/b.pdf'],
+        ]);
+        const exported = rewriteMediaRefs(original, (ref) => keyToPath.get(ref) ?? null);
+        expect(extractMediaRefs(exported).map((r) => r.ref)).toEqual([
+            'images/a.png',
+            'files/b.pdf',
+        ]);
+        const pathToKey = new Map([...keyToPath.entries()].map(([k, v]) => [v, k]));
+        const reimported = rewriteMediaRefs(exported, (ref) => pathToKey.get(ref) ?? null);
+        expect(reimported).toBe(original);
+    });
+});

package/dist/import-local.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Local GRAMMAR-markdown import runner (Phase 9a-3).
+ *
+ * The inverse of {@link runExport}: reads each local `.md` file VERBATIM as
+ * moxn-grammar markdown (front-matter + body + `:::image/:::csv/:::file/:::db`
+ * embeds), uploads any local media + rewrites the embed `ref`s from relative
+ * paths to STORAGE keys, then UPSERTs the document via the `import_markdown`
+ * action (over the shipped `replace_document` verb).
+ *
+ * This replaces the legacy blocks path (`LocalSource.extract` → MCP blocks →
+ * `create_document`) for the LOCAL source only. Notion/OneNote stay on blocks
+ * (they migrate in 9b).
+ */
+import { MoxnClient } from './client.js';
+import { LocalSource } from './sources/local.js';
+import type { MigrationLog, MigrationOptions } from './types.js';
+/**
+ * Join a base path and a relative KB path into a single absolute KB path
+ * (mirrors MoxnClient.buildPath so the grammar import places docs identically
+ * to the blocks import). E.g. ("/imported", "subdir/doc") → "/imported/subdir/doc".
+ */
+export declare function joinKbPath(basePath: string, relativePath: string): string;
+/**
+ * Upload the local media files referenced by a grammar markdown string and
+ * rewrite each embed `ref` from its (relative or absolute) local path to the
+ * returned storage key. Refs that are external URLs, or whose file can't be
+ * read, are left untouched (logged). Returns the rewritten markdown + a count
+ * of uploaded files.
+ *
+ * `baseDir` is the directory of the source `.md` file — relative refs resolve
+ * against it (matching how the export wrote them, relative to the `.md`).
+ */
+export declare function uploadAndRewriteMedia(markdown: string, baseDir: string, client: MoxnClient): Promise<{
+    markdown: string;
+    uploaded: number;
+}>;
+/**
+ * Run a local grammar-markdown migration: discover files via LocalSource, then
+ * for each file upload its media + `import_markdown` it.
+ */
+export declare function runLocalGrammarMigration(source: LocalSource, options: MigrationOptions): Promise<MigrationLog>;

package/dist/import-local.js

@@ -0,0 +1,206 @@
+/**
+ * Local GRAMMAR-markdown import runner (Phase 9a-3).
+ *
+ * The inverse of {@link runExport}: reads each local `.md` file VERBATIM as
+ * moxn-grammar markdown (front-matter + body + `:::image/:::csv/:::file/:::db`
+ * embeds), uploads any local media + rewrites the embed `ref`s from relative
+ * paths to STORAGE keys, then UPSERTs the document via the `import_markdown`
+ * action (over the shipped `replace_document` verb).
+ *
+ * This replaces the legacy blocks path (`LocalSource.extract` → MCP blocks →
+ * `create_document`) for the LOCAL source only. Notion/OneNote stay on blocks
+ * (they migrate in 9b).
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { MoxnClient } from './client.js';
+import { extractMediaRefs, rewriteMediaRefs, } from './grammar-media.js';
+/**
+ * Join a base path and a relative KB path into a single absolute KB path
+ * (mirrors MoxnClient.buildPath so the grammar import places docs identically
+ * to the blocks import). E.g. ("/imported", "subdir/doc") → "/imported/subdir/doc".
+ */
+export function joinKbPath(basePath, relativePath) {
+    const base = basePath.replace(/^\/+|\/+$/g, '');
+    const rel = relativePath.replace(/^\/+|\/+$/g, '');
+    return '/' + (base ? `${base}/${rel}` : rel);
+}
+/** Guess an upload MIME type from a media file's extension. */
+function mediaTypeFromPath(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    const map = {
+        '.png': 'image/png',
+        '.jpg': 'image/jpeg',
+        '.jpeg': 'image/jpeg',
+        '.gif': 'image/gif',
+        '.webp': 'image/webp',
+        '.svg': 'image/svg+xml',
+        '.pdf': 'application/pdf',
+        '.csv': 'text/csv',
+    };
+    return map[ext] || 'application/octet-stream';
+}
+/** True for an embed ref that is an external URL (left as-is, never uploaded). */
+function isExternalUrl(ref) {
+    return (ref.startsWith('http://') || ref.startsWith('https://') || ref.startsWith('data:'));
+}
+/**
+ * Upload the local media files referenced by a grammar markdown string and
+ * rewrite each embed `ref` from its (relative or absolute) local path to the
+ * returned storage key. Refs that are external URLs, or whose file can't be
+ * read, are left untouched (logged). Returns the rewritten markdown + a count
+ * of uploaded files.
+ *
+ * `baseDir` is the directory of the source `.md` file — relative refs resolve
+ * against it (matching how the export wrote them, relative to the `.md`).
+ */
+export async function uploadAndRewriteMedia(markdown, baseDir, client) {
+    const refs = extractMediaRefs(markdown);
+    if (refs.length === 0)
+        return { markdown, uploaded: 0 };
+    // Resolve each UNIQUE local ref → storage key (skip externals/missing).
+    const refToKey = new Map();
+    let uploaded = 0;
+    for (const { ref } of refs) {
+        if (refToKey.has(ref) || isExternalUrl(ref))
+            continue;
+        const localPath = path.isAbsolute(ref) ? ref : path.join(baseDir, ref);
+        let data;
+        try {
+            data = await fs.readFile(localPath);
+        }
+        catch {
+            console.error(`  ✗ Media not found, leaving ref as-is: ${ref}`);
+            continue;
+        }
+        const mediaType = mediaTypeFromPath(localPath);
+        const filename = path.basename(localPath);
+        try {
+            const { key } = await client.uploadFile(data, mediaType, filename);
+            refToKey.set(ref, key);
+            uploaded++;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`  ✗ Media upload failed, leaving ref as-is: ${ref}: ${msg}`);
+        }
+    }
+    const rewritten = rewriteMediaRefs(markdown, (ref, _directive) => refToKey.get(ref) ?? null);
+    return { markdown: rewritten, uploaded };
+}
+/**
+ * Run a local grammar-markdown migration: discover files via LocalSource, then
+ * for each file upload its media + `import_markdown` it.
+ */
+export async function runLocalGrammarMigration(source, options) {
+    const startTime = Date.now();
+    const results = [];
+    await source.validate();
+    const totalCount = await source.getDocumentCount();
+    const client = new MoxnClient(options);
+    let processed = 0;
+    let consecutiveFailures = 0;
+    const MAX_CONSECUTIVE_FAILURES = 10;
+    for await (const file of source.extractGrammarFiles()) {
+        processed++;
+        const progress = totalCount ? ` (${processed}/${totalCount})` : '';
+        console.log(`Processing: ${file.sourcePath}${progress}`);
+        const result = await migrateGrammarFile(client, file, options);
+        results.push(result);
+        if (result.status === 'failed') {
+            consecutiveFailures++;
+        }
+        else {
+            consecutiveFailures = 0;
+        }
+        const statusIcon = {
+            created: '✓',
+            updated: '↻',
+            skipped: '-',
+            failed: '✗',
+        }[result.status];
+        console.log(`  ${statusIcon} ${result.status}: ${result.documentPath}`);
+        if (result.error) {
+            console.log(`    Error: ${result.error}`);
+        }
+        if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+            console.error(`\nAborting: ${MAX_CONSECUTIVE_FAILURES} consecutive failures. ` +
+                'Last error: ' +
+                (result.error || 'unknown') +
+                '\nFix the underlying issue and retry. Remaining documents will be skipped.');
+            break;
+        }
+    }
+    const summary = {
+        total: results.length,
+        created: results.filter((r) => r.status === 'created').length,
+        updated: results.filter((r) => r.status === 'updated').length,
+        skipped: results.filter((r) => r.status === 'skipped').length,
+        failed: results.filter((r) => r.status === 'failed').length,
+        duration: Date.now() - startTime,
+    };
+    return {
+        timestamp: new Date().toISOString(),
+        source: { type: source.sourceType, location: source.sourceLocation },
+        targetApi: options.apiUrl,
+        basePath: options.basePath,
+        options: { dryRun: options.dryRun, onConflict: options.onConflict },
+        results,
+        summary,
+    };
+}
+/** Import a single grammar file: read → upload media → rewrite refs → import_markdown. */
+async function migrateGrammarFile(client, file, options) {
+    const startTime = Date.now();
+    const documentPath = joinKbPath(options.basePath, file.kbPath);
+    if (options.dryRun) {
+        return {
+            sourcePath: file.sourcePath,
+            documentPath,
+            status: 'skipped',
+            duration: Date.now() - startTime,
+        };
+    }
+    try {
+        const raw = await fs.readFile(file.fullPath, 'utf-8');
+        // Upload local media + rewrite embed refs (relative path → storage key)
+        // BEFORE import_markdown — the API boundary expects storage refs.
+        const { markdown } = await uploadAndRewriteMedia(raw, path.dirname(file.fullPath), client);
+        const res = await client.importMarkdown({
+            markdown,
+            // Destination hint: the PARENT sets the folder, the tail is only a name
+            // fallback. The server derives the final path from the name (front-matter
+            // name → first H1 → filename), so res.path may differ from this.
+            path: documentPath,
+            onConflict: options.onConflict,
+        });
+        // Surface a non-fatal warning when the file carried a front-matter block
+        // that wasn't applied (no `name` → body-only import): tags/description/etc.
+        // declared in it were ignored.
+        if (res.frontMatterIgnored) {
+            console.warn(`  ⚠ front-matter present but not applied (no \`name\`) — imported body only: ${file.sourcePath}`);
+        }
+        // Map import_markdown outcome → migration status.
+        const status = res.outcome === 'created'
+            ? 'created'
+            : res.outcome === 'updated'
+                ? 'updated'
+                : 'skipped';
+        return {
+            sourcePath: file.sourcePath,
+            documentPath: res.path || documentPath,
+            status,
+            documentId: res.id,
+            duration: Date.now() - startTime,
+        };
+    }
+    catch (error) {
+        return {
+            sourcePath: file.sourcePath,
+            documentPath,
+            status: 'failed',
+            error: error instanceof Error ? error.message : 'Unknown error',
+            duration: Date.now() - startTime,
+        };
+    }
+}

package/dist/import-local.test.d.ts

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

package/dist/import-local.test.js

@@ -0,0 +1,19 @@
+import { describe, it, expect } from 'vitest';
+import { joinKbPath } from './import-local.js';
+describe('joinKbPath', () => {
+    it('prefixes the relative KB path under a base path', () => {
+        expect(joinKbPath('/imported', 'subdir/doc')).toBe('/imported/subdir/doc');
+    });
+    it('treats base "/" as the root (no prefix segment)', () => {
+        expect(joinKbPath('/', 'doc')).toBe('/doc');
+    });
+    it('treats an empty base as the root', () => {
+        expect(joinKbPath('', 'guides/intro')).toBe('/guides/intro');
+    });
+    it('strips leading/trailing slashes from both parts', () => {
+        expect(joinKbPath('/base/', '/sub/doc/')).toBe('/base/sub/doc');
+    });
+    it('collapses redundant slashes at the join seam', () => {
+        expect(joinKbPath('base', 'doc')).toBe('/base/doc');
+    });
+});

package/dist/index.js

@@ -20,6 +20,7 @@ import { getPageTitle } from './sources/notion-blocks.js';
 import { slugify } from './sources/notion.js';
 import { MoxnClient } from './client.js';
 import { runExport } from './export.js';
+import { runLocalGrammarMigration } from './import-local.js';
 import { runNotionExport } from './export-notion.js';
 import { buildDateFilter } from './date-filter.js';
 const DEFAULT_API_URL = 'https://moxn.dev';
@@ -323,7 +324,11 @@ program
         dateFilter,
     };
     try {
-        const log = await runMigration(source, migrationOptions);
+        // Phase 9a-3: the local source now imports GRAMMAR markdown via
+        // `import_markdown` (read each .md verbatim, upload + rewrite media refs,
+        // UPSERT through replace_document) instead of parsing to MCP blocks +
+        // create_document. Notion/OneNote stay on the blocks runMigration path.
+        const log = await runLocalGrammarMigration(source, migrationOptions);
         if (opts.json) {
             console.log(JSON.stringify(log, null, 2));
         }
@@ -950,15 +955,9 @@ async function importNotionDatabase(client, dbImport, log, options, preCreatedDb
 }
 /**
  * Slugify a string for use as a tag path segment.
- * Similar to page slug but for the tag hierarchy.
+ * Delegates to the shared notion slugify so tags and page paths normalize identically.
  */
 function slugifyTagPath(s) {
-    return (s
-        .toLowerCase()
-        .trim()
-        .replace(/[^\w\s-]/g, '')
-        .replace(/[\s_]+/g, '-')
-        .replace(/-+/g, '-')
-        .replace(/^-|-$/g, '') || 'untitled');
+    return slugify(s);
 }
 program.parse();