@catafal/notion-cli 5.9.0

package/dist/utils/disk-cache.js

@@ -0,0 +1,291 @@
+"use strict";
+/**
+ * Disk Cache Manager
+ *
+ * Provides persistent caching to disk, maintaining cache across CLI invocations.
+ * Cache entries are stored in ~/.notion-cli/cache/ directory.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diskCacheManager = exports.DiskCacheManager = void 0;
+const fs = require("fs/promises");
+const path = require("path");
+const os = require("os");
+const crypto = require("crypto");
+const CACHE_DIR_NAME = '.notion-cli';
+const CACHE_SUBDIR = 'cache';
+const DEFAULT_MAX_SIZE = 100 * 1024 * 1024; // 100MB
+const DEFAULT_SYNC_INTERVAL = 5000; // 5 seconds
+class DiskCacheManager {
+    constructor(options = {}) {
+        this.dirtyKeys = new Set();
+        this.syncTimer = null;
+        this.initialized = false;
+        this.cacheDir = options.cacheDir || path.join(os.homedir(), CACHE_DIR_NAME, CACHE_SUBDIR);
+        this.maxSize = options.maxSize || parseInt(process.env.NOTION_CLI_DISK_CACHE_MAX_SIZE || String(DEFAULT_MAX_SIZE), 10);
+        this.syncInterval = options.syncInterval || parseInt(process.env.NOTION_CLI_DISK_CACHE_SYNC_INTERVAL || String(DEFAULT_SYNC_INTERVAL), 10);
+    }
+    /**
+     * Initialize disk cache (create directory, start sync timer)
+     */
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        await this.ensureCacheDir();
+        await this.enforceMaxSize();
+        // Start periodic sync timer
+        if (this.syncInterval > 0) {
+            this.syncTimer = setInterval(() => {
+                this.sync().catch(error => {
+                    if (process.env.DEBUG) {
+                        console.warn('Disk cache sync error:', error);
+                    }
+                });
+            }, this.syncInterval);
+            // Don't keep the process alive
+            if (this.syncTimer.unref) {
+                this.syncTimer.unref();
+            }
+        }
+        this.initialized = true;
+    }
+    /**
+     * Get a cache entry from disk
+     */
+    async get(key) {
+        try {
+            const filePath = this.getFilePath(key);
+            const content = await fs.readFile(filePath, 'utf-8');
+            const entry = JSON.parse(content);
+            // Check if expired
+            if (Date.now() > entry.expiresAt) {
+                // Delete expired entry
+                await this.invalidate(key);
+                return null;
+            }
+            return entry;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return null;
+            }
+            if (process.env.DEBUG) {
+                console.warn(`Failed to read cache entry ${key}:`, error.message);
+            }
+            return null;
+        }
+    }
+    /**
+     * Set a cache entry to disk
+     */
+    async set(key, data, ttl) {
+        const entry = {
+            key,
+            data,
+            expiresAt: Date.now() + ttl,
+            createdAt: Date.now(),
+            size: JSON.stringify(data).length,
+        };
+        const filePath = this.getFilePath(key);
+        const tmpPath = `${filePath}.tmp`;
+        try {
+            // Write to temporary file
+            await fs.writeFile(tmpPath, JSON.stringify(entry), { encoding: 'utf-8', mode: 0o600 });
+            // Atomic rename
+            await fs.rename(tmpPath, filePath);
+            this.dirtyKeys.delete(key);
+        }
+        catch (error) {
+            // Clean up temp file if it exists
+            try {
+                await fs.unlink(tmpPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            if (process.env.DEBUG) {
+                console.warn(`Failed to write cache entry ${key}:`, error.message);
+            }
+        }
+        // Check if we need to enforce size limits
+        const stats = await this.getStats();
+        if (stats.totalSize > this.maxSize) {
+            await this.enforceMaxSize();
+        }
+    }
+    /**
+     * Invalidate (delete) a cache entry
+     */
+    async invalidate(key) {
+        try {
+            const filePath = this.getFilePath(key);
+            await fs.unlink(filePath);
+            this.dirtyKeys.delete(key);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                if (process.env.DEBUG) {
+                    console.warn(`Failed to delete cache entry ${key}:`, error.message);
+                }
+            }
+        }
+    }
+    /**
+     * Clear all cache entries
+     */
+    async clear() {
+        try {
+            const files = await fs.readdir(this.cacheDir);
+            await Promise.all(files
+                .filter(file => !file.endsWith('.tmp'))
+                .map(file => fs.unlink(path.join(this.cacheDir, file)).catch(() => { })));
+            this.dirtyKeys.clear();
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                if (process.env.DEBUG) {
+                    console.warn('Failed to clear cache:', error.message);
+                }
+            }
+        }
+    }
+    /**
+     * Sync dirty entries to disk
+     */
+    async sync() {
+        // In our implementation, writes are immediate (no write buffering)
+        // This method is here for API compatibility
+        this.dirtyKeys.clear();
+    }
+    /**
+     * Shutdown (flush and cleanup)
+     */
+    async shutdown() {
+        if (this.syncTimer) {
+            clearInterval(this.syncTimer);
+            this.syncTimer = null;
+        }
+        await this.sync();
+        this.initialized = false;
+    }
+    /**
+     * Get cache statistics
+     */
+    async getStats() {
+        try {
+            const files = await fs.readdir(this.cacheDir);
+            const entries = [];
+            for (const file of files) {
+                if (file.endsWith('.tmp')) {
+                    continue;
+                }
+                try {
+                    const content = await fs.readFile(path.join(this.cacheDir, file), 'utf-8');
+                    const entry = JSON.parse(content);
+                    entries.push(entry);
+                }
+                catch {
+                    // Skip corrupted entries
+                }
+            }
+            const totalSize = entries.reduce((sum, entry) => sum + entry.size, 0);
+            const timestamps = entries.map(e => e.createdAt);
+            return {
+                totalEntries: entries.length,
+                totalSize,
+                oldestEntry: timestamps.length > 0 ? Math.min(...timestamps) : null,
+                newestEntry: timestamps.length > 0 ? Math.max(...timestamps) : null,
+            };
+        }
+        catch (error) {
+            return {
+                totalEntries: 0,
+                totalSize: 0,
+                oldestEntry: null,
+                newestEntry: null,
+            };
+        }
+    }
+    /**
+     * Enforce maximum cache size by removing oldest entries
+     */
+    async enforceMaxSize() {
+        try {
+            const files = await fs.readdir(this.cacheDir);
+            const entries = [];
+            // Load all entries
+            for (const file of files) {
+                if (file.endsWith('.tmp')) {
+                    continue;
+                }
+                try {
+                    const filePath = path.join(this.cacheDir, file);
+                    const content = await fs.readFile(filePath, 'utf-8');
+                    const entry = JSON.parse(content);
+                    // Remove expired entries
+                    if (Date.now() > entry.expiresAt) {
+                        await fs.unlink(filePath);
+                        continue;
+                    }
+                    entries.push({ file, entry });
+                }
+                catch {
+                    // Skip corrupted entries
+                }
+            }
+            // Calculate total size
+            const totalSize = entries.reduce((sum, { entry }) => sum + entry.size, 0);
+            // If under limit, we're done
+            if (totalSize <= this.maxSize) {
+                return;
+            }
+            // Sort by creation time (oldest first)
+            entries.sort((a, b) => a.entry.createdAt - b.entry.createdAt);
+            // Remove oldest entries until under limit
+            let currentSize = totalSize;
+            for (const { file, entry } of entries) {
+                if (currentSize <= this.maxSize) {
+                    break;
+                }
+                try {
+                    await fs.unlink(path.join(this.cacheDir, file));
+                    currentSize -= entry.size;
+                }
+                catch {
+                    // Skip deletion errors
+                }
+            }
+        }
+        catch (error) {
+            if (process.env.DEBUG) {
+                console.warn('Failed to enforce max size:', error.message);
+            }
+        }
+    }
+    /**
+     * Ensure cache directory exists
+     */
+    async ensureCacheDir() {
+        try {
+            await fs.mkdir(this.cacheDir, { recursive: true, mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST') {
+                throw new Error(`Failed to create cache directory: ${error.message}`);
+            }
+        }
+    }
+    /**
+     * Get file path for a cache key
+     */
+    getFilePath(key) {
+        // Hash the key to create a safe filename
+        const hash = crypto.createHash('sha256').update(key).digest('hex');
+        return path.join(this.cacheDir, `${hash}.json`);
+    }
+}
+exports.DiskCacheManager = DiskCacheManager;
+/**
+ * Global singleton instance
+ */
+exports.diskCacheManager = new DiskCacheManager();

