@catafal/notion-cli 5.9.0

package/dist/base-command.js

@@ -0,0 +1,179 @@
+"use strict";
+/**
+ * Base Command with Envelope Support
+ *
+ * Extends oclif Command with automatic envelope wrapping for consistent JSON output.
+ * All commands should extend this class to get automatic envelope support.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvelopeFlags = exports.BaseCommand = void 0;
+const core_1 = require("@oclif/core");
+const envelope_1 = require("./envelope");
+const index_1 = require("./errors/index");
+const disk_cache_1 = require("./utils/disk-cache");
+const http_agent_1 = require("./http-agent");
+/**
+ * BaseCommand - Extends oclif Command with envelope support
+ *
+ * Features:
+ * - Automatic envelope wrapping for JSON output
+ * - Consistent error handling
+ * - Execution time tracking
+ * - Version metadata injection
+ * - Stdout/stderr separation
+ */
+class BaseCommand extends core_1.Command {
+    constructor() {
+        super(...arguments);
+        this.shouldUseEnvelope = false;
+    }
+    /**
+     * Initialize command and create envelope formatter
+     */
+    async init() {
+        var _a;
+        await super.init();
+        // Initialize disk cache (load from disk)
+        const diskCacheEnabled = process.env.NOTION_CLI_DISK_CACHE_ENABLED !== 'false';
+        if (diskCacheEnabled) {
+            try {
+                await disk_cache_1.diskCacheManager.initialize();
+            }
+            catch (error) {
+                // Silently ignore disk cache initialization errors
+                if (process.env.DEBUG) {
+                    console.error('Failed to initialize disk cache:', error);
+                }
+            }
+        }
+        // Get command name from ID (e.g., "page:retrieve" -> "page retrieve")
+        const commandName = ((_a = this.id) === null || _a === void 0 ? void 0 : _a.replace(/:/g, ' ')) || 'unknown';
+        // Get version from config
+        const version = this.config.version;
+        // Initialize envelope formatter
+        this.envelope = new envelope_1.EnvelopeFormatter(commandName, version);
+    }
+    /**
+     * Cleanup hook - flushes disk cache and destroys HTTP agents before exit
+     */
+    async finally(error) {
+        // Destroy HTTP agents to close all connections
+        try {
+            (0, http_agent_1.destroyAgents)();
+        }
+        catch (agentError) {
+            // Silently ignore agent cleanup errors
+            if (process.env.DEBUG) {
+                console.error('Failed to destroy HTTP agents:', agentError);
+            }
+        }
+        // Flush disk cache before exit
+        const diskCacheEnabled = process.env.NOTION_CLI_DISK_CACHE_ENABLED !== 'false';
+        if (diskCacheEnabled) {
+            try {
+                await disk_cache_1.diskCacheManager.shutdown();
+            }
+            catch (shutdownError) {
+                // Silently ignore shutdown errors
+                if (process.env.DEBUG) {
+                    console.error('Failed to shutdown disk cache:', shutdownError);
+                }
+            }
+        }
+        await super.finally(error);
+    }
+    /**
+     * Determine if envelope should be used based on flags
+     */
+    checkEnvelopeUsage(flags) {
+        return !!(flags.json || flags['compact-json']);
+    }
+    /**
+     * Output success response with automatic envelope wrapping
+     *
+     * @param data - Response data
+     * @param flags - Command flags
+     * @param additionalMetadata - Optional metadata to include
+     */
+    outputSuccess(data, flags, additionalMetadata) {
+        // Check if we should use envelope
+        this.shouldUseEnvelope = this.checkEnvelopeUsage(flags);
+        if (this.shouldUseEnvelope) {
+            const envelope = this.envelope.wrapSuccess(data, additionalMetadata);
+            this.envelope.outputEnvelope(envelope, flags, this.log.bind(this));
+            process.exit(this.envelope.getExitCode(envelope));
+        }
+        else {
+            // Non-envelope output (table, markdown, etc.) - handled by caller
+            // This path should not normally be reached as caller handles non-JSON output
+            throw new Error('outputSuccess should only be called for JSON output');
+        }
+    }
+    /**
+     * Output error response with automatic envelope wrapping
+     *
+     * @param error - Error object
+     * @param flags - Command flags
+     * @param additionalContext - Optional error context
+     */
+    outputError(error, flags, additionalContext) {
+        // Wrap raw errors in NotionCLIError
+        const cliError = error instanceof index_1.NotionCLIError ? error : (0, index_1.wrapNotionError)(error);
+        // Check if we should use envelope
+        this.shouldUseEnvelope = this.checkEnvelopeUsage(flags);
+        if (this.shouldUseEnvelope) {
+            const envelope = this.envelope.wrapError(cliError, additionalContext);
+            this.envelope.outputEnvelope(envelope, flags, this.log.bind(this));
+            process.exit(this.envelope.getExitCode(envelope));
+        }
+        else {
+            // Non-JSON mode - use oclif's error handling
+            this.error(cliError.message, { exit: this.getExitCodeForError(cliError) });
+        }
+    }
+    /**
+     * Get appropriate exit code for error
+     */
+    getExitCodeForError(error) {
+        // CLI validation errors
+        if (error.code === 'VALIDATION_ERROR') {
+            return envelope_1.ExitCode.CLI_ERROR;
+        }
+        // API errors (default)
+        return envelope_1.ExitCode.API_ERROR;
+    }
+    /**
+     * Catch handler that ensures proper envelope error output
+     */
+    async catch(error) {
+        // If command has already handled the error via outputError, just propagate
+        if (error.exitCode !== undefined) {
+            throw error;
+        }
+        // Otherwise, wrap and handle the error
+        const cliError = (0, index_1.wrapNotionError)(error);
+        this.error(cliError.message, { exit: this.getExitCodeForError(cliError) });
+    }
+}
+exports.BaseCommand = BaseCommand;
+/**
+ * Standard flags that all envelope-enabled commands should include
+ */
+exports.EnvelopeFlags = {
+    json: core_1.Flags.boolean({
+        char: 'j',
+        description: 'Output as JSON envelope (recommended for automation)',
+        default: false,
+    }),
+    'compact-json': core_1.Flags.boolean({
+        char: 'c',
+        description: 'Output as compact JSON envelope (single-line, ideal for piping)',
+        default: false,
+        exclusive: ['markdown', 'pretty'],
+    }),
+    raw: core_1.Flags.boolean({
+        char: 'r',
+        description: 'Output raw API response without envelope (legacy mode)',
+        default: false,
+    }),
+};

