@catafal/notion-cli 5.9.0

package/dist/utils/shell-config.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Shell Configuration Utility
+ *
+ * Detects the user's shell and persists environment variables (e.g., NOTION_TOKEN)
+ * to the appropriate rc file (.zshrc, .bashrc, etc.).
+ *
+ * Used by both `config set-token` and `init` commands to avoid duplicating
+ * shell detection and rc file writing logic.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectShell = detectShell;
+exports.getRcFilePath = getRcFilePath;
+exports.persistToken = persistToken;
+const fs = require("fs/promises");
+const path = require("path");
+const os = require("os");
+/**
+ * Detect the current shell from the SHELL environment variable.
+ * Falls back to bash on Unix, powershell on Windows.
+ */
+function detectShell() {
+    const shell = process.env.SHELL || '';
+    if (shell.includes('zsh'))
+        return 'zsh';
+    if (shell.includes('bash'))
+        return 'bash';
+    if (shell.includes('fish'))
+        return 'fish';
+    return process.platform === 'win32' ? 'powershell' : 'bash';
+}
+/**
+ * Resolve the path to the shell's rc/config file.
+ */
+function getRcFilePath(shell) {
+    const home = os.homedir();
+    switch (shell) {
+        case 'zsh':
+            return path.join(home, '.zshrc');
+        case 'bash':
+            return path.join(home, '.bashrc');
+        case 'fish':
+            return path.join(home, '.config', 'fish', 'config.fish');
+        case 'powershell':
+            return path.join(home, 'Documents', 'PowerShell', 'Microsoft.PowerShell_profile.ps1');
+        default:
+            return path.join(home, '.bashrc');
+    }
+}
+/**
+ * Persist a Notion token to the user's shell rc file.
+ *
+ * Reads the rc file, checks if NOTION_TOKEN already exists (replaces it if so),
+ * otherwise appends a new export line. Creates the file if it doesn't exist.
+ *
+ * Returns the shell name and rc file path so callers can inform the user.
+ */
+async function persistToken(token) {
+    const shell = detectShell();
+    const rcFile = getRcFilePath(shell);
+    // Read existing rc file (create if missing)
+    let rcContent = '';
+    try {
+        rcContent = await fs.readFile(rcFile, 'utf-8');
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code !== 'ENOENT') {
+            throw error;
+        }
+        // File doesn't exist — will be created on write
+    }
+    // Upsert the NOTION_TOKEN export line
+    const tokenLineRegex = /^export\s+NOTION_TOKEN=.*/gm;
+    const newTokenLine = `export NOTION_TOKEN="${token}"`;
+    let updatedContent;
+    if (tokenLineRegex.test(rcContent)) {
+        updatedContent = rcContent.replace(tokenLineRegex, newTokenLine);
+    }
+    else {
+        updatedContent = rcContent.trim() + '\n\n# Notion CLI Token\n' + newTokenLine + '\n';
+    }
+    await fs.writeFile(rcFile, updatedContent, 'utf-8');
+    return { rcFile, shell };
+}

package/dist/utils/table-formatter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Table formatting utility to replace oclif v2's ux.table
+ * Provides backward-compatible table flags and formatting
+ */
+/**
+ * Table flags compatible with oclif v2's ux.table.flags()
+ */
+export declare const tableFlags: {
+    columns: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+    sort: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+    filter: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+    csv: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    extended: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    'no-truncate': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    'no-header': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+};
+export interface ColumnOptions<T> {
+    header?: string;
+    get?: (row: T) => any;
+    extended?: boolean;
+    minWidth?: number;
+}
+export interface TableOptions {
+    columns?: string;
+    sort?: string;
+    filter?: string;
+    csv?: boolean;
+    extended?: boolean;
+    'no-truncate'?: boolean;
+    'no-header'?: boolean;
+    printLine?: (s: string) => void;
+}
+/**
+ * Format and display a table (compatible with oclif v2's ux.table)
+ */
+export declare function formatTable<T extends Record<string, any>>(data: T[], columns: Record<string, ColumnOptions<T>>, options?: TableOptions): void;