package/dist/utils/fuzzy.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Fuzzy matching utilities for typo-tolerant name resolution.
+ *
+ * Uses Levenshtein distance (edit distance) to find the closest match
+ * when exact/substring lookups fail. No external dependencies — the
+ * algorithm is ~20 lines of classic dynamic programming.
+ */
+/**
+ * Levenshtein distance — minimum single-char edits (insert, delete, replace)
+ * to transform string `a` into string `b`.
+ *
+ * Classic DP approach, O(m*n) time and O(min(m,n)) space.
+ * Both inputs should be pre-normalized (lowercased/trimmed) by the caller.
+ */
+export declare function levenshtein(a: string, b: string): number;
+/**
+ * Find the best fuzzy match from a list of candidates.
+ *
+ * Returns the candidate with the lowest Levenshtein distance,
+ * but ONLY if the distance is within a dynamic threshold:
+ *   threshold = max(2, floor(query.length / 4))
+ *
+ * - Short names (≤8 chars): allows up to 2 typos
+ * - Longer names: ~25% of query length
+ *
+ * @param query - Normalized search query (lowercase, trimmed)
+ * @param candidates - Array of { key: unique ID, value: normalized name }
+ * @returns Best match { match: key, distance } or null if nothing is close enough
+ */
+export declare function fuzzyMatch(query: string, candidates: {
+    key: string;
+    value: string;
+}[]): {
+    match: string;
+    distance: number;
+} | null;

