@moxn/kb-migrate 0.4.41 → 0.5.0

package/dist/blocks-to-grammar.d.ts

@@ -0,0 +1,51 @@
+/**
+ * ContentBlock[] → grammar markdown serializer (Phase B of the write-surface
+ * tightening: the REST block-input path is retired; every import lands via
+ * `import_markdown`, the same grammar the export emits and the app's codec
+ * round-trips).
+ *
+ * The extractors (Notion / OneNote) keep producing ContentBlock sections —
+ * that stays a useful internal representation. This module is the WRITE
+ * BOUNDARY: it assumes media blocks have already been uploaded/re-hosted to
+ * storage keys (see `MoxnClient.processSections`, which now also re-hosts
+ * `url`/`base64` media) and reduces the sections to the `## H2` + `:::`
+ * directive grammar.
+ *
+ * Directive attr serialization REPLICATES the app codec
+ * (`src/lib/kb/grammar/attrs.ts` — kb-migrate is a separate package and
+ * cannot import it, same posture as grammar-media.ts): string → double-quoted
+ * with `&`→`&`, `"`→`"`; number → bare; string[] → `[a,b]` with
+ * `\` escaping for `\`, `,`, `]`.
+ */
+import type { ContentBlock } from './types.js';
+type AttrValue = string | number | string[] | null | undefined;
+/** Mirror of the app codec's `serializeAttrs` (src/lib/kb/grammar/attrs.ts). */
+export declare function serializeAttrs(obj: Record<string, AttrValue>): string;
+/**
+ * One ContentBlock → grammar chunk (markdown text or a `:::` directive line).
+ * Returns null for a block that cannot be expressed (e.g. base64 media that
+ * was not uploaded — the caller is expected to have re-hosted those first).
+ */
+export declare function blockToGrammar(block: ContentBlock): string | null;
+export interface SectionsToGrammarResult {
+    markdown: string;
+    /** Media blocks that could not be expressed (no storage key / URL). */
+    dropped: number;
+}
+/**
+ * Sections → grammar markdown BODY (no front-matter — the caller prepends
+ * it). Each section becomes an `## <name>` chunk; blocks join with blank
+ * lines, matching the H2-split the server applies on the way back in.
+ */
+export declare function sectionsToGrammarMarkdown(sections: Array<{
+    name: string;
+    content: ContentBlock[];
+}>): SectionsToGrammarResult;
+/**
+ * Minimal YAML front-matter for an import: `name` (+ optional description).
+ * `import_markdown` HONORS the front-matter (replace_document semantics on
+ * update — the import source is the source of truth for metadata).
+ * Values are JSON-quoted, which is valid YAML for scalar strings.
+ */
+export declare function buildImportFrontMatter(name: string, description?: string | null): string;
+export {};

package/dist/blocks-to-grammar.js