package/dist/utils/table-formatter.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * Table formatting utility to replace oclif v2's ux.table
+ * Provides backward-compatible table flags and formatting
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tableFlags = void 0;
+exports.formatTable = formatTable;
+const core_1 = require("@oclif/core");
+const Table = require("cli-table3");
+/**
+ * Table flags compatible with oclif v2's ux.table.flags()
+ */
+exports.tableFlags = {
+    columns: core_1.Flags.string({
+        description: 'Only show provided columns (comma-separated)',
+        exclusive: ['extended'],
+    }),
+    sort: core_1.Flags.string({
+        description: 'Property to sort by (prepend with - for descending)',
+    }),
+    filter: core_1.Flags.string({
+        description: 'Filter property by substring match',
+    }),
+    csv: core_1.Flags.boolean({
+        description: 'Output in CSV format',
+        exclusive: ['no-truncate'],
+    }),
+    extended: core_1.Flags.boolean({
+        char: 'x',
+        description: 'Show extra columns',
+    }),
+    'no-truncate': core_1.Flags.boolean({
+        description: 'Do not truncate output to fit screen',
+        exclusive: ['csv'],
+    }),
+    'no-header': core_1.Flags.boolean({
+        description: 'Hide table header from output',
+    }),
+};
+/**
+ * Format and display a table (compatible with oclif v2's ux.table)
+ */
+function formatTable(data, columns, options = {}) {
+    if (data.length === 0) {
+        return;
+    }
+    const printLine = options.printLine || console.log;
+    // Filter columns based on options
+    let selectedColumns = Object.keys(columns);
+    if (options.columns) {
+        const requestedCols = options.columns.split(',').map(c => c.trim());
+        selectedColumns = selectedColumns.filter(col => requestedCols.includes(col));
+    }
+    if (!options.extended) {
+        selectedColumns = selectedColumns.filter(col => !columns[col].extended);
+    }
+    // Filter rows
+    let filteredData = data;
+    if (options.filter) {
+        const [filterCol, filterVal] = options.filter.split('=');
+        if (filterVal) {
+            filteredData = data.filter(row => {
+                var _a;
+                const val = ((_a = columns[filterCol]) === null || _a === void 0 ? void 0 : _a.get) ? columns[filterCol].get(row) : row[filterCol];
+                return String(val).includes(filterVal);
+            });
+        }
+    }
+    // Sort data
+    if (options.sort) {
+        const descending = options.sort.startsWith('-');
+        const sortCol = descending ? options.sort.slice(1) : options.sort;
+        filteredData = [...filteredData].sort((a, b) => {
+            var _a, _b;
+            const aVal = ((_a = columns[sortCol]) === null || _a === void 0 ? void 0 : _a.get) ? columns[sortCol].get(a) : a[sortCol];
+            const bVal = ((_b = columns[sortCol]) === null || _b === void 0 ? void 0 : _b.get) ? columns[sortCol].get(b) : b[sortCol];
+            const comparison = String(aVal).localeCompare(String(bVal));
+            return descending ? -comparison : comparison;
+        });
+    }
+    // Output as CSV
+    if (options.csv) {
+        if (!options['no-header']) {
+            const headers = selectedColumns.map(col => columns[col].header || col);
+            printLine(headers.join(','));
+        }
+        filteredData.forEach(row => {
+            const values = selectedColumns.map(col => {
+                const val = columns[col].get ? columns[col].get(row) : row[col];
+                const str = String(val || '');
+                // Escape CSV values
+                return str.includes(',') || str.includes('"') ? `"${str.replace(/"/g, '""')}"` : str;
+            });
+            printLine(values.join(','));
+        });
+        return;
+    }
+    // Output as table
+    const headers = selectedColumns.map(col => columns[col].header || col);
+    // Respect NO_COLOR standard (https://no-color.org) — disables ANSI codes for
+    // CI/CD logs, screen readers, piped output, and AI agent consumption
+    const useColor = !process.env.NO_COLOR;
+    const table = new Table({
+        head: options['no-header'] ? [] : headers,
+        style: {
+            head: useColor ? ['cyan'] : [],
+            border: useColor ? ['gray'] : [],
+        },
+        wordWrap: !options['no-truncate'],
+        colWidths: selectedColumns.map(col => {
+            if (options['no-truncate'])
+                return undefined;
+            return columns[col].minWidth || undefined;
+        }),
+    });
+    filteredData.forEach(row => {
+        const values = selectedColumns.map(col => {
+            const val = columns[col].get ? columns[col].get(row) : row[col];
+            return String(val !== undefined && val !== null ? val : '');
+        });
+        table.push(values);
+    });
+    printLine(table.toString());
+}