package/dist/base-flags.d.ts

@@ -0,0 +1,14 @@
+export declare const AutomationFlags: {
+    json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    'page-size': import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
+    retry: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    timeout: import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
+    'no-cache': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    verbose: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    minimal: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+};
+export declare const OutputFormatFlags: {
+    markdown: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    'compact-json': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    pretty: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+};

package/dist/base-flags.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutputFormatFlags = exports.AutomationFlags = void 0;
+const core_1 = require("@oclif/core");
+exports.AutomationFlags = {
+    json: core_1.Flags.boolean({
+        char: 'j',
+        description: 'Output as JSON (recommended for automation)',
+        default: false,
+    }),
+    'page-size': core_1.Flags.integer({
+        description: 'Items per page (1-100, default: 100 for automation)',
+        min: 1,
+        max: 100,
+        default: 100,
+    }),
+    retry: core_1.Flags.boolean({
+        description: 'Auto-retry on rate limit (respects Retry-After header)',
+        default: true,
+    }),
+    timeout: core_1.Flags.integer({
+        description: 'Request timeout in milliseconds',
+        default: 30000,
+    }),
+    'no-cache': core_1.Flags.boolean({
+        description: 'Bypass cache and force fresh API calls',
+        default: false,
+    }),
+    verbose: core_1.Flags.boolean({
+        char: 'v',
+        description: 'Enable verbose logging to stderr (retry events, cache stats) - never pollutes stdout',
+        default: false,
+        env: 'NOTION_CLI_VERBOSE',
+    }),
+    minimal: core_1.Flags.boolean({
+        description: 'Strip unnecessary metadata (created_by, last_edited_by, object fields, request_id, etc.) - reduces response size by ~40%',
+        default: false,
+    }),
+};
+exports.OutputFormatFlags = {
+    markdown: core_1.Flags.boolean({
+        char: 'm',
+        description: 'Output as markdown table (GitHub-flavored)',
+        default: false,
+        exclusive: ['compact-json', 'pretty'],
+    }),
+    'compact-json': core_1.Flags.boolean({
+        char: 'c',
+        description: 'Output as compact JSON (single-line, ideal for piping)',
+        default: false,
+        exclusive: ['markdown', 'pretty'],
+    }),
+    pretty: core_1.Flags.boolean({
+        char: 'P',
+        description: 'Output as pretty table with borders',
+        default: false,
+        exclusive: ['markdown', 'compact-json'],
+    }),
+};