@@ -0,0 +1,133 @@
+/**
+ * ContentBlock[] → grammar markdown serializer (Phase B of the write-surface
+ * tightening: the REST block-input path is retired; every import lands via
+ * `import_markdown`, the same grammar the export emits and the app's codec
+ * round-trips).
+ *
+ * The extractors (Notion / OneNote) keep producing ContentBlock sections —
+ * that stays a useful internal representation. This module is the WRITE
+ * BOUNDARY: it assumes media blocks have already been uploaded/re-hosted to
+ * storage keys (see `MoxnClient.processSections`, which now also re-hosts
+ * `url`/`base64` media) and reduces the sections to the `## H2` + `:::`
+ * directive grammar.
+ *
+ * Directive attr serialization REPLICATES the app codec
+ * (`src/lib/kb/grammar/attrs.ts` — kb-migrate is a separate package and
+ * cannot import it, same posture as grammar-media.ts): string → double-quoted
+ * with `&`→`&`, `"`→`"`; number → bare; string[] → `[a,b]` with
+ * `\` escaping for `\`, `,`, `]`.
+ */
+function escapeArrayElement(v) {
+    return v.replace(/\\/g, '\\\\').replace(/,/g, '\\,').replace(/]/g, '\\]');
+}
+/** Mirror of the app codec's `serializeAttrs` (src/lib/kb/grammar/attrs.ts). */
+export function serializeAttrs(obj) {
+    const parts = [];
+    for (const [key, value] of Object.entries(obj)) {
+        if (value === null || value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            parts.push(`${key}=[${value.map(escapeArrayElement).join(',')}]`);
+        }
+        else if (typeof value === 'number') {
+            parts.push(`${key}=${value}`);
+        }
+        else {
+            const escaped = value.replace(/&/g, '&').replace(/"/g, '"');
+            parts.push(`${key}="${escaped}"`);
+        }
+    }
+    return parts.join(' ');
+}
+/** The `ref` a media block serializes: storage key first, else its URL. */
+function blockRef(block) {
+    if (block.type === 'storage' && block.key)
+        return block.key;
+    if (block.type === 'url' && block.url)
+        return block.url;
+    return null;
+}
+/**
+ * One ContentBlock → grammar chunk (markdown text or a `:::` directive line).
+ * Returns null for a block that cannot be expressed (e.g. base64 media that
+ * was not uploaded — the caller is expected to have re-hosted those first).
+ */
+export function blockToGrammar(block) {
+    switch (block.blockType) {
+        case 'text':
+            return block.text;
+        case 'image': {
+            const ref = blockRef(block);
+            if (!ref)
+                return null;
+            return `:::image{${serializeAttrs({
+                ref,
+                alt: block.alt,
+                mime: block.mediaType,
+            })}}`;
+        }
+        case 'document':
+        case 'file': {
+            const ref = blockRef(block);
+            if (!ref)
+                return null;
+            return `:::file{${serializeAttrs({
+                ref,
+                filename: 'filename' in block ? block.filename : undefined,
+                mime: block.mediaType,
+            })}}`;
+        }
+        case 'csv': {
+            const ref = blockRef(block);
+            if (!ref)
+                return null;
+            return `:::csv{${serializeAttrs({
+                ref,
+                filename: block.filename,
+                mime: 'text/csv',
+                headers: block.headers,
+                rowCount: block.rowCount,
+            })}}`;
+        }
+        case 'database_embed':
+            return `:::db{${serializeAttrs({ ref: block.databaseId })}}`;
+        default:
+            return null;
+    }
+}
+/**
+ * Sections → grammar markdown BODY (no front-matter — the caller prepends
+ * it). Each section becomes an `## <name>` chunk; blocks join with blank
+ * lines, matching the H2-split the server applies on the way back in.
+ */
+export function sectionsToGrammarMarkdown(sections) {
+    let dropped = 0;
+    const chunks = [];
+    for (const section of sections) {
+        const parts = [`## ${section.name}`];
+        for (const block of section.content) {
+            const chunk = blockToGrammar(block);
+            if (chunk === null) {
+                dropped++;
+                continue;
+            }
+            if (chunk.trim().length > 0)
+                parts.push(chunk.trim());
+        }
+        chunks.push(parts.join('\n\n'));
+    }
+    return { markdown: chunks.join('\n\n'), dropped };
+}
+/**
+ * Minimal YAML front-matter for an import: `name` (+ optional description).
+ * `import_markdown` HONORS the front-matter (replace_document semantics on
+ * update — the import source is the source of truth for metadata).
+ * Values are JSON-quoted, which is valid YAML for scalar strings.
+ */
+export function buildImportFrontMatter(name, description) {
+    const lines = [`name: ${JSON.stringify(name)}`];
+    if (description !== undefined && description !== null && description !== '') {
+        lines.push(`description: ${JSON.stringify(description)}`);
+    }
+    return `---\n${lines.join('\n')}\n---\n\n`;
+}

package/dist/client.d.ts

@@ -32,6 +32,10 @@ export interface ImportMarkdownResult {
      * lenient fallback recovered the name. Carries the js-yaml error message.
      */
     frontMatterError?: string;
+    /** Section anchor ids in POSITION ORDER after the upsert (for cross-refs). */
+    sectionIds?: string[];
+    /** The branch the upsert landed on (for branch-scoped follow-ups like tags). */
+    branchId?: string;
 }
 export declare class MoxnClient {
     private apiUrl;
@@ -42,6 +46,17 @@ export declare class MoxnClient {
     /**
      * Migrate a single document
      */
+    /**
+     * Migrate one extracted document via `import_markdown` (Phase B of the
+     * write-surface tightening — the REST block-input path is retired).
+     *
+     * Flow: upload/re-host every media block (local files, base64 payloads,
+     * remote URLs) → serialize the sections to grammar markdown → prepend a
+     * name/description front-matter → UPSERT via `import_markdown`
+     * (create-or-replace_document; `onConflict: 'skip'` skips an existing
+     * path). Idempotent: a byte-identical re-import is reported as a no-op
+     * update by the server.
+     */
     migrateDocument(doc: ExtractedDocument, basePath: string, onConflict: 'skip' | 'update', dryRun: boolean): Promise<MigrationResult>;
     /**
      * List all documents, optionally filtered by path prefix.
@@ -102,8 +117,6 @@ export declare class MoxnClient {
         key: string;
     }>;
     private getUploadUrl;
-    private createDocument;
-    private updateDocument;
     /**
      * Create a KB database.
      */
@@ -263,5 +276,4 @@ export declare class MoxnClient {
         id: string;
         name: string;
     } | null>;
-    private isConflictError;
 }

package/dist/client.js

@@ -3,6 +3,7 @@
  */
 import * as fs from 'fs/promises';
 import { formatApiError } from './api-error.js';
+import { sectionsToGrammarMarkdown, buildImportFrontMatter, } from './blocks-to-grammar.js';
 export class MoxnClient {
     apiUrl;
     apiKey;
@@ -21,6 +22,17 @@ export class MoxnClient {
     /**
      * Migrate a single document
      */
+    /**
+     * Migrate one extracted document via `import_markdown` (Phase B of the
+     * write-surface tightening — the REST block-input path is retired).
+     *
+     * Flow: upload/re-host every media block (local files, base64 payloads,
+     * remote URLs) → serialize the sections to grammar markdown → prepend a
+     * name/description front-matter → UPSERT via `import_markdown`
+     * (create-or-replace_document; `onConflict: 'skip'` skips an existing
+     * path). Idempotent: a byte-identical re-import is reported as a no-op
+     * update by the server.
+     */
     async migrateDocument(doc, basePath, onConflict, dryRun) {
         const startTime = Date.now();
         const documentPath = this.buildPath(basePath, doc.relativePath);
@@ -34,91 +46,36 @@ export class MoxnClient {
             };
         }
         try {
-            // Process content blocks (convert file paths to base64)
+            // Upload/re-host media (local paths, base64, remote URLs) → storage keys.
             const processedSections = await this.processSections(doc.sections);
-            // Try to create the document
-            const createResult = await this.createDocument({
+            const { markdown: body, dropped } = sectionsToGrammarMarkdown(processedSections);
+            if (dropped > 0) {
+                console.error(`  ! ${dropped} media block(s) had no uploadable payload and were dropped: ${doc.sourcePath}`);
+            }
+            const markdown = buildImportFrontMatter(doc.name, doc.description) + body;
+            const result = await this.importMarkdown({
+                markdown,
                 path: documentPath,
-                name: doc.name,
-                description: doc.description,
-                defaultPermission: this.defaultPermission,
-                aiAccess: this.aiAccess,
-                sections: processedSections,
+                onConflict,
             });
             return {
                 sourcePath: doc.sourcePath,
-                documentPath,
-                status: 'created',
-                documentId: createResult.id,
-                branchId: createResult.branchId,
-                sectionsCount: createResult.sections.length,
-                sectionIds: createResult.sections.map((s) => s.id),
+                documentPath: result.path,
+                status: result.outcome === 'created'
+                    ? 'created'
+                    : result.outcome === 'updated'
+                        ? 'updated'
+                        : 'skipped',
+                documentId: result.id,
+                branchId: result.branchId,
+                sectionsCount: result.sectionIds?.length,
+                sectionIds: result.sectionIds,
                 references: doc.references,
                 sourcePageId: doc.metadata?.notionPageId,
                 duration: Date.now() - startTime,
             };
         }
         catch (error) {
-            // Check for conflict (409)
-            if (this.isConflictError(error)) {
-                if (onConflict === 'skip') {
-                    return {
-                        sourcePath: doc.sourcePath,
-                        documentPath,
-                        status: 'skipped',
-                        documentId: error.documentId,
-                        branchId: error.branchId,
-                        duration: Date.now() - startTime,
-                    };
-                }
-                // Update existing document
-                try {
-                    const processedSections = await this.processSections(doc.sections);
-                    const updateResult = await this.updateDocument(error.documentId, {
-                        name: doc.name,
-                        description: doc.description,
-                        sections: processedSections,
-                    });
-                    return {
-                        sourcePath: doc.sourcePath,
-                        documentPath,
-                        status: 'updated',
-                        documentId: updateResult.id,
-                        branchId: updateResult.branchId,
-                        sectionsCount: updateResult.sections.length,
-                        sectionIds: updateResult.sections.map((s) => s.id),
-                        references: doc.references,
-                        sourcePageId: doc.metadata?.notionPageId,
-                        duration: Date.now() - startTime,
-                    };
-                }
-                catch (updateError) {
-                    // Re-importing BYTE-IDENTICAL content makes the server reject the
-                    // empty commit ("No changes to commit"). For an importer that's a
-                    // NO-OP, not a failure — report a successful (no-op) update, matching
-                    // the grammar path's idempotent re-import. (Audit finding B.)
-                    const msg = updateError instanceof Error ? updateError.message : '';
-                    if (msg.includes('No changes to commit')) {
-                        return {
-                            sourcePath: doc.sourcePath,
-                            documentPath,
-                            status: 'updated',
-                            documentId: error.documentId,
-                            branchId: error.branchId,
-                            sourcePageId: doc.metadata?.notionPageId,
-                            duration: Date.now() - startTime,
-                        };
-                    }
-                    return {
-                        sourcePath: doc.sourcePath,
-                        documentPath,
-                        status: 'failed',
-                        documentId: error.documentId,
-                        error: updateError instanceof Error ? updateError.message : 'Update failed',
-                        duration: Date.now() - startTime,
-                    };
-                }
-            }
             return {
                 sourcePath: doc.sourcePath,
                 documentPath,
@@ -358,6 +315,45 @@ export class MoxnClient {
                     filename: block.filename,
                 };
             }
+            // Base64 payloads (extractors that inline-downloaded media) → upload.
+            if ((block.blockType === 'image' ||
+                block.blockType === 'document' ||
+                block.blockType === 'csv' ||
+                block.blockType === 'file') &&
+                block.type === 'base64' &&
+                block.base64) {
+                const data = Buffer.from(block.base64, 'base64');
+                const filename = ('filename' in block ? block.filename : undefined) || 'media';
+                const { key } = await this.uploadFile(data, block.mediaType || 'application/octet-stream', filename);
+                return { ...block, type: 'storage', key, base64: undefined };
+            }
+            // Remote URLs (e.g. expiring Notion signed URLs) → download + re-host,
+            // matching the durability the server-side blocksToTipTap re-hosting
+            // used to provide. A failed download keeps the URL ref (the grammar
+            // carries external URLs) rather than failing the document.
+            if ((block.blockType === 'image' ||
+                block.blockType === 'document' ||
+                block.blockType === 'csv' ||
+                block.blockType === 'file') &&
+                block.type === 'url' &&
+                block.url) {
+                try {
+                    const response = await fetch(block.url);
+                    if (!response.ok)
+                        throw new Error(`HTTP ${response.status}`);
+                    const data = Buffer.from(await response.arrayBuffer());
+                    const filename = ('filename' in block ? block.filename : undefined) ||
+                        new URL(block.url).pathname.split('/').pop() ||
+                        'media';
+                    const { key } = await this.uploadFile(data, block.mediaType || 'application/octet-stream', filename);
+                    return { ...block, type: 'storage', key, url: undefined };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    console.error(`  ! media re-host failed, keeping external URL ref: ${block.url}: ${msg}`);
+                    return block;
+                }
+            }
             return block;
         }));
     }
@@ -394,42 +390,6 @@ export class MoxnClient {
         const data = await response.json();
         return { key: data.key, uploadUrl: data.uploadUrl };
     }
-    async createDocument(request) {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/documents`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'x-api-key': this.apiKey,
-            },
-            body: JSON.stringify(request),
-        });
-        if (!response.ok) {
-            const body = await response.json().catch(() => ({}));
-            if (response.status === 409 && body.documentId) {
-                const error = new Error(body.error || 'Document already exists');
-                error.documentId = body.documentId;
-                error.branchId = body.branchId;
-                throw error;
-            }
-            throw new Error(formatApiError(response.status, body));
-        }
-        return response.json();
-    }
-    async updateDocument(documentId, request) {
-        const response = await fetch(`${this.apiUrl}/api/v1/kb/documents/${documentId}`, {
-            method: 'PUT',
-            headers: {
-                'Content-Type': 'application/json',
-                'x-api-key': this.apiKey,
-            },
-            body: JSON.stringify(request),
-        });
-        if (!response.ok) {
-            const body = await response.json().catch(() => ({}));
-            throw new Error(formatApiError(response.status, body));
-        }
-        return response.json();
-    }
     // ──────────────────────────────────────────────
     // Database & tag methods (for Notion import)
     // ──────────────────────────────────────────────
@@ -670,11 +630,4 @@ export class MoxnClient {
         const databases = await this.listDatabases();
         return databases.find((db) => db.id === databaseId) ?? null;
     }
-    isConflictError(error) {
-        return (error instanceof Error &&
-            'documentId' in error &&
-            'branchId' in error &&
-            typeof error.documentId === 'string' &&
-            typeof error.branchId === 'string');
-    }
 }

package/dist/migrate-document.test.js

@@ -1,5 +1,6 @@
 import { describe, it, expect, vi, afterEach } from 'vitest';
 import { MoxnClient } from './client.js';
+import { sectionsToGrammarMarkdown, buildImportFrontMatter, blockToGrammar, } from './blocks-to-grammar.js';
 /** Minimal fetch Response stand-in (client reads .ok/.status/.json()). */
 function mockResponse(status, body) {
     return {
@@ -25,22 +26,59 @@ function client() {
     });
 }
 afterEach(() => vi.restoreAllMocks());
-describe('migrateDocument — finding B: unchanged re-import is a no-op, not a failure', () => {
-    it("treats the server's 'No changes to commit' on update as a no-op success", async () => {
-        // create → 409 (path exists, id recovered) → update → 400 No-changes.
+describe('migrateDocument — grammar-markdown import (write-surface Phase B)', () => {
+    it('serializes sections to grammar markdown and UPSERTs via import_markdown', async () => {
+        let importBody;
         vi.spyOn(globalThis, 'fetch').mockImplementation((async (url, init) => {
             const u = String(url);
             const method = (init?.method ?? 'GET').toUpperCase();
-            if (method === 'POST' && u.endsWith('/api/v1/kb/documents')) {
-                return mockResponse(409, {
-                    error: 'exists',
-                    documentId: 'doc-1',
-                    branchId: 'br-1',
+            if (method === 'POST' && u.endsWith('/api/v1/kb/import')) {
+                importBody = JSON.parse(String(init?.body));
+                return mockResponse(200, {
+                    result: {
+                        id: 'doc-1',
+                        path: '/runbook',
+                        outcome: 'created',
+                        existed: false,
+                        name: 'Runbook',
+                        frontMatterIgnored: false,
+                        sectionIds: ['s1'],
+                        branchId: 'br-1',
+                    },
                 });
             }
-            if (method === 'PUT' && u.includes('/api/v1/kb/documents/')) {
-                return mockResponse(400, {
-                    error: 'No changes to commit — working hash equals head body hash',
+            return mockResponse(200, {});
+        }));
+        const res = await client().migrateDocument(doc, '/', 'update', false);
+        expect(res.status).toBe('created');
+        expect(res.documentId).toBe('doc-1');
+        expect(res.branchId).toBe('br-1');
+        expect(res.sectionIds).toEqual(['s1']);
+        // POSITIVE wire assertion: the retired blocks payload is GONE; the body is
+        // grammar markdown with the name front-matter + H2 sections.
+        expect(importBody?.action).toBe('import_markdown');
+        const md = String(importBody?.markdown);
+        expect(md).toContain('name: "Runbook"');
+        expect(md).toContain('## Steps');
+        expect(md).toContain('body');
+        expect(importBody).not.toHaveProperty('sections');
+    });
+    it("maps the server's no-op re-import (outcome 'updated') to an updated result", async () => {
+        // The old client-side "No changes to commit" special-case moved server-side:
+        // import_markdown swallows the empty-commit rejection and reports 'updated'.
+        vi.spyOn(globalThis, 'fetch').mockImplementation((async (url, init) => {
+            const u = String(url);
+            const method = (init?.method ?? 'GET').toUpperCase();
+            if (method === 'POST' && u.endsWith('/api/v1/kb/import')) {
+                return mockResponse(200, {
+                    result: {
+                        id: 'doc-1',
+                        path: '/runbook',
+                        outcome: 'updated',
+                        existed: true,
+                        name: 'Runbook',
+                        frontMatterIgnored: false,
+                    },
                 });
             }
             return mockResponse(200, {});
@@ -49,22 +87,64 @@ describe('migrateDocument — finding B: unchanged re-import is a no-op, not a f
         expect(res.status).toBe('updated'); // NOT 'failed'
         expect(res.documentId).toBe('doc-1');
     });
-    it('still reports a genuine update error as failed', async () => {
+    it('still reports a genuine import error as failed', async () => {
         vi.spyOn(globalThis, 'fetch').mockImplementation((async (url, init) => {
             const u = String(url);
             const method = (init?.method ?? 'GET').toUpperCase();
-            if (method === 'POST' && u.endsWith('/api/v1/kb/documents')) {
-                return mockResponse(409, {
-                    error: 'exists',
-                    documentId: 'doc-1',
-                    branchId: 'br-1',
-                });
-            }
-            if (method === 'PUT')
+            if (method === 'POST' && u.endsWith('/api/v1/kb/import')) {
                 return mockResponse(500, { error: 'boom' });
+            }
             return mockResponse(200, {});
         }));
         const res = await client().migrateDocument(doc, '/', 'update', false);
         expect(res.status).toBe('failed');
     });
 });
+describe('blocks-to-grammar serializer', () => {
+    it('serializes media blocks to ::: directives (storage key first, url fallback)', () => {
+        expect(blockToGrammar({
+            blockType: 'image',
+            type: 'storage',
+            key: 'tenant_1/img.png',
+            mediaType: 'image/png',
+            alt: 'diagram',
+        })).toBe(':::image{ref="tenant_1/img.png" alt="diagram" mime="image/png"}');
+        expect(blockToGrammar({
+            blockType: 'image',
+            type: 'url',
+            url: 'https://example.test/pic.png',
+            mediaType: 'image/png',
+        })).toBe(':::image{ref="https://example.test/pic.png" mime="image/png"}');
+        expect(blockToGrammar({ blockType: 'database_embed', databaseId: 'db-1' })).toBe(':::db{ref="db-1"}');
+        expect(blockToGrammar({
+            blockType: 'csv',
+            type: 'storage',
+            key: 'tenant_1/data.csv',
+            mediaType: 'text/csv',
+            filename: 'data.csv',
+            headers: ['a', 'b'],
+            rowCount: 3,
+        })).toBe(':::csv{ref="tenant_1/data.csv" filename="data.csv" mime="text/csv" headers=[a,b] rowCount=3}');
+    });
+    it('drops media with no expressible ref and counts it', () => {
+        const { markdown, dropped } = sectionsToGrammarMarkdown([
+            {
+                name: 'S',
+                content: [
+                    { blockType: 'text', text: 'kept' },
+                    {
+                        blockType: 'image',
+                        type: 'base64',
+                        base64: 'xxxx',
+                        mediaType: 'image/png',
+                    },
+                ],
+            },
+        ]);
+        expect(dropped).toBe(1);
+        expect(markdown).toBe('## S\n\nkept');
+    });
+    it('front-matter escapes names safely (JSON-quoted scalars)', () => {
+        expect(buildImportFrontMatter('He said "hi": ok')).toBe('---\nname: "He said \\"hi\\": ok"\n---\n\n');
+    });
+});

package/dist/sources/onenote/__tests__/onenote-tree.test.d.ts

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

package/dist/sources/onenote/__tests__/onenote-tree.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest';
+import { discoverOneNotePages, slugifyPathSegment } from '../onenote-tree.js';
+/** Minimal OneNoteApiClient: one notebook, no groups, pages routed by section. */
+function mockClient(sectionPages) {
+    const sections = Object.keys(sectionPages).map((id) => ({ id, displayName: id }));
+    return {
+        listNotebooks: async () => [{ id: 'nb1', displayName: 'Notebook' }],
+        listSectionGroups: async () => [],
+        listSectionsInNotebook: async () => sections,
+        listSectionsInGroup: async () => [],
+        listPages: async (sectionId) => sectionPages[sectionId] ?? [],
+    };
+}
+describe('discoverOneNotePages — dedup same-titled sibling pages (finding D, #203)', () => {
+    it('two same-titled pages in ONE section get distinct paths + disambiguated titles', async () => {
+        const out = await discoverOneNotePages(mockClient({
+            sec1: [
+                { id: 'p1', title: 'Notes' },
+                { id: 'p2', title: 'Notes' },
+            ],
+        }));
+        expect(out).toHaveLength(2);
+        // Distinct paths — the collision (data loss) is gone.
+        expect(new Set(out.map((p) => p.kbPath)).size).toBe(2);
+        // Second sibling disambiguated.
+        expect(out.map((p) => p.title).sort()).toEqual(['Notes', 'Notes 2']);
+        // The server's bijection invariant: pathTail === slug(name).
+        for (const p of out) {
+            expect(p.kbPath.split('/').pop()).toBe(slugifyPathSegment(p.title));
+        }
+    });
+    it('same title in DIFFERENT sections is NOT deduped (counter is per-section)', async () => {
+        const out = await discoverOneNotePages(mockClient({
+            secA: [{ id: 'p1', title: 'Notes' }],
+            secB: [{ id: 'p2', title: 'Notes' }],
+        }));
+        expect(out).toHaveLength(2);
+        // Both keep the plain title (no cross-section suffixing)...
+        expect(out.map((p) => p.title)).toEqual(['Notes', 'Notes']);
+        // ...and the section segment already makes the paths distinct.
+        expect(new Set(out.map((p) => p.kbPath)).size).toBe(2);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moxn/kb-migrate",
-  "version": "0.4.41",
+  "version": "0.5.0",
   "description": "Migration tool for importing documents into Moxn Knowledge Base from local files, Notion, Google Docs, and more",
   "type": "module",
   "main": "dist/index.js",
@@ -155,4 +155,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}