@lpenguin/notion-cli 1.0.0

package/dist/lib/markdown.js

@@ -0,0 +1,320 @@
+/**
+ * Markdown conversion wrappers.
+ *
+ * - Markdown → Notion blocks: @tryfabric/martian
+ * - Notion → Markdown: notion-to-md (with unified converter)
+ *
+ * This module provides a clean interface over both libraries.
+ *
+ * IMPORTANT: All Notion→Markdown conversion uses `mdBlocksToMarkdown()`
+ * to ensure consistent output between `page read` and `page patch`.
+ */
+import { markdownToBlocks } from '@tryfabric/martian';
+import { NotionToMarkdown } from 'notion-to-md';
+import {} from 'notion-to-md/build/types/index.js';
+import {} from '@notionhq/client';
+import {} from '@notionhq/client/build/src/api-endpoints.js';
+import {} from './types.js';
+import * as logger from '../utils/logger.js';
+import { withRateLimit } from './rate-limit.js';
+import { isFileUrl, fileUrlToPath, uploadFileToNotion } from './file-upload.js';
+/**
+ * Custom implementation of blocksToMarkdown that fetches children in parallel using a queue.
+ */
+async function blocksToMarkdownParallel(n2m, client, blocks) {
+    if (!blocks)
+        return [];
+    const mdBlocks = await Promise.all(blocks.map(async (block, index) => {
+        const result = {
+            // @ts-ignore
+            type: block.type,
+            blockId: block.id,
+            parent: '',
+            children: [],
+        };
+        // Skip unsupported or restricted blocks
+        // @ts-ignore
+        if (block.type === 'unsupported' || !('type' in block)) {
+            return result;
+        }
+        // Handle numbered list items: inject the current index for markdown conversion
+        // Notion API returns chunks, and typically notion-to-md expects to calculate 
+        // these IDs sequentially. Here we simulate the index for the current list.
+        // @ts-ignore
+        if (block.type === 'numbered_list_item') {
+            // Calculate the relative index in the current list sequence
+            let listIndex = 1;
+            for (let i = index - 1; i >= 0; i--) {
+                const prevBlock = blocks[i];
+                // @ts-ignore
+                if (prevBlock && 'type' in prevBlock && prevBlock.type === 'numbered_list_item') {
+                    listIndex++;
+                }
+                else {
+                    break;
+                }
+            }
+            // @ts-ignore
+            block.numbered_list_item.number = listIndex;
+        }
+        // Convert the block itself to markdown. 
+        // We don't queue this as it's a local CPU operation, but we await it.
+        // @ts-ignore
+        result.parent = await n2m.blockToMarkdown(block);
+        // Recursive fetch for children
+        if ('has_children' in block && block.has_children) {
+            const blockId = block.id;
+            // Fetch children using the shared specialized queue
+            const childBlocks = await withRateLimit(async () => {
+                const results = [];
+                let cursor;
+                do {
+                    const response = await client.blocks.children.list({
+                        block_id: blockId,
+                        start_cursor: cursor,
+                    });
+                    results.push(...response.results);
+                    cursor = response.next_cursor ?? undefined;
+                } while (cursor !== undefined);
+                return results;
+            }, `blocks.children.list(${blockId})`);
+            // Recursively convert children
+            result.children = await blocksToMarkdownParallel(n2m, client, childBlocks);
+        }
+        return result;
+    }));
+    return mdBlocks;
+}
+/**
+ * Convert a Markdown string to an array of Notion block objects.
+ * Uses @tryfabric/martian for the conversion.
+ */
+export function markdownToNotionBlocks(markdown) {
+    logger.debug(`Converting ${String(markdown.length)} chars of Markdown to Notion blocks.`);
+    const blocks = markdownToBlocks(markdown);
+    logger.debug(`Produced ${String(blocks.length)} Notion blocks.`);
+    return blocks;
+}
+/**
+ * Process blocks and upload any file:// images to Notion.
+ * Returns modified blocks with uploaded file IDs.
+ */
+export async function processImageUploads(client, blocks) {
+    const processedBlocks = [];
+    for (const block of blocks) {
+        let processedBlock = block;
+        // Check if this is an image block with external URL
+        if (block.type === 'image' && 'image' in block) {
+            const imageBlock = block.image;
+            // Check if it's an external image
+            if ('type' in imageBlock && imageBlock.type === 'external' && 'external' in imageBlock) {
+                const external = imageBlock.external;
+                if ('url' in external && typeof external.url === 'string' && isFileUrl(external.url)) {
+                    // This is a file:// URL, upload it
+                    const filePath = fileUrlToPath(external.url);
+                    try {
+                        const fileUploadId = await uploadFileToNotion(client, filePath);
+                        // Replace with file_upload reference
+                        processedBlock = {
+                            ...block,
+                            image: {
+                                type: 'file_upload',
+                                file_upload: {
+                                    id: fileUploadId,
+                                },
+                                caption: 'caption' in imageBlock ? imageBlock.caption : undefined,
+                            },
+                        };
+                        logger.debug(`Replaced file:// image with upload ID: ${fileUploadId}`);
+                    }
+                    catch (err) {
+                        logger.debug(`Failed to upload image ${filePath}: ${String(err)}`);
+                        // Keep the original block if upload fails
+                    }
+                }
+            }
+        }
+        processedBlocks.push(processedBlock);
+    }
+    return processedBlocks;
+}
+/**
+ * Unified MdBlock to Markdown converter.
+ *
+ * Converts MdBlocks to markdown while tracking which lines each block contributes.
+ * This is the SINGLE source of truth for Notion→Markdown conversion.
+ *
+ * Used by both `page read` and `page patch` to ensure consistent line numbers.
+ *
+ * @param blocks - Array of MdBlocks from notion-to-md
+ * @returns The markdown string and a mapping of blocks to line ranges
+ */
+export function mdBlocksToMarkdown(blocks) {
+    const mappings = [];
+    const outputParts = [];
+    let currentLine = 1;
+    for (let i = 0; i < blocks.length; i++) {
+        const block = blocks[i];
+        // Add blank line before headers (except the first block).
+        // Only add if previous part isn't already empty to avoid triple newlines.
+        if (i > 0 && block.parent.trimStart().startsWith('#')) {
+            const prevPart = outputParts[outputParts.length - 1] ?? '';
+            if (prevPart !== '') {
+                outputParts.push(''); // blank-line separator
+                currentLine += 1;
+            }
+        }
+        const result = processBlockToMarkdown(block, currentLine, 0);
+        mappings.push(result.mapping);
+        outputParts.push(result.markdown);
+        // Count lines in this block's markdown
+        const blockLineCount = result.markdown.split('\n').length;
+        currentLine += blockLineCount;
+    }
+    const markdown = outputParts.join('\n').trim();
+    return { markdown, mappings };
+}
+/**
+ * Process a single block and its children recursively.
+ * Returns the markdown and line mapping for this block.
+ */
+function processBlockToMarkdown(block, startLine, indentLevel) {
+    const indent = '    '.repeat(indentLevel);
+    let markdown = '';
+    const childMappings = [];
+    // The block's own content (already converted to markdown by notion-to-md)
+    const parentContent = block.parent;
+    const parentLines = parentContent.split('\n');
+    // Apply indent to each line of parent content
+    const indentedParent = parentLines
+        .map((line) => (line === '' ? '' : `${indent}${line}`))
+        .join('\n');
+    markdown += indentedParent;
+    let currentLine = startLine + parentLines.length;
+    // Process children with increased indentation
+    if (block.children.length > 0) {
+        for (const child of block.children) {
+            // Add newline separator (ends the previous line, doesn't create a blank line)
+            markdown += '\n';
+            const childResult = processBlockToMarkdown(child, currentLine, indentLevel + 1);
+            childMappings.push(childResult.mapping);
+            markdown += childResult.markdown;
+            currentLine += childResult.markdown.split('\n').length;
+        }
+    }
+    // Calculate end line
+    const endLine = startLine + markdown.split('\n').length - 1;
+    const mapping = {
+        blockId: block.blockId,
+        type: block.type ?? 'unknown',
+        startLine,
+        endLine,
+        markdown: indentedParent, // Just this block's content, not children
+        children: childMappings,
+    };
+    return { mapping, markdown };
+}
+/**
+ * Fetch a Notion page's content as MdBlocks (preserving block IDs).
+ * Used for surgical patching where we need to track block → line mappings.
+ */
+export async function fetchPageMdBlocks(client, pageId) {
+    logger.debug(`Fetching page ${pageId} as MdBlocks.`);
+    const n2m = new NotionToMarkdown({ notionClient: client });
+    // Custom transformer to prevent embedding child pages (only show a link/title)
+    n2m.setCustomTransformer('child_page', (block) => {
+        const cpBlock = block;
+        const title = cpBlock.child_page?.title ?? 'Untitled Page';
+        const id = block.id.replace(/-/g, '');
+        return `[[${title}]](https://www.notion.so/${id})`;
+    });
+    // Fetch top-level blocks
+    const topLevelBlocks = await withRateLimit(async () => {
+        const results = [];
+        let cursor;
+        do {
+            const response = await client.blocks.children.list({
+                block_id: pageId,
+                start_cursor: cursor,
+            });
+            results.push(...response.results);
+            cursor = response.next_cursor ?? undefined;
+        } while (cursor !== undefined);
+        return results;
+    }, `blocks.children.list(${pageId})`);
+    // Convert blocks to markdown with parallel fetching for children via queue
+    const blocks = await blocksToMarkdownParallel(n2m, client, topLevelBlocks);
+    // Fix child_page blocks to be treated as paragraphs
+    fixChildPageBlocks(blocks);
+    logger.debug(`Fetched ${String(blocks.length)} MdBlocks.`);
+    return blocks;
+}
+/**
+ * Fetch a Notion page's content and convert to Markdown.
+ * Uses the unified mdBlocksToMarkdown converter.
+ */
+export async function notionPageToMarkdown(client, pageId) {
+    logger.debug(`Fetching page ${pageId} and converting to Markdown.`);
+    const blocks = await fetchPageMdBlocks(client, pageId);
+    const { markdown } = mdBlocksToMarkdown(blocks);
+    logger.debug(`Converted page to ${String(markdown.length)} chars of Markdown.`);
+    return markdown;
+}
+/**
+ * Clean raw Markdown output:
+ * - Trim leading/trailing whitespace
+ * - Collapse 3+ consecutive newlines into exactly 2
+ */
+export function cleanMarkdownOutput(raw) {
+    return raw
+        .trim()
+        .replace(/\n{3,}/g, '\n\n');
+}
+/**
+ * Recursively rewrite child_page blocks to paragraph so that
+ * toMarkdownString includes them in the output.
+ */
+export function fixChildPageBlocks(mdBlocks) {
+    for (const b of mdBlocks) {
+        if (b.type === 'child_page') {
+            b.type = 'paragraph';
+        }
+        if (b.children.length > 0) {
+            fixChildPageBlocks(b.children);
+        }
+    }
+}
+/**
+ * Convert Markdown to numbered-line format for patch operations.
+ * Each line is prefixed with its 1-based line number.
+ *
+ * Example output:
+ *   1: # Hello World
+ *   2:
+ *   3: Some content here.
+ */
+export function addLineNumbers(markdown) {
+    const lines = markdown.split('\n');
+    const padWidth = String(lines.length).length;
+    return lines
+        .map((line, i) => `${String(i + 1).padStart(padWidth)}: ${line}`)
+        .join('\n');
+}
+/**
+ * Remove line numbers from numbered-line format.
+ * Strips the "N: " prefix from each line.
+ */
+export function stripLineNumbers(numbered) {
+    return numbered
+        .split('\n')
+        .map((line) => line.replace(/^\s*\d+:\s?/, ''))
+        .join('\n');
+}
+/**
+ * Extract the title (first H1) from Markdown content.
+ */
+export function extractTitle(markdown) {
+    const match = /^#\s+(.+)$/m.exec(markdown);
+    return match?.[1]?.trim() ?? 'Untitled';
+}
+//# sourceMappingURL=markdown.js.map

