@moxn/kb-migrate 0.4.41 → 0.6.0

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/output.d.ts

@@ -0,0 +1,17 @@
+/**
+ * This package's version, read from its package.json at runtime (src/ and
+ * dist/ both sit one level below it). Reported by `--version`, on stderr at
+ * the start of every command, and on every JSON log — so a stale npx
+ * resolution of an old kb-migrate is visible instead of silent.
+ */
+export declare function packageVersion(): string;
+/**
+ * Route console.log to stderr until {@link exitJsonMode}. The CLI enters it
+ * from a preAction hook for any command run with `--json`.
+ */
+export declare function enterJsonMode(): void;
+export declare function exitJsonMode(): void;
+/** Run `fn` with console.log routed to stderr when `json` is set. */
+export declare function withJsonStdout<T>(json: boolean, fn: () => Promise<T>): Promise<T>;
+/** Write a command's JSON log to stdout, stamped with the kb-migrate version. */
+export declare function emitJson(log: object): void;

package/dist/output.js

@@ -0,0 +1,65 @@
+/**
+ * Process-output helpers for the kb-migrate CLI.
+ *
+ * `--json` promises stdout is ONE JSON document — `context import-local
+ * --json` and friends parse it. Progress lines are printed with console.log
+ * all through the runners, so JSON mode routes console.log to stderr for the
+ * duration of the run and writes the log itself straight to stdout.
+ */
+import * as fs from 'fs';
+import { format } from 'util';
+let cachedVersion;
+/**
+ * This package's version, read from its package.json at runtime (src/ and
+ * dist/ both sit one level below it). Reported by `--version`, on stderr at
+ * the start of every command, and on every JSON log — so a stale npx
+ * resolution of an old kb-migrate is visible instead of silent.
+ */
+export function packageVersion() {
+    if (cachedVersion === undefined) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
+            cachedVersion = pkg.version ?? 'unknown';
+        }
+        catch {
+            cachedVersion = 'unknown';
+        }
+    }
+    return cachedVersion;
+}
+let restoreLog;
+/**
+ * Route console.log to stderr until {@link exitJsonMode}. The CLI enters it
+ * from a preAction hook for any command run with `--json`.
+ */
+export function enterJsonMode() {
+    if (restoreLog)
+        return;
+    const original = console.log;
+    console.log = (...args) => {
+        process.stderr.write(`${format(...args)}\n`);
+    };
+    restoreLog = () => {
+        console.log = original;
+    };
+}
+export function exitJsonMode() {
+    restoreLog?.();
+    restoreLog = undefined;
+}
+/** Run `fn` with console.log routed to stderr when `json` is set. */
+export async function withJsonStdout(json, fn) {
+    if (!json)
+        return fn();
+    enterJsonMode();
+    try {
+        return await fn();
+    }
+    finally {
+        exitJsonMode();
+    }
+}
+/** Write a command's JSON log to stdout, stamped with the kb-migrate version. */
+export function emitJson(log) {
+    process.stdout.write(`${JSON.stringify({ kbMigrateVersion: packageVersion(), ...log }, null, 2)}\n`);
+}

package/dist/output.test.d.ts

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

package/dist/output.test.js