package/dist/utils/templates.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Templates Utility
+ *
+ * Reusable page presets — a named set of properties, optional body content,
+ * and optional icon. Templates are NOT tied to a specific database; properties
+ * are stored in simple format and expanded against the target schema at runtime.
+ *
+ * Stored at ~/.notion-cli/templates.json alongside bookmarks and daily config.
+ */
+export interface Template {
+    properties?: Record<string, any>;
+    content?: string;
+    icon?: string;
+}
+export interface TemplatesData {
+    version: string;
+    templates: Record<string, Template>;
+}
+/** Load templates from disk. Returns empty structure if file doesn't exist. */
+export declare function loadTemplates(): Promise<TemplatesData>;
+/** Save templates to disk (atomic write via tmp + rename). */
+export declare function saveTemplates(data: TemplatesData): Promise<void>;
+/** Get a single template by name. Returns null if not found. */
+export declare function getTemplate(name: string): Promise<Template | null>;
+/** Save or update a template. */
+export declare function setTemplate(name: string, template: Template): Promise<void>;
+/** Remove a template. Returns true if it existed. */
+export declare function removeTemplate(name: string): Promise<boolean>;
+/** List all template names. */
+export declare function listTemplateNames(): Promise<string[]>;

package/dist/utils/templates.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * Templates Utility
+ *
+ * Reusable page presets — a named set of properties, optional body content,
+ * and optional icon. Templates are NOT tied to a specific database; properties
+ * are stored in simple format and expanded against the target schema at runtime.
+ *
+ * Stored at ~/.notion-cli/templates.json alongside bookmarks and daily config.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadTemplates = loadTemplates;
+exports.saveTemplates = saveTemplates;
+exports.getTemplate = getTemplate;
+exports.setTemplate = setTemplate;
+exports.removeTemplate = removeTemplate;
+exports.listTemplateNames = listTemplateNames;
+const fs = require("fs/promises");
+const path = require("path");
+const workspace_cache_1 = require("./workspace-cache");
+// -- Constants --
+const TEMPLATES_FILE = 'templates.json';
+const TEMPLATES_VERSION = '1.0.0';
+function getTemplatesPath() {
+    return path.join((0, workspace_cache_1.getCacheDir)(), TEMPLATES_FILE);
+}
+// -- Core operations --
+/** Load templates from disk. Returns empty structure if file doesn't exist. */
+async function loadTemplates() {
+    try {
+        const content = await fs.readFile(getTemplatesPath(), 'utf-8');
+        const data = JSON.parse(content);
+        if (!data.version || typeof data.templates !== 'object') {
+            return createEmpty();
+        }
+        return data;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return createEmpty();
+        return createEmpty();
+    }
+}
+/** Save templates to disk (atomic write via tmp + rename). */
+async function saveTemplates(data) {
+    await (0, workspace_cache_1.ensureCacheDir)();
+    const filePath = getTemplatesPath();
+    const tmpPath = `${filePath}.tmp`;
+    await fs.writeFile(tmpPath, JSON.stringify(data, null, 2), { encoding: 'utf-8', mode: 0o600 });
+    await fs.rename(tmpPath, filePath);
+}
+/** Get a single template by name. Returns null if not found. */
+async function getTemplate(name) {
+    var _a;
+    const data = await loadTemplates();
+    return (_a = data.templates[name.toLowerCase()]) !== null && _a !== void 0 ? _a : null;
+}
+/** Save or update a template. */
+async function setTemplate(name, template) {
+    const data = await loadTemplates();
+    data.templates[name.toLowerCase()] = template;
+    await saveTemplates(data);
+}
+/** Remove a template. Returns true if it existed. */
+async function removeTemplate(name) {
+    const data = await loadTemplates();
+    const key = name.toLowerCase();
+    if (!(key in data.templates))
+        return false;
+    delete data.templates[key];
+    await saveTemplates(data);
+    return true;
+}
+/** List all template names. */
+async function listTemplateNames() {
+    const data = await loadTemplates();
+    return Object.keys(data.templates);
+}
+// -- Helpers --
+function createEmpty() {
+    return { version: TEMPLATES_VERSION, templates: {} };
+}