package/dist/lib/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../../src/lib/markdown.ts"],"names":[],"mappings":"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"}

package/dist/lib/output.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Output formatter — JSON mode for AI agents, human-readable for terminals.
+ * Data always goes to stdout; status/progress goes to stderr (via logger).
+ */
+import { type CliResponse, type ResponseMeta } from './types.js';
+export declare function setJsonMode(enabled: boolean): void;
+export declare function isJsonMode(): boolean;
+/** Output a successful result. */
+export declare function printSuccess<T>(data: T, meta?: ResponseMeta): void;
+/** Output an error result. */
+export declare function printError(code: string, message: string, details?: unknown): void;
+/** Format a table of key-value pairs for human display. */
+export declare function formatTable(rows: readonly (readonly [string, string])[]): string;
+/** Format a list of items with index numbers. */
+export declare function formatList(items: readonly string[]): string;
+/**
+ * Wrap a command handler: catches errors, formats output, sets exit code.
+ */
+export declare function wrapOutput(response: CliResponse): void;
+//# sourceMappingURL=output.d.ts.map

package/dist/lib/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/lib/output.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,KAAK,WAAW,EAAkD,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAIjH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAElD;AAED,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED,kCAAkC;AAClC,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,IAAI,CAWlE;AAED,8BAA8B;AAC9B,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAajF;AAED,2DAA2D;AAC3D,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,GAAG,MAAM,CAKhF;AAED,iDAAiD;AACjD,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAE3D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAMtD"}