package/dist/utils/fuzzy.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Fuzzy matching utilities for typo-tolerant name resolution.
+ *
+ * Uses Levenshtein distance (edit distance) to find the closest match
+ * when exact/substring lookups fail. No external dependencies — the
+ * algorithm is ~20 lines of classic dynamic programming.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.levenshtein = levenshtein;
+exports.fuzzyMatch = fuzzyMatch;
+/**
+ * Levenshtein distance — minimum single-char edits (insert, delete, replace)
+ * to transform string `a` into string `b`.
+ *
+ * Classic DP approach, O(m*n) time and O(min(m,n)) space.
+ * Both inputs should be pre-normalized (lowercased/trimmed) by the caller.
+ */
+function levenshtein(a, b) {
+    // Optimization: ensure `a` is the shorter string so we use less memory
+    if (a.length > b.length)
+        [a, b] = [b, a];
+    const m = a.length;
+    const n = b.length;
+    // Single row of the DP matrix (+ previous value), reused per iteration
+    let prev = Array.from({ length: m + 1 }, (_, i) => i);
+    for (let j = 1; j <= n; j++) {
+        const curr = [j]; // first column = number of insertions
+        for (let i = 1; i <= m; i++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[i] = Math.min(curr[i - 1] + 1, // insert
+            prev[i] + 1, // delete
+            prev[i - 1] + cost);
+        }
+        prev = curr;
+    }
+    return prev[m];
+}
+/**
+ * Find the best fuzzy match from a list of candidates.
+ *
+ * Returns the candidate with the lowest Levenshtein distance,
+ * but ONLY if the distance is within a dynamic threshold:
+ *   threshold = max(2, floor(query.length / 4))
+ *
+ * - Short names (≤8 chars): allows up to 2 typos
+ * - Longer names: ~25% of query length
+ *
+ * @param query - Normalized search query (lowercase, trimmed)
+ * @param candidates - Array of { key: unique ID, value: normalized name }
+ * @returns Best match { match: key, distance } or null if nothing is close enough
+ */
+function fuzzyMatch(query, candidates) {
+    const threshold = Math.max(2, Math.floor(query.length / 4));
+    let bestKey = null;
+    let bestDist = threshold + 1; // start above threshold so first valid match wins
+    for (const { key, value } of candidates) {
+        const dist = levenshtein(query, value);
+        if (dist < bestDist) {
+            bestDist = dist;
+            bestKey = key;
+        }
+    }
+    // Only return if we found something within the allowed threshold
+    if (bestKey !== null && bestDist <= threshold) {
+        return { match: bestKey, distance: bestDist };
+    }
+    return null;
+}

