@moxn/kb-migrate 0.5.0 → 0.6.0

package/dist/export.js

@@ -45,6 +45,75 @@ function mediaTargetForDirective(directive, options) {
 function docPathToFilePath(docPath) {
     return `${docPath.replace(/^\//, '')}.md`;
 }
+/** A KB path → its directory-relative location with a given extension. */
+function docPathWithExt(docPath, ext) {
+    return `${docPath.replace(/^\//, '')}${ext}`;
+}
+/** A document that could not be exported for a reason that is not an error. */
+class SkipExport extends Error {
+}
+/**
+ * Export a document the grammar export has no body for (report / file /
+ * slides), via the `read` tool. Returns the directory-relative files written
+ * (the first is the document's own output file). Throws on a read error
+ * (→ failed) and {@link SkipExport} on a kind it does not know (→ skipped),
+ * so nothing is ever reported "exported" without its body on disk.
+ */
+async function exportNonMarkdownDocument(client, docPath, documentId, outputDir, dryRun, claimed) {
+    const item = await client.readDocument(documentId);
+    if (item.error)
+        throw new Error(item.error);
+    const write = (relPath, text) => {
+        if (dryRun)
+            return;
+        const full = path.join(outputDir, relPath);
+        fs.mkdirSync(path.dirname(full), { recursive: true });
+        fs.writeFileSync(full, text, 'utf-8');
+    };
+    const htmlBody = () => {
+        const html = item.content?.find((c) => typeof c.text === 'string')?.text;
+        if (html === undefined)
+            throw new Error(`read returned no ${item.kind} HTML`);
+        return html;
+    };
+    switch (item.kind) {
+        case 'report': {
+            const out = docPathWithExt(docPath, '.html');
+            write(out, htmlBody());
+            return [out];
+        }
+        case 'slides': {
+            const out = docPathWithExt(docPath, '.html');
+            write(out, htmlBody());
+            const themeCss = item.deck?.themeCss;
+            if (!themeCss)
+                return [out];
+            const theme = docPathWithExt(docPath, '.theme.css');
+            write(theme, themeCss);
+            return [out, theme];
+        }
+        case 'file': {
+            if (!item.file)
+                throw new Error('read returned no file metadata');
+            // The blob under its ORIGINAL filename, beside where the doc lives. The
+            // filename is server data: only its basename is used, and a name another
+            // document in this run already took falls back to the (unique) KB path.
+            const folder = path.posix.dirname(docPath.replace(/^\//, ''));
+            const base = path.basename(item.file.filename);
+            let out = base && base !== '..' ? path.posix.join(folder, base) : '';
+            if (!out || claimed.has(out))
+                out = docPath.replace(/^\//, '');
+            if (!dryRun) {
+                const full = path.join(outputDir, out);
+                fs.mkdirSync(path.dirname(full), { recursive: true });
+                await client.downloadFile(item.file.download.url, full);
+            }
+            return [out];
+        }
+        default:
+            throw new SkipExport(`kind '${item.kind ?? 'unknown'}' has no local export format; nothing written`);
+    }
+}
 // ──────────────────────────────────────────────
 // Main export runner
 // ──────────────────────────────────────────────
@@ -84,6 +153,7 @@ export async function runExport(outputDir, options) {
                 total: 0,
                 exported: 0,
                 failed: 0,
+                skipped: 0,
                 mediaDownloaded: 0,
                 duration: Date.now() - startTime,
             },
@@ -98,6 +168,9 @@ export async function runExport(outputDir, options) {
     }
     const results = [];
     let totalMediaDownloaded = 0;
+    // Output files written so far — a file blob whose original filename is
+    // already taken falls back to its KB path instead of overwriting.
+    const claimed = new Set();
     for (const docItem of documents) {
         const docStart = Date.now();
         const mediaFiles = [];
@@ -115,7 +188,21 @@ export async function runExport(outputDir, options) {
             //    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)');
+                // No grammar body: a report / file / slides document. Export its real
+                // body (never an empty `.md` stand-in).
+                const files = await exportNonMarkdownDocument(client, docItem.path, docItem.id, outputDir, options.dryRun, claimed);
+                files.forEach((f) => claimed.add(f));
+                console.error(`  ✓ ${files[0]}`);
+                results.push({
+                    documentId: docItem.id,
+                    documentPath: docItem.path,
+                    outputFile: files[0],
+                    status: 'exported',
+                    sectionsCount: 0,
+                    mediaFiles: files.slice(1),
+                    duration: Date.now() - docStart,
+                });
+                continue;
             }
             const mdRelativePath = docPathToFilePath(docItem.path);
             const mdFullPath = path.join(outputDir, mdRelativePath);
@@ -171,6 +258,7 @@ export async function runExport(outputDir, options) {
                 fs.mkdirSync(path.dirname(mdFullPath), { recursive: true });
                 fs.writeFileSync(mdFullPath, markdown, 'utf-8');
             }
+            claimed.add(mdRelativePath);
             console.error(`  ✓ ${mdRelativePath} (${mediaFiles.length} media)`);
             results.push({
                 documentId: docItem.id,
@@ -186,12 +274,13 @@ export async function runExport(outputDir, options) {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            console.error(`  ✗ Failed: ${message}`);
+            const skipped = error instanceof SkipExport;
+            console.error(`  ${skipped ? '-' : '✗'} ${skipped ? 'Skipped' : 'Failed'}: ${message}`);
             results.push({
                 documentId: docItem.id,
                 documentPath: docItem.path,
-                outputFile: docPathToFilePath(docItem.path),
-                status: 'failed',
+                outputFile: '',
+                status: skipped ? 'skipped' : 'failed',
                 sectionsCount: 0,
                 mediaFiles: [],
                 error: message,
@@ -215,6 +304,7 @@ export async function runExport(outputDir, options) {
             total: results.length,
             exported: results.filter((r) => r.status === 'exported').length,
             failed: results.filter((r) => r.status === 'failed').length,
+            skipped: results.filter((r) => r.status === 'skipped').length,
             mediaDownloaded: totalMediaDownloaded,
             duration: Date.now() - startTime,
         },

package/dist/export.test.js

@@ -105,3 +105,124 @@ describe('runExport — clean grammar (no {#id} anchors, Issue 1)', () => {
         fs.rmSync(outputDir, { recursive: true, force: true });
     });
 });
+/**
+ * Non-markdown kinds (prod 2026-09-25). A `kind='report'` document came out
+ * as a 34-byte `.md` holding only `# <name>` while the summary said
+ * `exported: 2, failed: 0` — its HTML body silently gone. The grammar export
+ * (`get_document_markdown`) has no body for report / file / slides, so each
+ * kind now exports its REAL body via the `read` tool, and anything that can't
+ * be exported is `skipped` or `failed` with a reason — never "exported".
+ */
+describe('runExport — non-markdown kinds export their real body', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    const OPTIONS = {
+        apiUrl: 'http://localhost:3001',
+        apiKey: 'test-key',
+        basePath: '',
+        imageDir: 'images',
+        pdfDir: 'pdfs',
+        csvDir: 'csvs',
+        dryRun: false,
+    };
+    function listItem(id, docPath) {
+        return {
+            id,
+            path: docPath,
+            name: docPath.split('/').pop(),
+            description: null,
+            createdAt: '2026-01-01T00:00:00.000Z',
+            updatedAt: null,
+        };
+    }
+    it('writes report HTML, the file blob under its filename, and deck HTML; md stays grammar', async () => {
+        const outputDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-export-kinds-'));
+        vi.spyOn(MoxnClient.prototype, 'listDocuments').mockResolvedValue([
+            listItem('md-1', '/qa/notes'),
+            listItem('rep-1', '/qa/dashboard'),
+            listItem('file-1', '/qa/file-versions.txt'),
+            listItem('deck-1', '/qa/pitch'),
+        ]);
+        vi.spyOn(MoxnClient.prototype, 'getDocumentMarkdown').mockImplementation(async (id) => id === 'md-1'
+            ? {
+                id,
+                branchName: 'main',
+                markdown: '---\nname: notes\n---\n\nPreamble.\n\n## Alpha\n\nalpha\n',
+            }
+            : null);
+        const readDocument = vi
+            .spyOn(MoxnClient.prototype, 'readDocument')
+            .mockImplementation(async (id) => {
+            if (id === 'rep-1') {
+                return {
+                    type: 'document',
+                    documentId: id,
+                    kind: 'report',
+                    content: [{ type: 'text', text: '<h1>Q3</h1><p>numbers</p>' }],
+                };
+            }
+            if (id === 'file-1') {
+                return {
+                    type: 'document',
+                    documentId: id,
+                    kind: 'file',
+                    file: {
+                        filename: 'f.txt',
+                        download: { url: 'https://storage.example/signed-f' },
+                    },
+                };
+            }
+            return {
+                type: 'document',
+                documentId: id,
+                kind: 'slides',
+                content: [{ type: 'text', text: '<section data-moxn-slide>one</section>' }],
+                deck: { themeCss: null },
+            };
+        });
+        vi.spyOn(MoxnClient.prototype, 'downloadFile').mockImplementation(async (url, dest) => {
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            fs.writeFileSync(dest, `blob from ${url}`);
+        });
+        const log = await runExport(outputDir, OPTIONS);
+        // md never touches the read fallback.
+        expect(readDocument.mock.calls.map((c) => c[0]).sort()).toEqual([
+            'deck-1',
+            'file-1',
+            'rep-1',
+        ]);
+        expect(fs.readFileSync(path.join(outputDir, 'qa/notes.md'), 'utf-8')).toContain('Preamble.');
+        expect(fs.readFileSync(path.join(outputDir, 'qa/dashboard.html'), 'utf-8')).toBe('<h1>Q3</h1><p>numbers</p>');
+        expect(fs.readFileSync(path.join(outputDir, 'qa/f.txt'), 'utf-8')).toBe('blob from https://storage.example/signed-f');
+        expect(fs.readFileSync(path.join(outputDir, 'qa/pitch.html'), 'utf-8')).toBe('<section data-moxn-slide>one</section>');
+        // No empty `.md` stand-ins for the non-md kinds.
+        expect(fs.existsSync(path.join(outputDir, 'qa/dashboard.md'))).toBe(false);
+        const byId = Object.fromEntries(log.results.map((r) => [r.documentId, r]));
+        expect(byId['rep-1'].outputFile).toBe('qa/dashboard.html');
+        expect(byId['file-1'].outputFile).toBe('qa/f.txt');
+        expect(byId['deck-1'].outputFile).toBe('qa/pitch.html');
+        expect(log.summary).toMatchObject({ total: 4, exported: 4, failed: 0, skipped: 0 });
+        fs.rmSync(outputDir, { recursive: true, force: true });
+    });
+    it('a read error is a FAILURE with its reason, an unknown kind is SKIPPED — neither is "exported"', async () => {
+        const outputDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-export-kinds-err-'));
+        vi.spyOn(MoxnClient.prototype, 'listDocuments').mockResolvedValue([
+            listItem('locked', '/qa/locked'),
+            listItem('odd', '/qa/odd'),
+        ]);
+        vi.spyOn(MoxnClient.prototype, 'getDocumentMarkdown').mockResolvedValue(null);
+        vi.spyOn(MoxnClient.prototype, 'readDocument').mockImplementation(async (id) => id === 'locked'
+            ? { type: 'document', documentId: id, error: 'Access denied (aiAccess none)' }
+            : { type: 'document', documentId: id, kind: 'hologram' });
+        const log = await runExport(outputDir, OPTIONS);
+        const byId = Object.fromEntries(log.results.map((r) => [r.documentId, r]));
+        expect(byId.locked.status).toBe('failed');
+        expect(byId.locked.error).toContain('Access denied');
+        expect(byId.odd.status).toBe('skipped');
+        expect(byId.odd.error).toMatch(/hologram/);
+        expect(log.summary).toMatchObject({ total: 2, exported: 0, failed: 1, skipped: 1 });
+        expect(fs.readdirSync(outputDir).filter((f) => f === 'qa')).toEqual([]);
+        fs.rmSync(outputDir, { recursive: true, force: true });
+    });
+});

package/dist/http.d.ts

@@ -0,0 +1 @@
+export declare function moxnFetch(url: string, init?: RequestInit): Promise<Response>;

package/dist/http.js

@@ -0,0 +1,16 @@
+/**
+ * The one fetch for Moxn API calls. Adds the Vercel protection-bypass header
+ * via @moxn/auth's `vercelBypassHeaders` — the helper kb-cli uses — which is a
+ * no-op unless MOXN_VERCEL_BYPASS is set AND the URL is MOXN_BASE_URL's
+ * origin, so signed storage / Notion / media URLs never receive the secret.
+ */
+import { vercelBypassHeaders } from '@moxn/auth';
+export function moxnFetch(url, init = {}) {
+    const bypass = vercelBypassHeaders(url);
+    if (Object.keys(bypass).length === 0)
+        return fetch(url, init);
+    const headers = new Headers(init.headers);
+    for (const [k, v] of Object.entries(bypass))
+        headers.set(k, v);
+    return fetch(url, { ...init, headers });
+}

package/dist/import-local.js

@@ -206,6 +206,7 @@ async function migrateGrammarFile(client, file, options) {
                 documentPath: res.path || documentPath,
                 status,
                 documentId: res.id,
+                ...client.permissionWarningFor(res, file.sourcePath),
                 duration: Date.now() - startTime,
             },
             hadFmWarning,

package/dist/import-local.test.js

@@ -117,3 +117,99 @@ describe('runLocalGrammarMigration — FM warning surface + summary count', () =
         expect(log.summary.fmIgnoredOrDegraded).toBeUndefined();
     });
 });
+// ─────────────────────────────────────────────────────────────────────────────
+// --default-permission / --ai-access reach the server (prod 2026-09-25: both
+// were stored on the client and never sent, so `--ai-access none` created an
+// ai_access='edit' document).
+// ─────────────────────────────────────────────────────────────────────────────
+describe('runLocalGrammarMigration — importer permissions', () => {
+    let warnSpy;
+    let fetchSpy;
+    beforeEach(() => {
+        warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        vi.spyOn(console, 'log').mockImplementation(() => { });
+        fetchSpy = vi.spyOn(globalThis, 'fetch');
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    const PERM_OPTIONS = {
+        ...BASE_OPTIONS,
+        defaultPermission: 'read',
+        aiAccess: 'none',
+    };
+    function sentBody() {
+        const init = fetchSpy.mock.calls[0][1];
+        return JSON.parse(String(init.body));
+    }
+    it('sends defaultPermission + aiAccess on the import_markdown request', async () => {
+        fetchSpy.mockResolvedValue(mockResponse(200, {
+            result: {
+                id: 'doc-p',
+                path: '/imported/my-doc',
+                outcome: 'created',
+                existed: false,
+                name: 'my-doc',
+                frontMatterIgnored: false,
+                permissions: { defaultPermission: 'read', aiAccess: 'none' },
+            },
+        }));
+        const log = await runLocalGrammarMigration(fakeSource(), PERM_OPTIONS);
+        const body = sentBody();
+        expect(body.action).toBe('import_markdown');
+        expect(body.defaultPermission).toBe('read');
+        expect(body.aiAccess).toBe('none');
+        expect(log.results[0].status).toBe('created');
+        // Applied as asked → nothing to warn about.
+        expect(warnSpy).not.toHaveBeenCalled();
+    });
+    it('omits both fields when the flags were not given (server keeps its defaults)', async () => {
+        fetchSpy.mockResolvedValue(mockResponse(200, {
+            result: {
+                id: 'doc-d',
+                path: '/imported/my-doc',
+                outcome: 'created',
+                existed: false,
+                name: 'my-doc',
+                frontMatterIgnored: false,
+                permissions: { defaultPermission: 'read', aiAccess: 'edit' },
+            },
+        }));
+        await runLocalGrammarMigration(fakeSource(), BASE_OPTIONS);
+        const body = sentBody();
+        expect('defaultPermission' in body).toBe(false);
+        expect('aiAccess' in body).toBe(false);
+    });
+    it('warns that an UPDATED document kept its existing permissions', async () => {
+        fetchSpy.mockResolvedValue(mockResponse(200, {
+            result: {
+                id: 'doc-u',
+                path: '/imported/my-doc',
+                outcome: 'updated',
+                existed: true,
+                name: 'my-doc',
+                frontMatterIgnored: false,
+            },
+        }));
+        const log = await runLocalGrammarMigration(fakeSource(), PERM_OPTIONS);
+        expect(log.results[0].status).toBe('updated');
+        expect(log.results[0].warning).toMatch(/permissions/i);
+        expect(String(warnSpy.mock.calls[0]?.[0])).toMatch(/existing document.*permissions/i);
+    });
+    it('warns when a server too old to apply the flags created the document without them', async () => {
+        fetchSpy.mockResolvedValue(mockResponse(200, {
+            result: {
+                id: 'doc-o',
+                path: '/imported/my-doc',
+                outcome: 'created',
+                existed: false,
+                name: 'my-doc',
+                frontMatterIgnored: false,
+                // no `permissions` echo — an older server ignored the fields
+            },
+        }));
+        const log = await runLocalGrammarMigration(fakeSource(), PERM_OPTIONS);
+        expect(log.results[0].warning).toMatch(/server/i);
+        expect(String(warnSpy.mock.calls[0]?.[0])).toMatch(/did not apply/i);
+    });
+});

package/dist/index.js

@@ -19,6 +19,7 @@ import { notionColorToHex } from './sources/notion-api.js';
 import { getPageTitle } from './sources/notion-blocks.js';
 import { slugify } from './sources/notion.js';
 import { MoxnClient } from './client.js';
+import { emitJson, enterJsonMode, exitJsonMode, packageVersion } from './output.js';
 import { runExport } from './export.js';
 import { runLocalGrammarMigration } from './import-local.js';
 import { runNotionExport } from './export-notion.js';
@@ -121,6 +122,18 @@ async function runMigration(source, options) {
     };
     return log;
 }
+/** Exit on a --default-permission / --ai-access value the server would reject per document. */
+function assertPermissionFlags(opts) {
+    for (const [flag, value] of [
+        ['--default-permission', opts.defaultPermission],
+        ['--ai-access', opts.aiAccess],
+    ]) {
+        if (value !== undefined && !['edit', 'read', 'none'].includes(value)) {
+            console.error(`Error: ${flag} must be "edit", "read" or "none"`);
+            process.exit(1);
+        }
+    }
+}
 function printSummary(log) {
     console.log('\n--- Migration Summary ---');
     console.log(`Source: ${log.source.type} (${log.source.location})`);
@@ -159,10 +172,14 @@ function printExportSummary(log) {
     console.log(`Total:      ${log.summary.total}`);
     console.log(`Exported:   ${log.summary.exported}`);
     console.log(`Failed:     ${log.summary.failed}`);
+    console.log(`Skipped:    ${log.summary.skipped}`);
     console.log(`Media:      ${log.summary.mediaDownloaded}`);
-    if (log.summary.failed > 0) {
-        console.log('\nFailed documents:');
-        for (const f of log.results.filter((r) => r.status === 'failed')) {
+    for (const status of ['failed', 'skipped']) {
+        const rows = log.results.filter((r) => r.status === status);
+        if (rows.length === 0)
+            continue;
+        console.log(`\n${status === 'failed' ? 'Failed' : 'Skipped'} documents:`);
+        for (const f of rows) {
             console.log(`  - ${f.documentPath}: ${f.error}`);
         }
     }
@@ -276,7 +293,15 @@ const program = new Command();
 program
     .name('moxn-kb-migrate')
     .description('Import documents into Moxn Knowledge Base')
-    .version('0.1.0');
+    .version(packageVersion());
+// Which kb-migrate ran is always on stderr (a stale npx resolution once ran a
+// retired exporter silently), and `--json` keeps stdout to the JSON log alone.
+program.hook('preAction', (_program, actionCommand) => {
+    console.error(`@moxn/kb-migrate ${packageVersion()}`);
+    if (actionCommand.opts().json)
+        enterJsonMode();
+});
+program.hook('postAction', () => exitJsonMode());
 program
     .command('local <directory>')
     .description('Migrate documents from local filesystem')
@@ -285,8 +310,8 @@ program
     .option('--base-path <path>', 'Base path for imported documents', '/')
     .option('--extensions <exts>', 'Comma-separated file extensions', DEFAULT_EXTENSIONS.join(','))
     .option('--on-conflict <action>', 'Action on conflict: skip or update', 'skip')
-    .option('--default-permission <perm>', 'Default permission: edit, read, or none')
-    .option('--ai-access <perm>', 'AI access permission: edit, read, or none')
+    .option('--default-permission <perm>', 'Default permission for CREATED docs: edit, read, or none (an update leaves existing permissions alone)')
+    .option('--ai-access <perm>', 'AI access for CREATED docs: edit, read, or none (an update leaves existing permissions alone)')
     .option('--created-after <date>', 'Only include docs created after this date (ISO 8601)')
     .option('--created-before <date>', 'Only include docs created before this date (ISO 8601)')
     .option('--modified-after <date>', 'Only include docs modified after this date (ISO 8601)')
@@ -305,6 +330,7 @@ program
         console.error('Error: --on-conflict must be "skip" or "update"');
         process.exit(1);
     }
+    assertPermissionFlags(opts);
     const dateFilter = buildDateFilter({
         createdAfter: opts.createdAfter,
         createdBefore: opts.createdBefore,
@@ -333,7 +359,7 @@ program
         // 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));
+            emitJson(log);
         }
         else {
             printSummary(log);
@@ -388,7 +414,7 @@ program
     try {
         const log = await runExport(directory, exportOptions);
         if (opts.json) {
-            console.log(JSON.stringify(log, null, 2));
+            emitJson(log);
         }
         else {
             printExportSummary(log);
@@ -412,8 +438,8 @@ program
     .option('--root-page-id <id>', 'Import subtree starting from this Notion page ID')
     .option('--max-depth <n>', 'Maximum nesting depth')
     .option('--on-conflict <action>', 'Action on conflict: skip or update', 'skip')
-    .option('--default-permission <perm>', 'Default permission: edit, read, or none')
-    .option('--ai-access <perm>', 'AI access permission: edit, read, or none')
+    .option('--default-permission <perm>', 'Default permission for CREATED docs: edit, read, or none (an update leaves existing permissions alone)')
+    .option('--ai-access <perm>', 'AI access for CREATED docs: edit, read, or none (an update leaves existing permissions alone)')
     .option('--visibility <vis>', 'Convenience flag: team (read) or private (none)')
     .option('--created-after <date>', 'Only include docs created after this date (ISO 8601)')
     .option('--created-before <date>', 'Only include docs created before this date (ISO 8601)')
@@ -437,6 +463,7 @@ program
         console.error('Error: --on-conflict must be "skip" or "update"');
         process.exit(1);
     }
+    assertPermissionFlags(opts);
     // Resolve visibility → defaultPermission (visibility is syntactic sugar)
     let defaultPermission = opts.defaultPermission;
     if (!defaultPermission && opts.visibility) {
@@ -650,7 +677,7 @@ program
         // Cleanup temp files
         await source.cleanup();
         if (opts.json) {
-            console.log(JSON.stringify(log, null, 2));
+            emitJson(log);
         }
         else {
             printSummary(log);
@@ -718,7 +745,7 @@ program
             dateFilter,
         });
         if (opts.json) {
-            console.log(JSON.stringify(log, null, 2));
+            emitJson(log);
         }
         else {
             printNotionExportSummary(log);

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 {};