package/dist/utils/terminal-banner.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Terminal banner and color utilities for consistent branding
+ * Used across postinstall script and init command
+ */
+/**
+ * ANSI color codes for cross-platform terminal compatibility
+ */
+export declare const colors: {
+    readonly reset: "\u001B[0m";
+    readonly bright: "\u001B[1m";
+    readonly dim: "\u001B[2m";
+    readonly green: "\u001B[32m";
+    readonly blue: "\u001B[34m";
+    readonly cyan: "\u001B[36m";
+    readonly gray: "\u001B[90m";
+    readonly yellow: "\u001B[33m";
+    readonly magenta: "\u001B[35m";
+};
+/**
+ * ASCII art banner for Notion CLI
+ * Displayed during install and setup
+ * Uses terminal's default color (black/white depending on theme)
+ */
+export declare const ASCII_BANNER = "\n\u2588\u2588\u2588\u2557   \u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2557   \u2588\u2588\u2557     \u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557     \u2588\u2588\u2557\n\u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2588\u2588\u2557\u255A\u2550\u2550\u2588\u2588\u2554\u2550\u2550\u255D\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2551    \u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2551     \u2588\u2588\u2551\n\u2588\u2588\u2554\u2588\u2588\u2557 \u2588\u2588\u2551\u2588\u2588\u2551   \u2588\u2588\u2551   \u2588\u2588\u2551   \u2588\u2588\u2551\u2588\u2588\u2551   \u2588\u2588\u2551\u2588\u2588\u2554\u2588\u2588\u2557 \u2588\u2588\u2551    \u2588\u2588\u2551     \u2588\u2588\u2551     \u2588\u2588\u2551\n\u2588\u2588\u2551\u255A\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2551   \u2588\u2588\u2551   \u2588\u2588\u2551   \u2588\u2588\u2551\u2588\u2588\u2551   \u2588\u2588\u2551\u2588\u2588\u2551\u255A\u2588\u2588\u2557\u2588\u2588\u2551    \u2588\u2588\u2551     \u2588\u2588\u2551     \u2588\u2588\u2551\n\u2588\u2588\u2551 \u255A\u2588\u2588\u2588\u2588\u2551\u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D   \u2588\u2588\u2551   \u2588\u2588\u2551\u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2551 \u255A\u2588\u2588\u2588\u2588\u2551    \u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551\n\u255A\u2550\u255D  \u255A\u2550\u2550\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u255D    \u255A\u2550\u255D   \u255A\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u255D  \u255A\u2550\u2550\u2550\u255D     \u255A\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u255D\n";

package/dist/utils/terminal-banner.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Terminal banner and color utilities for consistent branding
+ * Used across postinstall script and init command
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ASCII_BANNER = exports.colors = void 0;
+/**
+ * ANSI color codes for cross-platform terminal compatibility
+ */
+exports.colors = {
+    reset: '\x1b[0m',
+    bright: '\x1b[1m',
+    dim: '\x1b[2m',
+    green: '\x1b[32m',
+    blue: '\x1b[34m',
+    cyan: '\x1b[36m',
+    gray: '\x1b[90m',
+    yellow: '\x1b[33m',
+    magenta: '\x1b[35m',
+};
+/**
+ * ASCII art banner for Notion CLI
+ * Displayed during install and setup
+ * Uses terminal's default color (black/white depending on theme)
+ */
+exports.ASCII_BANNER = `
+███╗   ██╗ ██████╗ ████████╗██╗ ██████╗ ███╗   ██╗     ██████╗██╗     ██╗
+████╗  ██║██╔═══██╗╚══██╔══╝██║██╔═══██╗████╗  ██║    ██╔════╝██║     ██║
+██╔██╗ ██║██║   ██║   ██║   ██║██║   ██║██╔██╗ ██║    ██║     ██║     ██║
+██║╚██╗██║██║   ██║   ██║   ██║██║   ██║██║╚██╗██║    ██║     ██║     ██║
+██║ ╚████║╚██████╔╝   ██║   ██║╚██████╔╝██║ ╚████║    ╚██████╗███████╗██║
+╚═╝  ╚═══╝ ╚═════╝    ╚═╝   ╚═╝ ╚═════╝ ╚═╝  ╚═══╝     ╚═════╝╚══════╝╚═╝
+`;