package/dist/lib/output.js

@@ -0,0 +1,67 @@
+/**
+ * Output formatter — JSON mode for AI agents, human-readable for terminals.
+ * Data always goes to stdout; status/progress goes to stderr (via logger).
+ */
+import chalk from 'chalk';
+import {} from './types.js';
+let jsonMode = false;
+export function setJsonMode(enabled) {
+    jsonMode = enabled;
+}
+export function isJsonMode() {
+    return jsonMode;
+}
+/** Output a successful result. */
+export function printSuccess(data, meta) {
+    if (jsonMode) {
+        const response = { ok: true, data, ...(meta !== undefined ? { meta } : {}) };
+        process.stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    }
+    else {
+        if (typeof data === 'string') {
+            process.stdout.write(`${data}\n`);
+        }
+        else {
+            process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+        }
+    }
+}
+/** Output an error result. */
+export function printError(code, message, details) {
+    if (jsonMode) {
+        const response = {
+            ok: false,
+            error: { code, message, ...(details !== undefined ? { details } : {}) },
+        };
+        process.stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    }
+    else {
+        process.stderr.write(`${chalk.red('Error')} [${code}]: ${message}\n`);
+        if (details !== undefined) {
+            process.stderr.write(`${chalk.gray(JSON.stringify(details, null, 2))}\n`);
+        }
+    }
+}
+/** Format a table of key-value pairs for human display. */
+export function formatTable(rows) {
+    const maxKeyLen = Math.max(...rows.map(([key]) => key.length));
+    return rows
+        .map(([key, value]) => `  ${chalk.bold(key.padEnd(maxKeyLen))}  ${value}`)
+        .join('\n');
+}
+/** Format a list of items with index numbers. */
+export function formatList(items) {
+    return items.map((item, i) => `  ${chalk.gray(`${String(i + 1)}.`)} ${item}`).join('\n');
+}
+/**
+ * Wrap a command handler: catches errors, formats output, sets exit code.
+ */
+export function wrapOutput(response) {
+    if (response.ok) {
+        printSuccess(response.data, response.meta);
+    }
+    else {
+        printError(response.error.code, response.error.message, response.error.details);
+    }
+}
+//# sourceMappingURL=output.js.map