@@ -0,0 +1,59 @@
+/**
+ * `--json` output contract + version reporting.
+ *
+ * - `kb-migrate local --json` printed `Processing: …` progress on STDOUT ahead
+ *   of the JSON log, so `context import-local --json` was not parseable. In
+ *   JSON mode stdout carries the log and nothing else; progress goes to stderr.
+ * - `--version` was hardcoded `0.1.0`, so a stale npx resolution (a cached
+ *   0.4.x exporter, prod 2026-09-25) was undiagnosable. The real package
+ *   version is reported, and stamped on every JSON log.
+ */
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import * as fs from 'fs';
+import { emitJson, packageVersion, withJsonStdout } from './output.js';
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+describe('packageVersion', () => {
+    it('is the version in package.json, not a hardcoded placeholder', () => {
+        const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
+        expect(packageVersion()).toBe(pkg.version);
+        expect(packageVersion()).not.toBe('0.1.0');
+    });
+});
+describe('JSON mode stdout', () => {
+    function capture() {
+        const stdout = [];
+        const stderr = [];
+        vi.spyOn(process.stdout, 'write').mockImplementation(((c) => {
+            stdout.push(String(c));
+            return true;
+        }));
+        vi.spyOn(process.stderr, 'write').mockImplementation(((c) => {
+            stderr.push(String(c));
+            return true;
+        }));
+        return { stdout, stderr };
+    }
+    it('routes progress (console.log) to stderr while the run is in JSON mode', async () => {
+        const { stdout, stderr } = capture();
+        await withJsonStdout(true, async () => {
+            console.log('Processing: a.md (1/1)');
+        });
+        emitJson({ summary: { total: 1 } });
+        const out = stdout.join('');
+        const parsed = JSON.parse(out);
+        expect(parsed.summary.total).toBe(1);
+        expect(parsed.kbMigrateVersion).toBe(packageVersion());
+        expect(out).not.toContain('Processing');
+        expect(stderr.join('')).toContain('Processing: a.md');
+    });
+    it('restores console.log afterwards, and leaves it alone outside JSON mode', async () => {
+        const original = console.log;
+        await withJsonStdout(true, async () => { });
+        expect(console.log).toBe(original);
+        await withJsonStdout(false, async () => {
+            expect(console.log).toBe(original);
+        });
+    });
+});

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/dist/targets/notion.js

@@ -11,6 +11,7 @@
  * Conflict detection uses the MoxnClient's notion-mapping API endpoints
  * (when available) to find existing Notion pages for a KB document.
  */
+import { moxnFetch } from '../http.js';
 import { Client } from '@notionhq/client';
 import { markdownToBlocks } from '@tryfabric/martian';
 import { ExportTarget, } from './base.js';
@@ -744,7 +745,7 @@ export class NotionExportTarget extends ExportTarget {
             return cached;
         // Try notion-mapping API
         try {
-            const response = await fetch(`${this.config.apiUrl}/api/v1/kb/notion-mappings/by-document/${kbDocumentId}`, {
+            const response = await moxnFetch(`${this.config.apiUrl}/api/v1/kb/notion-mappings/by-document/${kbDocumentId}`, {
                 headers: { 'x-api-key': this.config.apiKey },
             });
             if (response.ok) {
@@ -764,7 +765,7 @@ export class NotionExportTarget extends ExportTarget {
         this.mappingCache.set(kbDocumentId, notionPageId);
         // Try to save mapping via API (best-effort)
         try {
-            await fetch(`${this.config.apiUrl}/api/v1/kb/notion-mappings`, {
+            await moxnFetch(`${this.config.apiUrl}/api/v1/kb/notion-mappings`, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',

package/dist/types.d.ts

@@ -146,6 +146,8 @@ export interface MigrationResult {
     /** Source page ID (e.g. Notion page ID) for building cross-ref mappings */
     sourcePageId?: string;
     error?: string;
+    /** Non-fatal: the document landed, but not everything asked for applied. */
+    warning?: string;
     duration?: number;
 }
 /**
@@ -276,8 +278,10 @@ export interface ListResponse {
 export interface ExportResult {
     documentId: string;
     documentPath: string;
+    /** Directory-relative output file; empty when nothing was written. */
     outputFile: string;
-    status: 'exported' | 'failed';
+    /** 'skipped': a kind with no local export format (nothing written). */
+    status: 'exported' | 'failed' | 'skipped';
     sectionsCount: number;
     mediaFiles: string[];
     error?: string;
@@ -302,6 +306,7 @@ export interface ExportLog {
         total: number;
         exported: number;
         failed: number;
+        skipped: number;
         mediaDownloaded: number;
         duration: number;
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moxn/kb-migrate",
-  "version": "0.4.41",
+  "version": "0.6.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",
@@ -112,6 +112,7 @@
   "dependencies": {
     "@azure/msal-node": "^3.8.10",
     "@microsoft/microsoft-graph-client": "^3.0.7",
+    "@moxn/auth": "^0.1.0",
     "@moxn/kb-migrate": "^0.4.14",
     "@notionhq/client": "^5.9.0",
     "@tryfabric/martian": "^1.2.4",
@@ -155,4 +156,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}