package/dist/utils/interactive-navigator.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Interactive Page Navigator
+ *
+ * Provides arrow-key navigation through Notion page trees.
+ * Reuses mapPageStructure() for cached, parallel data fetching.
+ *
+ * Exported functions:
+ * - extractNavigableItems(): filters child_page/child_database from structure (pure)
+ * - buildChoices(): builds @inquirer/select choices array (pure)
+ * - startNavigator(): main navigation loop (side-effectful)
+ */
+import { mapPageStructure } from '../notion';
+/** A navigable item extracted from page structure */
+export interface NavigableItem {
+    id: string;
+    title: string;
+    type: 'child_page' | 'child_database';
+}
+/** A choice for the select prompt */
+export interface NavigatorChoice {
+    name: string;
+    value: string;
+}
+export declare const NAV_BACK = "__nav_back__";
+export declare const NAV_QUIT = "__nav_quit__";
+/**
+ * Extract navigable items (child pages and databases) from page structure.
+ * Pure function — no side effects.
+ *
+ * @param structure - The structure array from mapPageStructure()
+ * @returns Filtered list of navigable items
+ */
+export declare function extractNavigableItems(structure: Array<{
+    type: string;
+    id: string;
+    title?: string;
+}>): NavigableItem[];
+/**
+ * Build choices array for @inquirer/select.
+ * Pure function — no side effects.
+ *
+ * @param items - Navigable items to display
+ * @param hasParent - Whether to show ".. Back" option
+ * @returns Choices array with navigation items, Back, and Quit
+ */
+export declare function buildChoices(items: NavigableItem[], hasParent: boolean): NavigatorChoice[];
+/** Dependencies injectable for testing */
+export interface NavigatorDeps {
+    selectFn: (config: {
+        message: string;
+        choices: NavigatorChoice[];
+    }) => Promise<string>;
+    fetchStructure: (pageId: string) => ReturnType<typeof mapPageStructure>;
+}
+/**
+ * Main interactive navigation loop.
+ * Fetches page structure, displays select prompt, navigates on selection.
+ *
+ * @param startPageId - The page ID to start navigating from
+ * @param log - Logging function (typically this.log from oclif)
+ * @param deps - Injectable dependencies (for testing)
+ */
+export declare function startNavigator(startPageId: string, log: (msg: string) => void, deps?: NavigatorDeps): Promise<void>;