package/dist/lib/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/lib/output.ts"],"names":[],"mappings":"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"}

package/dist/lib/patch.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Patch engine — apply edits to Markdown content.
+ *
+ * Line-range replacement (--lines START:END)
+ * Replace lines START through END with new content.
+ * Familiar to coding agents that work with line numbers.
+ */
+import { type PatchOperation } from './types.js';
+/** Result of applying a patch. */
+export interface PatchResult {
+    /** The patched Markdown content. */
+    readonly patched: string;
+    /** Human-readable unified diff of the changes. */
+    readonly diff: string;
+    /** Number of lines changed. */
+    readonly linesChanged: number;
+}
+/**
+ * Apply a patch operation to Markdown content.
+ * Returns the patched content, a diff of changes, and line count.
+ */
+export declare function applyPatchOperation(original: string, operation: PatchOperation): PatchResult;
+//# sourceMappingURL=patch.d.ts.map

package/dist/lib/patch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch.d.ts","sourceRoot":"","sources":["../../src/lib/patch.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,KAAK,cAAc,EAAuB,MAAM,YAAY,CAAC;AAItE,kCAAkC;AAClC,MAAM,WAAW,WAAW;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,cAAc,GACxB,WAAW,CAEb"}

package/dist/lib/patch.js

@@ -0,0 +1,72 @@
+/**
+ * Patch engine — apply edits to Markdown content.
+ *
+ * Line-range replacement (--lines START:END)
+ * Replace lines START through END with new content.
+ * Familiar to coding agents that work with line numbers.
+ */
+import { createTwoFilesPatch } from 'diff';
+import {} from './types.js';
+import { ValidationError } from './errors.js';
+import * as logger from '../utils/logger.js';
+/**
+ * Apply a patch operation to Markdown content.
+ * Returns the patched content, a diff of changes, and line count.
+ */
+export function applyPatchOperation(original, operation) {
+    return applyLineRange(original, operation);
+}
+/**
+ * Line-range replacement.
+ *
+ * Replace lines [start, end] (1-indexed, inclusive) with new content.
+ *
+ * Special cases:
+ * - start === end: Replace a single line.
+ * - Content is empty: Delete the lines.
+ */
+function applyLineRange(original, op) {
+    const lines = original.split('\n');
+    const totalLines = lines.length;
+    // Validate range
+    if (op.start < 1) {
+        throw new ValidationError('Line range start must be >= 1.');
+    }
+    const effectiveEnd = Math.min(op.end, totalLines);
+    if (op.start > totalLines + 1) {
+        throw new ValidationError(`Start line ${String(op.start)} exceeds document length (${String(totalLines)} lines).`);
+    }
+    logger.debug(`Replacing lines ${String(op.start)}-${String(effectiveEnd)} (of ${String(totalLines)}) with ${String(op.content.split('\n').length)} lines.`);
+    // Build new content
+    const before = lines.slice(0, op.start - 1);
+    const after = lines.slice(effectiveEnd);
+    const newLines = op.content === '' ? [] : op.content.split('\n');
+    const patched = [...before, ...newLines, ...after].join('\n');
+    return buildResult(original, patched);
+}
+/**
+ * Build a PatchResult from before/after content.
+ */
+function buildResult(original, patched) {
+    const diff = createTwoFilesPatch('before', 'after', original, patched, '', '', {
+        context: 3,
+    });
+    // Count changed lines
+    const diffLines = diff.split('\n');
+    let added = 0;
+    let removed = 0;
+    for (const line of diffLines) {
+        if (line.startsWith('+') && !line.startsWith('+++')) {
+            added++;
+        }
+        if (line.startsWith('-') && !line.startsWith('---')) {
+            removed++;
+        }
+    }
+    return {
+        patched,
+        diff,
+        linesChanged: added + removed,
+    };
+}
+//# sourceMappingURL=patch.js.map

