@moxn/kb-migrate 0.4.39 → 0.4.41

package/dist/client.d.ts

@@ -27,6 +27,11 @@ export interface ImportMarkdownResult {
     name?: string;
     /** True when a front-matter block was present but NOT applied (no name → body-only import). */
     frontMatterIgnored?: boolean;
+    /**
+     * Set when strict YAML parsing of the front-matter block failed, even if the
+     * lenient fallback recovered the name. Carries the js-yaml error message.
+     */
+    frontMatterError?: string;
 }
 export declare class MoxnClient {
     private apiUrl;

package/dist/import-local.js

@@ -100,13 +100,16 @@ export async function runLocalGrammarMigration(source, options) {
     const client = new MoxnClient(options);
     let processed = 0;
     let consecutiveFailures = 0;
+    let fmIgnoredOrDegraded = 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);
+        const { result, hadFmWarning } = await migrateGrammarFile(client, file, options);
         results.push(result);
+        if (hadFmWarning)
+            fmIgnoredOrDegraded++;
         if (result.status === 'failed') {
             consecutiveFailures++;
         }
@@ -138,6 +141,7 @@ export async function runLocalGrammarMigration(source, options) {
         skipped: results.filter((r) => r.status === 'skipped').length,
         failed: results.filter((r) => r.status === 'failed').length,
         duration: Date.now() - startTime,
+        ...(fmIgnoredOrDegraded > 0 ? { fmIgnoredOrDegraded } : {}),
     };
     return {
         timestamp: new Date().toISOString(),
@@ -155,10 +159,13 @@ async function migrateGrammarFile(client, file, options) {
     const documentPath = joinKbPath(options.basePath, file.kbPath);
     if (options.dryRun) {
         return {
-            sourcePath: file.sourcePath,
-            documentPath,
-            status: 'skipped',
-            duration: Date.now() - startTime,
+            result: {
+                sourcePath: file.sourcePath,
+                documentPath,
+                status: 'skipped',
+                duration: Date.now() - startTime,
+            },
+            hadFmWarning: false,
         };
     }
     try {
@@ -175,11 +182,18 @@ async function migrateGrammarFile(client, file, options) {
             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.
+        // that wasn't applied (no `name` → body-only import), OR when strict YAML
+        // parsing failed (even if the lenient fallback recovered the name, some
+        // metadata like tags/properties may have been lost).
+        let hadFmWarning = false;
         if (res.frontMatterIgnored) {
+            hadFmWarning = true;
             console.warn(`  ⚠ front-matter present but not applied (no \`name\`) — imported body only: ${file.sourcePath}`);
         }
+        else if (res.frontMatterError) {
+            hadFmWarning = true;
+            console.warn(`  ⚠ front-matter YAML parse error (tags/properties may be missing): ${res.frontMatterError} — ${file.sourcePath}`);
+        }
         // Map import_markdown outcome → migration status.
         const status = res.outcome === 'created'
             ? 'created'
@@ -187,20 +201,26 @@ async function migrateGrammarFile(client, file, options) {
                 ? 'updated'
                 : 'skipped';
         return {
-            sourcePath: file.sourcePath,
-            documentPath: res.path || documentPath,
-            status,
-            documentId: res.id,
-            duration: Date.now() - startTime,
+            result: {
+                sourcePath: file.sourcePath,
+                documentPath: res.path || documentPath,
+                status,
+                documentId: res.id,
+                duration: Date.now() - startTime,
+            },
+            hadFmWarning,
         };
     }
     catch (error) {
         return {
-            sourcePath: file.sourcePath,
-            documentPath,
-            status: 'failed',
-            error: error instanceof Error ? error.message : 'Unknown error',
-            duration: Date.now() - startTime,
+            result: {
+                sourcePath: file.sourcePath,
+                documentPath,
+                status: 'failed',
+                error: error instanceof Error ? error.message : 'Unknown error',
+                duration: Date.now() - startTime,
+            },
+            hadFmWarning: false,
         };
     }
 }

package/dist/import-local.test.js

@@ -1,5 +1,9 @@
-import { describe, it, expect } from 'vitest';
-import { joinKbPath } from './import-local.js';
+import { describe, it, expect, vi, afterEach, beforeEach, } from 'vitest';
+import { joinKbPath, runLocalGrammarMigration } from './import-local.js';
+// Mock fs/promises at module level so readFile is consistently stubable.
+vi.mock('fs/promises', () => ({
+    readFile: vi.fn().mockResolvedValue('---\nname: test-doc\n---\n\n## Body\n\ncontent'),
+}));
 describe('joinKbPath', () => {
     it('prefixes the relative KB path under a base path', () => {
         expect(joinKbPath('/imported', 'subdir/doc')).toBe('/imported/subdir/doc');
@@ -17,3 +21,99 @@ describe('joinKbPath', () => {
         expect(joinKbPath('base', 'doc')).toBe('/base/doc');
     });
 });
+// ─────────────────────────────────────────────────────────────────────────────
+// FM warning + summary count tests
+// ─────────────────────────────────────────────────────────────────────────────
+const BASE_OPTIONS = {
+    apiUrl: 'http://test-api',
+    apiKey: 'test-key',
+    basePath: '/imported',
+    onConflict: 'update',
+    dryRun: false,
+};
+function mockResponse(status, body) {
+    return {
+        ok: status >= 200 && status < 300,
+        status,
+        json: async () => body,
+    };
+}
+function fakeSource(kbPath = 'my-doc.md') {
+    return {
+        sourceType: 'local',
+        sourceLocation: '/fake',
+        validate: async () => { },
+        getDocumentCount: async () => 1,
+        async *extractGrammarFiles() {
+            yield {
+                fullPath: '/fake/my-doc.md',
+                sourcePath: 'my-doc.md',
+                kbPath,
+            };
+        },
+    };
+}
+describe('runLocalGrammarMigration — FM warning surface + summary count', () => {
+    let warnSpy;
+    let logSpy;
+    let fetchSpy;
+    beforeEach(() => {
+        warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        fetchSpy = vi.spyOn(globalThis, 'fetch');
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('includes frontMatterError text in the console warning when server returns it', async () => {
+        fetchSpy.mockResolvedValue(mockResponse(200, {
+            result: {
+                id: 'doc-1',
+                path: '/imported/test',
+                outcome: 'created',
+                existed: false,
+                name: 'test',
+                frontMatterIgnored: false,
+                frontMatterError: 'strict YAML parse failed (bad indentation of a mapping entry); recovered name/description via lenient fallback',
+            },
+        }));
+        const log = await runLocalGrammarMigration(fakeSource(), BASE_OPTIONS);
+        // Warning must be emitted and include the frontMatterError message
+        expect(warnSpy).toHaveBeenCalledOnce();
+        const warnMsg = String(warnSpy.mock.calls[0][0]);
+        expect(warnMsg).toMatch(/YAML parse error|frontMatterError|bad indentation/i);
+        // Summary must carry the count
+        expect(log.summary.fmIgnoredOrDegraded).toBe(1);
+        void logSpy; // suppress unused warning
+    });
+    it('includes frontMatterIgnored warning when server returns frontMatterIgnored (no frontMatterError)', async () => {
+        fetchSpy.mockResolvedValue(mockResponse(200, {
+            result: {
+                id: 'doc-2',
+                path: '/imported/my-doc',
+                outcome: 'created',
+                existed: false,
+                name: 'my-doc',
+                frontMatterIgnored: true,
+            },
+        }));
+        const log = await runLocalGrammarMigration(fakeSource(), BASE_OPTIONS);
+        expect(warnSpy).toHaveBeenCalledOnce();
+        expect(log.summary.fmIgnoredOrDegraded).toBe(1);
+    });
+    it('fmIgnoredOrDegraded is absent from summary when no FM issues occurred', async () => {
+        fetchSpy.mockResolvedValue(mockResponse(200, {
+            result: {
+                id: 'doc-3',
+                path: '/imported/clean',
+                outcome: 'created',
+                existed: false,
+                name: 'clean',
+                frontMatterIgnored: false,
+            },
+        }));
+        const log = await runLocalGrammarMigration(fakeSource(), BASE_OPTIONS);
+        expect(warnSpy).not.toHaveBeenCalled();
+        expect(log.summary.fmIgnoredOrDegraded).toBeUndefined();
+    });
+});

package/dist/index.js

@@ -142,6 +142,9 @@ function printSummary(log) {
     console.log(`Updated: ${log.summary.updated}`);
     console.log(`Skipped: ${log.summary.skipped}`);
     console.log(`Failed:  ${log.summary.failed}`);
+    if (log.summary.fmIgnoredOrDegraded) {
+        console.log(`FM ignored: ${log.summary.fmIgnoredOrDegraded} (see warnings above)`);
+    }
     if (log.options.dryRun) {
         console.log('\n(Dry run - no changes made)');
     }

package/dist/sources/local.js

@@ -7,6 +7,13 @@ import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
 import * as path from 'path';
 import { glob } from 'glob';
+// NAMED import, matching this package's OWN dependency (unified@^11, pure ESM,
+// named export only — no default). The published artifact resolves ^11; a
+// default import bricks the npx-installed CLI at load time (proven: 0.4.40).
+// In-repo gotcha: this package is STANDALONE-installed (own package-lock.json)
+// — run `npm install` INSIDE packages/kb-migrate before building, or tsc/tsx
+// resolve the monorepo ROOT's hoisted CJS unified@9 and this import appears
+// broken (TS2595). That mirage is what shipped the 0.4.40 regression.
 import { unified } from 'unified';
 import remarkParse from 'remark-parse';
 import { MigrationSource } from './base.js';

package/dist/types.d.ts

@@ -176,6 +176,12 @@ export interface MigrationLog {
         discovered?: number;
         /** Pages skipped during extraction (empty, no content, errors). */
         skippedDuringExtraction?: number;
+        /**
+         * Number of files where front-matter was ignored (no name) or degraded
+         * (strict YAML failed but lenient fallback recovered a name). Non-zero means
+         * some files lost tags/description/properties declared in the front-matter.
+         */
+        fmIgnoredOrDegraded?: number;
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moxn/kb-migrate",
-  "version": "0.4.39",
+  "version": "0.4.41",
   "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"
   }
-}
+}