package/dist/utils/token-validator.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Token Validation Utility
+ *
+ * Provides consistent token validation across all commands that interact with the Notion API.
+ * This ensures users get helpful, actionable error messages before attempting API calls.
+ */
+/**
+ * Masks a Notion token for safe display in logs and console output
+ *
+ * Shows only the prefix and last 3 characters to prevent token leakage
+ * in screen recordings, terminal sharing, or logs.
+ *
+ * @param token - The token to mask
+ * @returns Masked token string (e.g., "secret_***...***abc")
+ *
+ * @example
+ * ```typescript
+ * const token = "secret_1234567890abcdef"
+ * const masked = maskToken(token)
+ * // Returns: "secret_***...***def"
+ * ```
+ */
+export declare function maskToken(token: string): string;
+/**
+ * Validates that NOTION_TOKEN environment variable is set
+ *
+ * @throws {NotionCLIError} If token is not set, throws with helpful suggestions
+ *
+ * @example
+ * ```typescript
+ * import { validateNotionToken } from '../utils/token-validator'
+ *
+ * // In your command's run() method:
+ * async run() {
+ *   const { flags } = await this.parse(MyCommand)
+ *   validateNotionToken() // Throws if token not set
+ *
+ *   // Continue with API calls...
+ * }
+ * ```
+ */
+export declare function validateNotionToken(): void;

package/dist/utils/token-validator.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Token Validation Utility
+ *
+ * Provides consistent token validation across all commands that interact with the Notion API.
+ * This ensures users get helpful, actionable error messages before attempting API calls.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maskToken = maskToken;
+exports.validateNotionToken = validateNotionToken;
+const errors_1 = require("../errors");
+/**
+ * Masks a Notion token for safe display in logs and console output
+ *
+ * Shows only the prefix and last 3 characters to prevent token leakage
+ * in screen recordings, terminal sharing, or logs.
+ *
+ * @param token - The token to mask
+ * @returns Masked token string (e.g., "secret_***...***abc")
+ *
+ * @example
+ * ```typescript
+ * const token = "secret_1234567890abcdef"
+ * const masked = maskToken(token)
+ * // Returns: "secret_***...***def"
+ * ```
+ */
+function maskToken(token) {
+    if (!token)
+        return '';
+    if (token.length <= 10) {
+        // Token too short to safely mask, obscure completely
+        // Threshold: 10 chars ensures at least 3 chars are masked after prefix+suffix
+        return '***';
+    }
+    // Show prefix (secret_ or ntn_) and last 3 chars
+    // For unknown prefixes: use max 4 chars to ensure at least 4 chars are masked
+    const prefix = token.startsWith('secret_') ? 'secret_' :
+        token.startsWith('ntn_') ? 'ntn_' :
+            token.slice(0, Math.min(4, token.length - 7));
+    const suffix = token.slice(-3);
+    return `${prefix}***...***${suffix}`;
+}
+/**
+ * Validates that NOTION_TOKEN environment variable is set
+ *
+ * @throws {NotionCLIError} If token is not set, throws with helpful suggestions
+ *
+ * @example
+ * ```typescript
+ * import { validateNotionToken } from '../utils/token-validator'
+ *
+ * // In your command's run() method:
+ * async run() {
+ *   const { flags } = await this.parse(MyCommand)
+ *   validateNotionToken() // Throws if token not set
+ *
+ *   // Continue with API calls...
+ * }
+ * ```
+ */
+function validateNotionToken() {
+    if (!process.env.NOTION_TOKEN) {
+        throw errors_1.NotionCLIErrorFactory.tokenMissing();
+    }
+}