package/dist/lib/patch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch.js","sourceRoot":"","sources":["../../src/lib/patch.ts"],"names":[],"mappings":"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"}

package/dist/lib/rate-limit.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Rate-limit handling with exponential backoff.
+ * Notion API has a 3 requests/second rate limit.
+ */
+/**
+ * Execute an async function with both concurrency control and automatic retry on rate-limits.
+ */
+export declare function withRateLimit<T>(fn: () => Promise<T>, label?: string): Promise<T>;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/lib/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/lib/rate-limit.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAgBH;;GAEG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,KAAK,SAAa,GACjB,OAAO,CAAC,CAAC,CAAC,CAEZ"}

package/dist/lib/rate-limit.js

@@ -0,0 +1,67 @@
+/**
+ * Rate-limit handling with exponential backoff.
+ * Notion API has a 3 requests/second rate limit.
+ */
+import * as logger from '../utils/logger.js';
+import { RateLimitError } from './errors.js';
+import PQueue from 'p-queue';
+const MAX_RETRIES = 5;
+const BASE_DELAY_MS = 1000;
+const MAX_DELAY_MS = 30_000;
+/**
+ * Global queue for Notion API requests.
+ * Concurrency is set to 3 to stay within Notion's recommended rate limits.
+ */
+const notionQueue = new PQueue({ concurrency: 3 });
+/**
+ * Execute an async function with both concurrency control and automatic retry on rate-limits.
+ */
+export async function withRateLimit(fn, label = 'API call') {
+    return notionQueue.add(() => withRetry(fn, label));
+}
+/**
+ * Execute an async function with automatic retry on rate-limit (429) errors.
+ * Uses exponential backoff with jitter.
+ */
+async function withRetry(fn, label = 'API call') {
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err;
+            if (!isRateLimitError(err)) {
+                throw err;
+            }
+            if (attempt === MAX_RETRIES) {
+                throw new RateLimitError(MAX_DELAY_MS);
+            }
+            const delay = calculateDelay(attempt);
+            logger.warn(`${label}: Rate limited (attempt ${String(attempt + 1)}/${String(MAX_RETRIES)}). Retrying in ${String(Math.ceil(delay / 1000))}s...`);
+            await sleep(delay);
+        }
+    }
+    // This should be unreachable, but satisfies noImplicitReturns
+    throw lastError;
+}
+function isRateLimitError(err) {
+    if (typeof err !== 'object' || err === null) {
+        return false;
+    }
+    const status = err['status'];
+    return status === 429;
+}
+function calculateDelay(attempt) {
+    const exponential = BASE_DELAY_MS * Math.pow(2, attempt);
+    const capped = Math.min(exponential, MAX_DELAY_MS);
+    // Add jitter: 50-100% of the delay
+    const jitter = capped * (0.5 + Math.random() * 0.5);
+    return Math.round(jitter);
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/lib/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../../src/lib/rate-limit.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,MAAM,MAAM,SAAS,CAAC;AAE7B,MAAM,WAAW,GAAG,CAAC,CAAC;AACtB,MAAM,aAAa,GAAG,IAAI,CAAC;AAC3B,MAAM,YAAY,GAAG,MAAM,CAAC;AAE5B;;;GAGG;AACH,MAAM,WAAW,GAAW,IAAI,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC,CAAC;AAE3D;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,EAAoB,EACpB,KAAK,GAAG,UAAU;IAElB,OAAO,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;AACrD,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,SAAS,CACtB,EAAoB,EACpB,KAAK,GAAG,UAAU;IAElB,IAAI,SAAkB,CAAC;IAEvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QACxD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,SAAS,GAAG,GAAG,CAAC;YAEhB,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC3B,MAAM,GAAG,CAAC;YACZ,CAAC;YAED,IAAI,OAAO,KAAK,WAAW,EAAE,CAAC;gBAC5B,MAAM,IAAI,cAAc,CAAC,YAAY,CAAC,CAAC;YACzC,CAAC;YAED,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;YACtC,MAAM,CAAC,IAAI,CACT,GAAG,KAAK,2BAA2B,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC,IAAI,MAAM,CAAC,WAAW,CAAC,kBAAkB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,MAAM,CACrI,CAAC;YACF,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,8DAA8D;IAC9D,MAAM,SAAS,CAAC;AAClB,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAY;IACpC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC5C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,MAAM,GAAI,GAA+B,CAAC,QAAQ,CAAC,CAAC;IAC1D,OAAO,MAAM,KAAK,GAAG,CAAC;AACxB,CAAC;AAED,SAAS,cAAc,CAAC,OAAe;IACrC,MAAM,WAAW,GAAG,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IACnD,mCAAmC;IACnC,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC;IACpD,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AAED,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/lib/safety.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Safety module — confirmation prompts, dry-run, and write guards.
+ *
+ * This is the single point of control for write safety.
+ */
+/**
+ * Guard for dry-run mode.
+ * Returns true if we should skip the actual write (dry-run is active).
+ */
+export declare function isDryRun(dryRun?: boolean): boolean;
+/**
+ * Display a diff preview before applying changes.
+ *
+ * Shows a colored unified diff of the changes.
+ */
+export declare function showDiffPreview(before: string, after: string): void;
+//# sourceMappingURL=safety.d.ts.map

package/dist/lib/safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety.d.ts","sourceRoot":"","sources":["../../src/lib/safety.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAMlD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAwBnE"}