package/dist/cache.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Simple in-memory caching layer for Notion API responses
+ * Supports TTL (time-to-live) and cache invalidation
+ * Integrated with disk cache for persistence across CLI invocations
+ */
+export interface CacheEntry<T> {
+    data: T;
+    timestamp: number;
+    ttl: number;
+}
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    sets: number;
+    evictions: number;
+    size: number;
+}
+export interface CacheConfig {
+    enabled: boolean;
+    defaultTtl: number;
+    maxSize: number;
+    ttlByType: {
+        dataSource: number;
+        database: number;
+        user: number;
+        page: number;
+        block: number;
+    };
+}
+export declare class CacheManager {
+    private cache;
+    private stats;
+    private config;
+    constructor(config?: Partial<CacheConfig>);
+    /**
+     * Generate a cache key from resource type and identifiers
+     */
+    private generateKey;
+    /**
+     * Check if a cache entry is still valid
+     */
+    private isValid;
+    /**
+     * Evict expired entries
+     */
+    private evictExpired;
+    /**
+     * Evict oldest entries if cache is full
+     */
+    private evictOldest;
+    /**
+     * Get a value from cache (checks memory, then disk)
+     */
+    get<T>(type: string, ...identifiers: Array<string | number | object>): Promise<T | null>;
+    /**
+     * Set a value in cache with optional custom TTL (writes to memory and disk)
+     */
+    set<T>(type: string, data: T, customTtl?: number, ...identifiers: Array<string | number | object>): void;
+    /**
+     * Invalidate specific cache entries by type and optional identifiers
+     */
+    invalidate(type: string, ...identifiers: Array<string | number | object>): void;
+    /**
+     * Clear all cache entries (memory and disk)
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Get cache hit rate
+     */
+    getHitRate(): number;
+    /**
+     * Check if cache is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get current configuration
+     */
+    getConfig(): CacheConfig;
+}
+export declare const cacheManager: CacheManager;

package/dist/cache.js