package/dist/utils/update-notifier.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Update notifier utility
+ * Checks for new versions of notion-cli and notifies users non-intrusively
+ *
+ * Runs asynchronously in background, doesn't block CLI execution
+ * Caches results for 1 day to avoid unnecessary npm registry checks
+ * Respects NO_UPDATE_NOTIFIER environment variable and CI environments
+ */
+/**
+ * Check for updates and notify user if a new version is available
+ *
+ * This runs asynchronously and won't block CLI execution.
+ * Checks are cached for 1 day by default.
+ *
+ * Set DEBUG=1 environment variable to see error messages if update check fails.
+ *
+ * @example
+ * ```bash
+ * # Silent mode (default)
+ * notion-cli --version
+ *
+ * # Debug mode
+ * DEBUG=1 notion-cli --version
+ * ```
+ */
+export declare function checkForUpdates(): void;

package/dist/utils/update-notifier.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Update notifier utility
+ * Checks for new versions of notion-cli and notifies users non-intrusively
+ *
+ * Runs asynchronously in background, doesn't block CLI execution
+ * Caches results for 1 day to avoid unnecessary npm registry checks
+ * Respects NO_UPDATE_NOTIFIER environment variable and CI environments
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkForUpdates = checkForUpdates;
+/**
+ * Check for updates and notify user if a new version is available
+ *
+ * This runs asynchronously and won't block CLI execution.
+ * Checks are cached for 1 day by default.
+ *
+ * Set DEBUG=1 environment variable to see error messages if update check fails.
+ *
+ * @example
+ * ```bash
+ * # Silent mode (default)
+ * notion-cli --version
+ *
+ * # Debug mode
+ * DEBUG=1 notion-cli --version
+ * ```
+ */
+function checkForUpdates() {
+    try {
+        // Load dependencies dynamically to avoid rootDir issues
+        const updateNotifier = require('update-notifier').default || require('update-notifier');
+        const packageJson = require('../../package.json');
+        // Initialize update notifier with package info
+        const notifier = updateNotifier({
+            pkg: packageJson,
+            updateCheckInterval: 1000 * 60 * 60 * 24, // Check once per day
+        });
+        // Show notification if update is available
+        // This displays a yellow-bordered box with update info
+        notifier.notify({
+            defer: true, // Show notification after command completes (non-intrusive)
+            isGlobal: true, // This is a global CLI tool
+        });
+    }
+    catch (error) {
+        // Silently fail - don't break CLI if update check fails
+        // This could happen if npm registry is unreachable, network issues, etc.
+        // Debug mode: Show error details for troubleshooting
+        if (process.env.DEBUG) {
+            console.error('Update check failed:', error instanceof Error ? error.message : error);
+        }
+    }
+}

package/dist/utils/workspace-cache.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Workspace Cache Utility
+ *
+ * Manages persistent caching of workspace databases for fast name-to-ID resolution.
+ * Cache is stored at ~/.notion-cli/databases.json
+ */
+import { GetDataSourceResponse, DataSourceObjectResponse } from '@notionhq/client/build/src/api-endpoints';
+export interface CachedDatabase {
+    id: string;
+    title: string;
+    titleNormalized: string;
+    aliases: string[];
+    url?: string;
+    lastEditedTime?: string;
+    properties?: Record<string, any>;
+}
+export interface WorkspaceCache {
+    version: string;
+    lastSync: string;
+    databases: CachedDatabase[];
+}
+/**
+ * Get the cache directory path
+ */
+export declare function getCacheDir(): string;
+/**
+ * Get the cache file path
+ */
+export declare function getCachePath(): Promise<string>;
+/**
+ * Ensure cache directory exists
+ */
+export declare function ensureCacheDir(): Promise<void>;
+/**
+ * Load cache from disk
+ * Returns null if cache doesn't exist or is corrupted
+ */
+export declare function loadCache(): Promise<WorkspaceCache | null>;
+/**
+ * Save cache to disk (atomic write)
+ */
+export declare function saveCache(data: WorkspaceCache): Promise<void>;
+/**
+ * Generate search aliases from a database title
+ *
+ * @example
+ * generateAliases('Tasks Database')
+ * // Returns: ['tasks database', 'tasks', 'task', 'tasks db', 'task db', 'td']
+ */
+export declare function generateAliases(title: string): string[];
+/**
+ * Build a cached database entry from a data source response
+ */
+export declare function buildCacheEntry(dataSource: GetDataSourceResponse | DataSourceObjectResponse): CachedDatabase;
+/**
+ * Create an empty cache
+ */
+export declare function createEmptyCache(): WorkspaceCache;