package/dist/utils/interactive-navigator.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Interactive Page Navigator
+ *
+ * Provides arrow-key navigation through Notion page trees.
+ * Reuses mapPageStructure() for cached, parallel data fetching.
+ *
+ * Exported functions:
+ * - extractNavigableItems(): filters child_page/child_database from structure (pure)
+ * - buildChoices(): builds @inquirer/select choices array (pure)
+ * - startNavigator(): main navigation loop (side-effectful)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAV_QUIT = exports.NAV_BACK = void 0;
+exports.extractNavigableItems = extractNavigableItems;
+exports.buildChoices = buildChoices;
+exports.startNavigator = startNavigator;
+const select_1 = require("@inquirer/select");
+const notion_1 = require("../notion");
+const errors_1 = require("../errors");
+// Sentinel values for navigation actions
+exports.NAV_BACK = '__nav_back__';
+exports.NAV_QUIT = '__nav_quit__';
+/**
+ * Extract navigable items (child pages and databases) from page structure.
+ * Pure function — no side effects.
+ *
+ * @param structure - The structure array from mapPageStructure()
+ * @returns Filtered list of navigable items
+ */
+function extractNavigableItems(structure) {
+    return structure
+        .filter((item) => item.type === 'child_page' || item.type === 'child_database')
+        .map((item) => ({
+        id: item.id,
+        title: item.title || 'Untitled',
+        type: item.type,
+    }));
+}
+/**
+ * Build choices array for @inquirer/select.
+ * Pure function — no side effects.
+ *
+ * @param items - Navigable items to display
+ * @param hasParent - Whether to show ".. Back" option
+ * @returns Choices array with navigation items, Back, and Quit
+ */
+function buildChoices(items, hasParent) {
+    const choices = [];
+    // Back option at top when not at root
+    if (hasParent) {
+        choices.push({ name: '.. Back', value: exports.NAV_BACK });
+    }
+    // Child pages and databases
+    for (const item of items) {
+        const prefix = item.type === 'child_database' ? '[DB] ' : '';
+        choices.push({ name: `${prefix}${item.title}`, value: item.id });
+    }
+    // Quit at bottom
+    choices.push({ name: '[Quit]', value: exports.NAV_QUIT });
+    return choices;
+}
+// Default deps use real implementations
+const defaultDeps = {
+    selectFn: (config) => (0, select_1.default)(config),
+    fetchStructure: notion_1.mapPageStructure,
+};
+/**
+ * Main interactive navigation loop.
+ * Fetches page structure, displays select prompt, navigates on selection.
+ *
+ * @param startPageId - The page ID to start navigating from
+ * @param log - Logging function (typically this.log from oclif)
+ * @param deps - Injectable dependencies (for testing)
+ */
+async function startNavigator(startPageId, log, deps = defaultDeps) {
+    // Guard: must be interactive terminal
+    if (!process.stdin.isTTY) {
+        throw new errors_1.NotionCLIError(errors_1.NotionCLIErrorCode.VALIDATION_ERROR, 'browse requires an interactive terminal (TTY)', [{ description: 'Run this command in a terminal, not piped or in CI' }]);
+    }
+    // Navigation history stack — push on enter, pop on back
+    const history = [];
+    let currentPageId = startPageId;
+    // Navigation loop
+    while (true) {
+        let pageData;
+        try {
+            pageData = await deps.fetchStructure(currentPageId);
+        }
+        catch (error) {
+            throw error instanceof errors_1.NotionCLIError ? error : (0, errors_1.wrapNotionError)(error, {
+                resourceType: 'page',
+                attemptedId: currentPageId,
+                endpoint: 'pages.retrieve',
+            });
+        }
+        const items = extractNavigableItems(pageData.structure);
+        const icon = pageData.icon || '';
+        const header = `${icon}${icon ? ' ' : ''}${pageData.title}  (${items.length} children)`;
+        log(`\n${header}`);
+        const choices = buildChoices(items, history.length > 0);
+        // Nothing to navigate if no children and no parent
+        if (items.length === 0 && history.length === 0) {
+            log('No child pages or databases found.');
+            return;
+        }
+        const selected = await deps.selectFn({
+            message: 'Navigate to:',
+            choices,
+        });
+        if (selected === exports.NAV_QUIT) {
+            return;
+        }
+        if (selected === exports.NAV_BACK) {
+            // Pop from history to go back
+            currentPageId = history.pop();
+            continue;
+        }
+        // Navigate into selected page
+        history.push(currentPageId);
+        currentPageId = selected;
+    }
+}

package/dist/utils/markdown-to-blocks.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Converts markdown text to Notion block objects
+ *
+ * This is a simple, secure replacement for @tryfabric/martian's markdownToBlocks
+ * to eliminate security vulnerabilities from the katex dependency chain.
+ *
+ * Supports:
+ * - Headings (h1, h2, h3)
+ * - Paragraphs
+ * - Bulleted lists
+ * - Numbered lists
+ * - Checkboxes (to_do blocks)
+ * - Code blocks
+ * - Tables (with header detection)
+ * - Quotes
+ * - Bold, italic, strikethrough, and inline code formatting
+ *
+ * @param markdown - The markdown string to convert
+ * @returns Array of Notion block objects
+ */
+export declare function markdownToBlocks(markdown: string): any[];