@@ -0,0 +1,351 @@
+"use strict";
+/**
+ * Simple in-memory caching layer for Notion API responses
+ * Supports TTL (time-to-live) and cache invalidation
+ * Integrated with disk cache for persistence across CLI invocations
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cacheManager = exports.CacheManager = void 0;
+const disk_cache_1 = require("./utils/disk-cache");
+/**
+ * Check if verbose logging is enabled
+ */
+function isVerboseEnabled() {
+    return process.env.DEBUG === 'true' ||
+        process.env.NOTION_CLI_DEBUG === 'true' ||
+        process.env.NOTION_CLI_VERBOSE === 'true';
+}
+/**
+ * Log structured cache event to stderr
+ * Never pollutes stdout - safe for JSON output
+ */
+function logCacheEvent(event) {
+    // Only log if verbose mode is enabled
+    if (!isVerboseEnabled()) {
+        return;
+    }
+    // Always write to stderr, never stdout
+    console.error(JSON.stringify(event));
+}
+class CacheManager {
+    constructor(config) {
+        this.cache = new Map();
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            sets: 0,
+            evictions: 0,
+            size: 0,
+        };
+        // Default configuration
+        this.config = {
+            enabled: process.env.NOTION_CLI_CACHE_ENABLED !== 'false',
+            defaultTtl: parseInt(process.env.NOTION_CLI_CACHE_TTL || '300000', 10), // 5 minutes default
+            maxSize: parseInt(process.env.NOTION_CLI_CACHE_MAX_SIZE || '1000', 10),
+            ttlByType: {
+                dataSource: parseInt(process.env.NOTION_CLI_CACHE_DS_TTL || '600000', 10), // 10 min
+                database: parseInt(process.env.NOTION_CLI_CACHE_DB_TTL || '600000', 10), // 10 min
+                user: parseInt(process.env.NOTION_CLI_CACHE_USER_TTL || '3600000', 10), // 1 hour
+                page: parseInt(process.env.NOTION_CLI_CACHE_PAGE_TTL || '60000', 10), // 1 min
+                block: parseInt(process.env.NOTION_CLI_CACHE_BLOCK_TTL || '30000', 10), // 30 sec
+            },
+            ...config,
+        };
+    }
+    /**
+     * Generate a cache key from resource type and identifiers
+     */
+    generateKey(type, ...identifiers) {
+        return `${type}:${identifiers.map(id => typeof id === 'object' ? JSON.stringify(id) : String(id)).join(':')}`;
+    }
+    /**
+     * Check if a cache entry is still valid
+     */
+    isValid(entry) {
+        const now = Date.now();
+        return now - entry.timestamp < entry.ttl;
+    }
+    /**
+     * Evict expired entries
+     */
+    evictExpired() {
+        let evictedCount = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            if (!this.isValid(entry)) {
+                this.cache.delete(key);
+                this.stats.evictions++;
+                evictedCount++;
+            }
+        }
+        this.stats.size = this.cache.size;
+        // Log eviction event if any entries were evicted
+        if (evictedCount > 0 && isVerboseEnabled()) {
+            logCacheEvent({
+                level: 'debug',
+                event: 'cache_evict',
+                namespace: 'expired',
+                cache_size: this.cache.size,
+                timestamp: new Date().toISOString(),
+            });
+        }
+    }
+    /**
+     * Evict oldest entries if cache is full
+     */
+    evictOldest() {
+        if (this.cache.size >= this.config.maxSize) {
+            // Find and remove oldest entry
+            let oldestKey = null;
+            let oldestTime = Infinity;
+            for (const [key, entry] of this.cache.entries()) {
+                if (entry.timestamp < oldestTime) {
+                    oldestTime = entry.timestamp;
+                    oldestKey = key;
+                }
+            }
+            if (oldestKey) {
+                this.cache.delete(oldestKey);
+                this.stats.evictions++;
+                // Log LRU eviction
+                logCacheEvent({
+                    level: 'debug',
+                    event: 'cache_evict',
+                    namespace: 'lru',
+                    key: oldestKey,
+                    cache_size: this.cache.size,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+        }
+    }
+    /**
+     * Get a value from cache (checks memory, then disk)
+     */
+    async get(type, ...identifiers) {
+        if (!this.config.enabled) {
+            return null;
+        }
+        const key = this.generateKey(type, ...identifiers);
+        const entry = this.cache.get(key);
+        // Check memory cache first
+        if (entry && this.isValid(entry)) {
+            this.stats.hits++;
+            // Log cache hit
+            logCacheEvent({
+                level: 'debug',
+                event: 'cache_hit',
+                namespace: type,
+                key: identifiers.join(':'),
+                age_ms: Date.now() - entry.timestamp,
+                ttl_ms: entry.ttl,
+                timestamp: new Date().toISOString(),
+            });
+            return entry.data;
+        }
+        // Remove invalid memory entry
+        if (entry) {
+            this.cache.delete(key);
+            this.stats.evictions++;
+            // Log eviction event
+            logCacheEvent({
+                level: 'debug',
+                event: 'cache_evict',
+                namespace: type,
+                key: identifiers.join(':'),
+                cache_size: this.cache.size,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        // Check disk cache (only if enabled)
+        const diskEnabled = process.env.NOTION_CLI_DISK_CACHE_ENABLED !== 'false';
+        if (diskEnabled) {
+            try {
+                const diskEntry = await disk_cache_1.diskCacheManager.get(key);
+                if (diskEntry && diskEntry.data) {
+                    const entry = diskEntry.data;
+                    // Validate disk entry
+                    if (this.isValid(entry)) {
+                        // Promote to memory cache
+                        this.cache.set(key, entry);
+                        this.stats.hits++;
+                        // Log cache hit (from disk)
+                        logCacheEvent({
+                            level: 'debug',
+                            event: 'cache_hit',
+                            namespace: type,
+                            key: identifiers.join(':'),
+                            age_ms: Date.now() - entry.timestamp,
+                            ttl_ms: entry.ttl,
+                            timestamp: new Date().toISOString(),
+                        });
+                        return entry.data;
+                    }
+                    else {
+                        // Remove expired disk entry
+                        disk_cache_1.diskCacheManager.invalidate(key).catch(() => { });
+                    }
+                }
+            }
+            catch (error) {
+                // Silently ignore disk cache errors
+            }
+        }
+        // Cache miss
+        this.stats.misses++;
+        // Log cache miss
+        logCacheEvent({
+            level: 'debug',
+            event: 'cache_miss',
+            namespace: type,
+            key: identifiers.join(':'),
+            timestamp: new Date().toISOString(),
+        });
+        return null;
+    }
+    /**
+     * Set a value in cache with optional custom TTL (writes to memory and disk)
+     */
+    set(type, data, customTtl, ...identifiers) {
+        if (!this.config.enabled) {
+            return;
+        }
+        // Evict expired entries periodically
+        if (this.cache.size > 0 && Math.random() < 0.1) {
+            this.evictExpired();
+        }
+        // Evict oldest if at capacity
+        this.evictOldest();
+        const key = this.generateKey(type, ...identifiers);
+        const ttl = customTtl || this.config.ttlByType[type] || this.config.defaultTtl;
+        const entry = {
+            data,
+            timestamp: Date.now(),
+            ttl,
+        };
+        this.cache.set(key, entry);
+        this.stats.sets++;
+        this.stats.size = this.cache.size;
+        // Log cache set
+        logCacheEvent({
+            level: 'debug',
+            event: 'cache_set',
+            namespace: type,
+            key: identifiers.join(':'),
+            ttl_ms: ttl,
+            cache_size: this.cache.size,
+            timestamp: new Date().toISOString(),
+        });
+        // Async write to disk cache (fire-and-forget)
+        const diskEnabled = process.env.NOTION_CLI_DISK_CACHE_ENABLED !== 'false';
+        if (diskEnabled) {
+            disk_cache_1.diskCacheManager.set(key, entry, ttl).catch(() => {
+                // Silently ignore disk cache errors
+            });
+        }
+    }
+    /**
+     * Invalidate specific cache entries by type and optional identifiers
+     */
+    invalidate(type, ...identifiers) {
+        const diskEnabled = process.env.NOTION_CLI_DISK_CACHE_ENABLED !== 'false';
+        if (identifiers.length === 0) {
+            // Invalidate all entries of this type
+            const pattern = `${type}:`;
+            let invalidatedCount = 0;
+            for (const key of this.cache.keys()) {
+                if (key.startsWith(pattern)) {
+                    this.cache.delete(key);
+                    this.stats.evictions++;
+                    invalidatedCount++;
+                    // Also invalidate from disk (fire-and-forget)
+                    if (diskEnabled) {
+                        disk_cache_1.diskCacheManager.invalidate(key).catch(() => { });
+                    }
+                }
+            }
+            // Log bulk invalidation
+            if (invalidatedCount > 0) {
+                logCacheEvent({
+                    level: 'debug',
+                    event: 'cache_invalidate',
+                    namespace: type,
+                    cache_size: this.cache.size,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+        }
+        else {
+            // Invalidate specific entry
+            const key = this.generateKey(type, ...identifiers);
+            if (this.cache.delete(key)) {
+                this.stats.evictions++;
+                // Also invalidate from disk (fire-and-forget)
+                if (diskEnabled) {
+                    disk_cache_1.diskCacheManager.invalidate(key).catch(() => { });
+                }
+                // Log specific invalidation
+                logCacheEvent({
+                    level: 'debug',
+                    event: 'cache_invalidate',
+                    namespace: type,
+                    key: identifiers.join(':'),
+                    cache_size: this.cache.size,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+        }
+        this.stats.size = this.cache.size;
+    }
+    /**
+     * Clear all cache entries (memory and disk)
+     */
+    clear() {
+        const previousSize = this.cache.size;
+        this.cache.clear();
+        this.stats.evictions += this.stats.size;
+        this.stats.size = 0;
+        // Also clear disk cache (fire-and-forget)
+        const diskEnabled = process.env.NOTION_CLI_DISK_CACHE_ENABLED !== 'false';
+        if (diskEnabled) {
+            disk_cache_1.diskCacheManager.clear().catch(() => { });
+        }
+        // Log cache clear
+        if (previousSize > 0) {
+            logCacheEvent({
+                level: 'info',
+                event: 'cache_invalidate',
+                namespace: 'all',
+                cache_size: 0,
+                timestamp: new Date().toISOString(),
+            });
+        }
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Get cache hit rate
+     */
+    getHitRate() {
+        const total = this.stats.hits + this.stats.misses;
+        return total > 0 ? this.stats.hits / total : 0;
+    }
+    /**
+     * Check if cache is enabled
+     */
+    isEnabled() {
+        return this.config.enabled;
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+exports.CacheManager = CacheManager;
+// Singleton instance
+exports.cacheManager = new CacheManager();