nconv-cli 1.0.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/config.ts","../src/core/exporter.ts","../src/utils/file.ts","../src/utils/logger.ts","../src/commands/md.ts","../src/commands/debug.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport { Command } from 'commander';\nimport { mdCommand } from './commands/md.js';\nimport { debugCommand } from './commands/debug.js';\n\nconst program = new Command();\n\nprogram\n  .name('nconv')\n  .description('CLI tool for converting Notion pages to blog-ready markdown')\n  .version('1.0.0');\n\nprogram\n  .command('md <url>')\n  .description('Convert a Notion page to markdown')\n  .option('-o, --output <dir>', 'Output directory', './output')\n  .option('-i, --image-dir <dir>', 'Image folder name (relative to output)', 'images')\n  .option('-f, --filename <name>', '출력 파일명 (확장자 제외 또는 포함)')\n  .option('-v, --verbose', 'Enable verbose logging', false)\n  .action(async (url: string, options) => {\n    await mdCommand(url, {\n      output: options.output,\n      imageDir: options.imageDir,\n      filename: options.filename,\n      verbose: options.verbose,\n    });\n  });\n\n// 개발 환경에서만 debug 명령어를 활성화\nif (process.env.NODE_ENV !== 'production') {\n  program\n    .command('debug <url>')\n    .description('Debug: Output raw markdown and image URLs')\n    .option('-o, --output <dir>', '출력 디렉토리', './output')\n    .option('-i, --image-dir <dir>', 'Image folder name', 'images')\n    .option('-v, --verbose', 'Enable verbose logging', false)\n    .action(async (url: string, options) => {\n      await debugCommand(url, {\n        output: options.output,\n        imageDir: options.imageDir,\n        filename: '',\n        verbose: options.verbose,\n      });\n    });\n}\n\nprogram.parse();\n","import { config as dotenvConfig } from 'dotenv';\nimport { existsSync } from 'fs';\nimport { resolve } from 'path';\n\n// 환경 변수 로드\ndotenvConfig();\n\nexport interface NotionConfig {\n  tokenV2: string;\n  fileToken: string;\n}\n\nexport interface ConverterOptions {\n  output: string;\n  imageDir: string;\n  filename?: string;\n  verbose: boolean;\n}\n\nexport interface FullConfig extends NotionConfig, ConverterOptions {}\n\n/**\n * Notion 인증 설정 가져오기\n */\nexport function getNotionConfig(): NotionConfig {\n  const tokenV2 = process.env.TOKEN_V2 || '';\n  const fileToken = process.env.FILE_TOKEN || '';\n\n  if (!tokenV2 || !fileToken) {\n    throw new Error(\n      'Notion 토큰이 설정되지 않았습니다.\\n' +\n      '.env 파일에 TOKEN_V2와 FILE_TOKEN을 설정해주세요.\\n' +\n      '자세한 내용은 .env.example을 참고하세요.'\n    );\n  }\n\n  return { tokenV2, fileToken };\n}\n\n/**\n * 전체 설정 생성\n */\nexport function createConfig(options: ConverterOptions): FullConfig {\n  const notionConfig = getNotionConfig();\n\n  // 출력 디렉토리 절대 경로로 변환\n  const outputDir = resolve(process.cwd(), options.output);\n\n  return {\n    ...notionConfig,\n    ...options,\n    output: outputDir,\n  };\n}\n\n/**\n * 디렉토리 존재 여부 확인\n */\nexport function ensureDirectoryExists(dir: string): boolean {\n  return existsSync(dir);\n}\n","import { NotionExporter } from 'notion-exporter';\nimport { promises as fs } from 'fs';\nimport path from 'path';\nimport type { NotionConfig } from '../config.js';\n\nexport interface ExportResult {\n  markdown: string;\n  imageFiles: Array<{ filename: string; sourcePath: string }>;\n}\n\n/**\n * Notion 페이지를 마크다운으로 내보내기\n */\nexport class NotionMarkdownExporter {\n  private exporter: NotionExporter;\n\n  constructor(config: NotionConfig) {\n    this.exporter = new NotionExporter(config.tokenV2, config.fileToken);\n  }\n\n  /**\n   * Notion URL에서 마크다운과 이미지 파일 가져오기\n   */\n  async exportWithImages(notionUrl: string, tempDir: string): Promise<ExportResult> {\n    try {\n      // 임시 디렉토리 생성\n      await fs.mkdir(tempDir, { recursive: true });\n\n      // getMdFiles로 마크다운과 이미지를 함께 다운로드\n      await this.exporter.getMdFiles(notionUrl, tempDir);\n\n      // 다운로드된 파일 목록 가져오기\n      const files = await fs.readdir(tempDir, { withFileTypes: true });\n\n      // 마크다운 파일 찾기\n      const mdFile = files.find(f => f.isFile() && f.name.endsWith('.md'));\n      if (!mdFile) {\n        throw new Error('Markdown file not found.');\n      }\n\n      // 마크다운 내용 읽기\n      const mdPath = path.join(tempDir, mdFile.name);\n      const markdown = await fs.readFile(mdPath, 'utf-8');\n\n      // 이미지 파일 목록 (마크다운이 아닌 파일들)\n      const imageFiles = files\n        .filter(f => f.isFile() && !f.name.endsWith('.md'))\n        .map(f => ({\n          filename: f.name,\n          sourcePath: path.join(tempDir, f.name),\n        }));\n\n      // 디렉토리 내 폴더도 확인 (Notion이 폴더 구조로 저장할 수 있음)\n      const dirs = files.filter(f => f.isDirectory());\n      for (const dir of dirs) {\n        const subFiles = await fs.readdir(path.join(tempDir, dir.name), { withFileTypes: true });\n        for (const subFile of subFiles) {\n          if (subFile.isFile() && !subFile.name.endsWith('.md')) {\n            imageFiles.push({\n              filename: path.join(dir.name, subFile.name),\n              sourcePath: path.join(tempDir, dir.name, subFile.name),\n            });\n          }\n        }\n      }\n\n      return { markdown, imageFiles };\n    } catch (error) {\n      if (error instanceof Error) {\n        throw new Error(`Failed to fetch Notion page: ${error.message}`);\n      }\n      throw new Error('Failed to fetch Notion page.');\n    }\n  }\n}\n","import { promises as fs } from 'fs';\nimport path from 'path';\nimport slugify from 'slugify';\nimport { v4 as uuidv4 } from 'uuid';\n\n/**\n * Notion URL에서 페이지 제목 추출 (간단한 버전)\n */\nexport function extractTitleFromUrl(notionUrl: string): string | null {\n  try {\n    const url = new URL(notionUrl);\n    const pathname = url.pathname;\n\n    // /Page-Title-abc123 형식에서 제목 부분 추출\n    const match = pathname.match(/\\/([^/]+)-[a-f0-9]{32}$/i);\n    if (match) {\n      const title = match[1].replace(/-/g, ' ');\n      return title;\n    }\n\n    return null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * 안전한 파일명 생성\n */\nexport function generateSafeFilename(title: string | null, extension: string = 'md'): string {\n  if (title) {\n    const slug = slugify(title, {\n      lower: true,\n      strict: true,\n      locale: 'ko',\n    });\n\n    if (slug.length > 0) {\n      return extension ? `${slug}.${extension}` : slug;\n    }\n  }\n\n  // 제목이 없거나 slugify 실패 시 UUID 사용\n  const hash = uuidv4().slice(0, 8);\n  return extension ? `notion-export-${hash}.${extension}` : `notion-export-${hash}`;\n}\n\n/**\n * 마크다운 파일 저장\n */\nexport async function saveMarkdownFile(\n  outputDir: string,\n  filename: string,\n  content: string\n): Promise<string> {\n  await fs.mkdir(outputDir, { recursive: true });\n\n  const filePath = path.join(outputDir, filename);\n  await fs.writeFile(filePath, content, 'utf-8');\n\n  return filePath;\n}\n\n/**\n * 파일 경로를 상대 경로로 변환\n */\nexport function toRelativePath(from: string, to: string): string {\n  return path.relative(from, to);\n}\n","import chalk from 'chalk';\nimport ora, { Ora } from 'ora';\n\n/**\n * 성공 메시지 출력\n */\nexport function success(message: string): void {\n  console.log(chalk.green('✓'), message);\n}\n\n/**\n * 에러 메시지 출력\n */\nexport function error(message: string): void {\n  console.error(chalk.red('✗'), message);\n}\n\n/**\n * 정보 메시지 출력\n */\nexport function info(message: string): void {\n  console.log(chalk.blue('ℹ'), message);\n}\n\n/**\n * 경고 메시지 출력\n */\nexport function warn(message: string): void {\n  console.log(chalk.yellow('⚠'), message);\n}\n\n/**\n * 스피너 생성\n */\nexport function spinner(text: string): Ora {\n  return ora(text).start();\n}\n","import { ConverterOptions, createConfig } from '../config.js';\nimport { NotionMarkdownExporter } from '../core/exporter.js';\nimport { generateSafeFilename, extractTitleFromUrl, saveMarkdownFile } from '../utils/file.js';\nimport * as logger from '../utils/logger.js';\nimport path from 'path';\nimport { promises as fs } from 'fs';\nimport os from 'os';\n\n/**\n * md 명령어 핸들러\n */\nexport async function mdCommand(notionUrl: string, options: ConverterOptions) {\n  const tempDir = path.join(os.tmpdir(), `nconv-cli-${Date.now()}`);\n\n  try {\n    // 설정 생성\n    const config = createConfig(options);\n\n    if (config.verbose) {\n      logger.info('Configuration loaded successfully');\n      console.log(`  Output directory: ${config.output}\\n`);\n    }\n\n    // 1. Notion에서 마크다운과 이미지 가져오기\n    const spinner = logger.spinner('Fetching Notion page...');\n\n    const exporter = new NotionMarkdownExporter({\n      tokenV2: config.tokenV2,\n      fileToken: config.fileToken,\n    });\n\n    let result;\n    try {\n      result = await exporter.exportWithImages(notionUrl, tempDir);\n      spinner.succeed(`Notion page fetched (${result.imageFiles.length} images)`);\n    } catch (error) {\n      spinner.fail('Failed to fetch Notion page');\n      throw error;\n    }\n\n    // 2. 파일명/폴더명 생성\n    let baseFilename: string;\n    if (config.filename) {\n      baseFilename = config.filename.replace(/\\.md$/, '');\n    } else {\n      const title = extractTitleFromUrl(notionUrl);\n      baseFilename = generateSafeFilename(title, ''); // 확장자 없이 생성\n    }\n\n    // 3. 제목별 폴더 생성 (output/제목/)\n    const pageDir = path.join(config.output, baseFilename);\n    await fs.mkdir(pageDir, { recursive: true });\n\n    if (config.verbose) {\n      console.log(`📁 출력 폴더: ${path.relative(process.cwd(), pageDir)}\\n`);\n    }\n\n    // 4. 이미지 폴더 생성 및 이미지 파일 이동\n    const imageOutputDir = path.join(pageDir, config.imageDir);\n    await fs.mkdir(imageOutputDir, { recursive: true });\n\n    if (config.verbose && result.imageFiles.length > 0) {\n      console.log(`Processing image files...\\n`);\n    }\n\n    let processedMarkdown = result.markdown;\n    for (const imageFile of result.imageFiles) {\n      try {\n        // 파일명에서 공백을 하이픈으로 변경 (마크다운 호환성)\n        const originalFileName = path.basename(imageFile.filename);\n        const safeFileName = originalFileName.replace(/\\s+/g, '-');\n\n        // 이미지 파일 복사\n        const targetPath = path.join(imageOutputDir, safeFileName);\n        await fs.copyFile(imageFile.sourcePath, targetPath);\n\n        if (config.verbose) {\n          console.log(`✓ ${safeFileName}`);\n        }\n\n        // 마크다운 내 경로를 상대경로로 변경\n        const originalPath = imageFile.filename;\n        const relativePath = `./${config.imageDir}/${safeFileName}`;\n\n        // Notion이 URL 인코딩하는 방식: 각 경로 부분을 개별적으로 인코딩\n        const pathParts = originalPath.split('/');\n        const encodedPath = pathParts.map(part => encodeURIComponent(part)).join('/');\n\n        // 정규식 특수문자 이스케이프 함수\n        const escapeRegex = (str: string) => str.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n\n        // 모든 가능한 형태의 경로를 교체\n        processedMarkdown = processedMarkdown\n          .replace(new RegExp(`\\\\(${escapeRegex(originalPath)}\\\\)`, 'g'), `(${relativePath})`)\n          .replace(new RegExp(`\\\\(${escapeRegex(encodedPath)}\\\\)`, 'g'), `(${relativePath})`);\n\n      } catch (error) {\n        if (config.verbose) {\n          const errorMsg = error instanceof Error ? error.message : '알 수 없는 오류';\n          console.error(`✗ ${imageFile.filename}: ${errorMsg}`);\n        }\n      }\n    }\n\n    // 5. 마크다운 파일 저장 (제목 폴더 안에)\n    const filename = `${baseFilename}.md`;\n    const filePath = await saveMarkdownFile(pageDir, filename, processedMarkdown);\n\n    // 6. 결과 출력\n    console.log('');\n    logger.success('Conversion complete!');\n    console.log('');\n    console.log(`📁 Folder: ${path.relative(process.cwd(), pageDir)}`);\n    console.log(`📄 Markdown: ${filename}`);\n\n    if (result.imageFiles.length > 0) {\n      console.log(`🖼️  Images: ${config.imageDir}/ (${result.imageFiles.length} files)`);\n    }\n\n    console.log('');\n\n  } catch (error) {\n    if (error instanceof Error) {\n      logger.error(error.message);\n    } else {\n      logger.error('An unknown error occurred.');\n    }\n    process.exit(1);\n  } finally {\n    // 임시 디렉토리 정리\n    try {\n      await fs.rm(tempDir, { recursive: true, force: true });\n    } catch {\n      // 무시\n    }\n  }\n}\n","import { ConverterOptions, createConfig } from '../config.js';\nimport { NotionMarkdownExporter } from '../core/exporter.js';\nimport * as fs from 'fs/promises';\nimport * as os from 'os';\nimport * as path from 'path';\n\n/**\n * Debugging command - output raw markdown\n */\nexport async function debugCommand(notionUrl: string, options: ConverterOptions) {\n  let tempDir: string | undefined;\n  try {\n    const config = createConfig(options);\n\n    const exporter = new NotionMarkdownExporter({\n      tokenV2: config.tokenV2,\n      fileToken: config.fileToken,\n    });\n\n    tempDir = path.join(os.tmpdir(), `notion-debug-${Date.now()}`); // Create temporary directory\n\n    console.log('Fetching Notion page...\\n');\n    const { markdown, imageFiles } = await exporter.exportWithImages(notionUrl, tempDir);\n\n    console.log('=== Raw Markdown ===\\n');\n    console.log(markdown.slice(0, 3000));\n    console.log('\\n... (truncated) ...\\n');\n\n    console.log(`\\n=== Found Images (${imageFiles.length}) ===\\n`);\n    imageFiles.forEach((file, i) => {\n      console.log(`${i + 1}. ${file.filename} (원본 경로: ${file.sourcePath})`);\n    });\n\n  } catch (error) {\n    console.error('Error:', error);\n  } finally {\n    if (tempDir) {\n      // Clean up temporary directory\n      await fs.rm(tempDir, { recursive: true, force: true }).catch(err => {\n        console.warn(`Error cleaning up temporary directory: ${err.message}`);\n      });\n    }\n  }\n}"],"mappings":";;;AAEA,SAAS,eAAe;;;ACFxB,SAAS,UAAU,oBAAoB;AAEvC,SAAS,eAAe;AAGxB,aAAa;AAmBN,SAAS,kBAAgC;AAC9C,QAAM,UAAU,QAAQ,IAAI,YAAY;AACxC,QAAM,YAAY,QAAQ,IAAI,cAAc;AAE5C,MAAI,CAAC,WAAW,CAAC,WAAW;AAC1B,UAAM,IAAI;AAAA,MACR;AAAA,IAGF;AAAA,EACF;AAEA,SAAO,EAAE,SAAS,UAAU;AAC9B;AAKO,SAAS,aAAa,SAAuC;AAClE,QAAM,eAAe,gBAAgB;AAGrC,QAAM,YAAY,QAAQ,QAAQ,IAAI,GAAG,QAAQ,MAAM;AAEvD,SAAO;AAAA,IACL,GAAG;AAAA,IACH,GAAG;AAAA,IACH,QAAQ;AAAA,EACV;AACF;;;ACrDA,SAAS,sBAAsB;AAC/B,SAAS,YAAY,UAAU;AAC/B,OAAO,UAAU;AAWV,IAAM,yBAAN,MAA6B;AAAA,EAGlC,YAAY,QAAsB;AAChC,SAAK,WAAW,IAAI,eAAe,OAAO,SAAS,OAAO,SAAS;AAAA,EACrE;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,iBAAiB,WAAmB,SAAwC;AAChF,QAAI;AAEF,YAAM,GAAG,MAAM,SAAS,EAAE,WAAW,KAAK,CAAC;AAG3C,YAAM,KAAK,SAAS,WAAW,WAAW,OAAO;AAGjD,YAAM,QAAQ,MAAM,GAAG,QAAQ,SAAS,EAAE,eAAe,KAAK,CAAC;AAG/D,YAAM,SAAS,MAAM,KAAK,OAAK,EAAE,OAAO,KAAK,EAAE,KAAK,SAAS,KAAK,CAAC;AACnE,UAAI,CAAC,QAAQ;AACX,cAAM,IAAI,MAAM,0BAA0B;AAAA,MAC5C;AAGA,YAAM,SAAS,KAAK,KAAK,SAAS,OAAO,IAAI;AAC7C,YAAM,WAAW,MAAM,GAAG,SAAS,QAAQ,OAAO;AAGlD,YAAM,aAAa,MAChB,OAAO,OAAK,EAAE,OAAO,KAAK,CAAC,EAAE,KAAK,SAAS,KAAK,CAAC,EACjD,IAAI,QAAM;AAAA,QACT,UAAU,EAAE;AAAA,QACZ,YAAY,KAAK,KAAK,SAAS,EAAE,IAAI;AAAA,MACvC,EAAE;AAGJ,YAAM,OAAO,MAAM,OAAO,OAAK,EAAE,YAAY,CAAC;AAC9C,iBAAW,OAAO,MAAM;AACtB,cAAM,WAAW,MAAM,GAAG,QAAQ,KAAK,KAAK,SAAS,IAAI,IAAI,GAAG,EAAE,eAAe,KAAK,CAAC;AACvF,mBAAW,WAAW,UAAU;AAC9B,cAAI,QAAQ,OAAO,KAAK,CAAC,QAAQ,KAAK,SAAS,KAAK,GAAG;AACrD,uBAAW,KAAK;AAAA,cACd,UAAU,KAAK,KAAK,IAAI,MAAM,QAAQ,IAAI;AAAA,cAC1C,YAAY,KAAK,KAAK,SAAS,IAAI,MAAM,QAAQ,IAAI;AAAA,YACvD,CAAC;AAAA,UACH;AAAA,QACF;AAAA,MACF;AAEA,aAAO,EAAE,UAAU,WAAW;AAAA,IAChC,SAASA,QAAO;AACd,UAAIA,kBAAiB,OAAO;AAC1B,cAAM,IAAI,MAAM,gCAAgCA,OAAM,OAAO,EAAE;AAAA,MACjE;AACA,YAAM,IAAI,MAAM,8BAA8B;AAAA,IAChD;AAAA,EACF;AACF;;;AC1EA,SAAS,YAAYC,WAAU;AAC/B,OAAOC,WAAU;AACjB,OAAO,aAAa;AACpB,SAAS,MAAM,cAAc;AAKtB,SAAS,oBAAoB,WAAkC;AACpE,MAAI;AACF,UAAM,MAAM,IAAI,IAAI,SAAS;AAC7B,UAAM,WAAW,IAAI;AAGrB,UAAM,QAAQ,SAAS,MAAM,0BAA0B;AACvD,QAAI,OAAO;AACT,YAAM,QAAQ,MAAM,CAAC,EAAE,QAAQ,MAAM,GAAG;AACxC,aAAO;AAAA,IACT;AAEA,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAKO,SAAS,qBAAqB,OAAsB,YAAoB,MAAc;AAC3F,MAAI,OAAO;AACT,UAAM,OAAO,QAAQ,OAAO;AAAA,MAC1B,OAAO;AAAA,MACP,QAAQ;AAAA,MACR,QAAQ;AAAA,IACV,CAAC;AAED,QAAI,KAAK,SAAS,GAAG;AACnB,aAAO,YAAY,GAAG,IAAI,IAAI,SAAS,KAAK;AAAA,IAC9C;AAAA,EACF;AAGA,QAAM,OAAO,OAAO,EAAE,MAAM,GAAG,CAAC;AAChC,SAAO,YAAY,iBAAiB,IAAI,IAAI,SAAS,KAAK,iBAAiB,IAAI;AACjF;AAKA,eAAsB,iBACpB,WACA,UACA,SACiB;AACjB,QAAMD,IAAG,MAAM,WAAW,EAAE,WAAW,KAAK,CAAC;AAE7C,QAAM,WAAWC,MAAK,KAAK,WAAW,QAAQ;AAC9C,QAAMD,IAAG,UAAU,UAAU,SAAS,OAAO;AAE7C,SAAO;AACT;;;AC7DA,OAAO,WAAW;AAClB,OAAO,SAAkB;AAKlB,SAAS,QAAQ,SAAuB;AAC7C,UAAQ,IAAI,MAAM,MAAM,QAAG,GAAG,OAAO;AACvC;AAKO,SAAS,MAAM,SAAuB;AAC3C,UAAQ,MAAM,MAAM,IAAI,QAAG,GAAG,OAAO;AACvC;AAKO,SAAS,KAAK,SAAuB;AAC1C,UAAQ,IAAI,MAAM,KAAK,QAAG,GAAG,OAAO;AACtC;AAYO,SAAS,QAAQ,MAAmB;AACzC,SAAO,IAAI,IAAI,EAAE,MAAM;AACzB;;;AChCA,OAAOE,WAAU;AACjB,SAAS,YAAYC,WAAU;AAC/B,OAAO,QAAQ;AAKf,eAAsB,UAAU,WAAmB,SAA2B;AAC5E,QAAM,UAAUD,MAAK,KAAK,GAAG,OAAO,GAAG,aAAa,KAAK,IAAI,CAAC,EAAE;AAEhE,MAAI;AAEF,UAAM,SAAS,aAAa,OAAO;AAEnC,QAAI,OAAO,SAAS;AAClB,MAAO,KAAK,mCAAmC;AAC/C,cAAQ,IAAI,uBAAuB,OAAO,MAAM;AAAA,CAAI;AAAA,IACtD;AAGA,UAAME,WAAiB,QAAQ,yBAAyB;AAExD,UAAM,WAAW,IAAI,uBAAuB;AAAA,MAC1C,SAAS,OAAO;AAAA,MAChB,WAAW,OAAO;AAAA,IACpB,CAAC;AAED,QAAI;AACJ,QAAI;AACF,eAAS,MAAM,SAAS,iBAAiB,WAAW,OAAO;AAC3D,MAAAA,SAAQ,QAAQ,wBAAwB,OAAO,WAAW,MAAM,UAAU;AAAA,IAC5E,SAASC,QAAO;AACd,MAAAD,SAAQ,KAAK,6BAA6B;AAC1C,YAAMC;AAAA,IACR;AAGA,QAAI;AACJ,QAAI,OAAO,UAAU;AACnB,qBAAe,OAAO,SAAS,QAAQ,SAAS,EAAE;AAAA,IACpD,OAAO;AACL,YAAM,QAAQ,oBAAoB,SAAS;AAC3C,qBAAe,qBAAqB,OAAO,EAAE;AAAA,IAC/C;AAGA,UAAM,UAAUH,MAAK,KAAK,OAAO,QAAQ,YAAY;AACrD,UAAMC,IAAG,MAAM,SAAS,EAAE,WAAW,KAAK,CAAC;AAE3C,QAAI,OAAO,SAAS;AAClB,cAAQ,IAAI,wCAAaD,MAAK,SAAS,QAAQ,IAAI,GAAG,OAAO,CAAC;AAAA,CAAI;AAAA,IACpE;AAGA,UAAM,iBAAiBA,MAAK,KAAK,SAAS,OAAO,QAAQ;AACzD,UAAMC,IAAG,MAAM,gBAAgB,EAAE,WAAW,KAAK,CAAC;AAElD,QAAI,OAAO,WAAW,OAAO,WAAW,SAAS,GAAG;AAClD,cAAQ,IAAI;AAAA,CAA6B;AAAA,IAC3C;AAEA,QAAI,oBAAoB,OAAO;AAC/B,eAAW,aAAa,OAAO,YAAY;AACzC,UAAI;AAEF,cAAM,mBAAmBD,MAAK,SAAS,UAAU,QAAQ;AACzD,cAAM,eAAe,iBAAiB,QAAQ,QAAQ,GAAG;AAGzD,cAAM,aAAaA,MAAK,KAAK,gBAAgB,YAAY;AACzD,cAAMC,IAAG,SAAS,UAAU,YAAY,UAAU;AAElD,YAAI,OAAO,SAAS;AAClB,kBAAQ,IAAI,UAAK,YAAY,EAAE;AAAA,QACjC;AAGA,cAAM,eAAe,UAAU;AAC/B,cAAM,eAAe,KAAK,OAAO,QAAQ,IAAI,YAAY;AAGzD,cAAM,YAAY,aAAa,MAAM,GAAG;AACxC,cAAM,cAAc,UAAU,IAAI,UAAQ,mBAAmB,IAAI,CAAC,EAAE,KAAK,GAAG;AAG5E,cAAM,cAAc,CAAC,QAAgB,IAAI,QAAQ,uBAAuB,MAAM;AAG9E,4BAAoB,kBACjB,QAAQ,IAAI,OAAO,MAAM,YAAY,YAAY,CAAC,OAAO,GAAG,GAAG,IAAI,YAAY,GAAG,EAClF,QAAQ,IAAI,OAAO,MAAM,YAAY,WAAW,CAAC,OAAO,GAAG,GAAG,IAAI,YAAY,GAAG;AAAA,MAEtF,SAASE,QAAO;AACd,YAAI,OAAO,SAAS;AAClB,gBAAM,WAAWA,kBAAiB,QAAQA,OAAM,UAAU;AAC1D,kBAAQ,MAAM,UAAK,UAAU,QAAQ,KAAK,QAAQ,EAAE;AAAA,QACtD;AAAA,MACF;AAAA,IACF;AAGA,UAAM,WAAW,GAAG,YAAY;AAChC,UAAM,WAAW,MAAM,iBAAiB,SAAS,UAAU,iBAAiB;AAG5E,YAAQ,IAAI,EAAE;AACd,IAAO,QAAQ,sBAAsB;AACrC,YAAQ,IAAI,EAAE;AACd,YAAQ,IAAI,qBAAcH,MAAK,SAAS,QAAQ,IAAI,GAAG,OAAO,CAAC,EAAE;AACjE,YAAQ,IAAI,uBAAgB,QAAQ,EAAE;AAEtC,QAAI,OAAO,WAAW,SAAS,GAAG;AAChC,cAAQ,IAAI,4BAAgB,OAAO,QAAQ,MAAM,OAAO,WAAW,MAAM,SAAS;AAAA,IACpF;AAEA,YAAQ,IAAI,EAAE;AAAA,EAEhB,SAASG,QAAO;AACd,QAAIA,kBAAiB,OAAO;AAC1B,MAAO,MAAMA,OAAM,OAAO;AAAA,IAC5B,OAAO;AACL,MAAO,MAAM,4BAA4B;AAAA,IAC3C;AACA,YAAQ,KAAK,CAAC;AAAA,EAChB,UAAE;AAEA,QAAI;AACF,YAAMF,IAAG,GAAG,SAAS,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC;AAAA,IACvD,QAAQ;AAAA,IAER;AAAA,EACF;AACF;;;ACtIA,YAAYG,SAAQ;AACpB,YAAYC,SAAQ;AACpB,YAAYC,WAAU;AAKtB,eAAsB,aAAa,WAAmB,SAA2B;AAC/E,MAAI;AACJ,MAAI;AACF,UAAM,SAAS,aAAa,OAAO;AAEnC,UAAM,WAAW,IAAI,uBAAuB;AAAA,MAC1C,SAAS,OAAO;AAAA,MAChB,WAAW,OAAO;AAAA,IACpB,CAAC;AAED,cAAe,WAAQ,WAAO,GAAG,gBAAgB,KAAK,IAAI,CAAC,EAAE;AAE7D,YAAQ,IAAI,2BAA2B;AACvC,UAAM,EAAE,UAAU,WAAW,IAAI,MAAM,SAAS,iBAAiB,WAAW,OAAO;AAEnF,YAAQ,IAAI,wBAAwB;AACpC,YAAQ,IAAI,SAAS,MAAM,GAAG,GAAI,CAAC;AACnC,YAAQ,IAAI,yBAAyB;AAErC,YAAQ,IAAI;AAAA,oBAAuB,WAAW,MAAM;AAAA,CAAS;AAC7D,eAAW,QAAQ,CAAC,MAAM,MAAM;AAC9B,cAAQ,IAAI,GAAG,IAAI,CAAC,KAAK,KAAK,QAAQ,gCAAY,KAAK,UAAU,GAAG;AAAA,IACtE,CAAC;AAAA,EAEH,SAASC,QAAO;AACd,YAAQ,MAAM,UAAUA,MAAK;AAAA,EAC/B,UAAE;AACA,QAAI,SAAS;AAEX,YAAS,OAAG,SAAS,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC,EAAE,MAAM,SAAO;AAClE,gBAAQ,KAAK,0CAA0C,IAAI,OAAO,EAAE;AAAA,MACtE,CAAC;AAAA,IACH;AAAA,EACF;AACF;;;ANrCA,IAAM,UAAU,IAAI,QAAQ;AAE5B,QACG,KAAK,OAAO,EACZ,YAAY,6DAA6D,EACzE,QAAQ,OAAO;AAElB,QACG,QAAQ,UAAU,EAClB,YAAY,mCAAmC,EAC/C,OAAO,sBAAsB,oBAAoB,UAAU,EAC3D,OAAO,yBAAyB,0CAA0C,QAAQ,EAClF,OAAO,yBAAyB,6FAAuB,EACvD,OAAO,iBAAiB,0BAA0B,KAAK,EACvD,OAAO,OAAO,KAAa,YAAY;AACtC,QAAM,UAAU,KAAK;AAAA,IACnB,QAAQ,QAAQ;AAAA,IAChB,UAAU,QAAQ;AAAA,IAClB,UAAU,QAAQ;AAAA,IAClB,SAAS,QAAQ;AAAA,EACnB,CAAC;AACH,CAAC;AAGH,IAAI,QAAQ,IAAI,aAAa,cAAc;AACzC,UACG,QAAQ,aAAa,EACrB,YAAY,2CAA2C,EACvD,OAAO,sBAAsB,yCAAW,UAAU,EAClD,OAAO,yBAAyB,qBAAqB,QAAQ,EAC7D,OAAO,iBAAiB,0BAA0B,KAAK,EACvD,OAAO,OAAO,KAAa,YAAY;AACtC,UAAM,aAAa,KAAK;AAAA,MACtB,QAAQ,QAAQ;AAAA,MAChB,UAAU,QAAQ;AAAA,MAClB,UAAU;AAAA,MACV,SAAS,QAAQ;AAAA,IACnB,CAAC;AAAA,EACH,CAAC;AACL;AAEA,QAAQ,MAAM;","names":["error","fs","path","path","fs","spinner","error","fs","os","path","error"]}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "nconv-cli",
+  "version": "1.0.0",
+  "description": "A CLI tool that converts Notion pages into blog-ready Markdown (with automatic image extraction and path normalization)",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "nconv": "./bin/nconv.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "start": "node dist/index.js"
+  },
+  "keywords": ["notion", "markdown", "blog", "converter", "cli"],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "notion-exporter": "^0.8.1",
+    "commander": "^12.0.0",
+    "axios": "^1.13.2",
+    "dotenv": "^17.2.3",
+    "chalk": "^5.4.0",
+    "ora": "^8.0.0",
+    "slugify": "^1.6.6",
+    "uuid": "^13.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "@types/uuid": "^10.0.0",
+    "typescript": "^5.9.3",
+    "tsup": "^8.0.0"
+  }
+}

package/src/commands/debug.ts

@@ -0,0 +1,44 @@
+import { ConverterOptions, createConfig } from '../config.js';
+import { NotionMarkdownExporter } from '../core/exporter.js';
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+
+/**
+ * Debugging command - output raw markdown
+ */
+export async function debugCommand(notionUrl: string, options: ConverterOptions) {
+  let tempDir: string | undefined;
+  try {
+    const config = createConfig(options);
+
+    const exporter = new NotionMarkdownExporter({
+      tokenV2: config.tokenV2,
+      fileToken: config.fileToken,
+    });
+
+    tempDir = path.join(os.tmpdir(), `notion-debug-${Date.now()}`); // Create temporary directory
+
+    console.log('Fetching Notion page...\n');
+    const { markdown, imageFiles } = await exporter.exportWithImages(notionUrl, tempDir);
+
+    console.log('=== Raw Markdown ===\n');
+    console.log(markdown.slice(0, 3000));
+    console.log('\n... (truncated) ...\n');
+
+    console.log(`\n=== Found Images (${imageFiles.length}) ===\n`);
+    imageFiles.forEach((file, i) => {
+      console.log(`${i + 1}. ${file.filename} (원본 경로: ${file.sourcePath})`);
+    });
+
+  } catch (error) {
+    console.error('Error:', error);
+  } finally {
+    if (tempDir) {
+      // Clean up temporary directory
+      await fs.rm(tempDir, { recursive: true, force: true }).catch(err => {
+        console.warn(`Error cleaning up temporary directory: ${err.message}`);
+      });
+    }
+  }
+}

package/src/commands/md.ts

@@ -0,0 +1,137 @@
+import { ConverterOptions, createConfig } from '../config.js';
+import { NotionMarkdownExporter } from '../core/exporter.js';
+import { generateSafeFilename, extractTitleFromUrl, saveMarkdownFile } from '../utils/file.js';
+import * as logger from '../utils/logger.js';
+import path from 'path';
+import { promises as fs } from 'fs';
+import os from 'os';
+
+/**
+ * md 명령어 핸들러
+ */
+export async function mdCommand(notionUrl: string, options: ConverterOptions) {
+  const tempDir = path.join(os.tmpdir(), `nconv-cli-${Date.now()}`);
+
+  try {
+    // 설정 생성
+    const config = createConfig(options);
+
+    if (config.verbose) {
+      logger.info('Configuration loaded successfully');
+      console.log(`  Output directory: ${config.output}\n`);
+    }
+
+    // 1. Notion에서 마크다운과 이미지 가져오기
+    const spinner = logger.spinner('Fetching Notion page...');
+
+    const exporter = new NotionMarkdownExporter({
+      tokenV2: config.tokenV2,
+      fileToken: config.fileToken,
+    });
+
+    let result;
+    try {
+      result = await exporter.exportWithImages(notionUrl, tempDir);
+      spinner.succeed(`Notion page fetched (${result.imageFiles.length} images)`);
+    } catch (error) {
+      spinner.fail('Failed to fetch Notion page');
+      throw error;
+    }
+
+    // 2. 파일명/폴더명 생성
+    let baseFilename: string;
+    if (config.filename) {
+      baseFilename = config.filename.replace(/\.md$/, '');
+    } else {
+      const title = extractTitleFromUrl(notionUrl);
+      baseFilename = generateSafeFilename(title, ''); // 확장자 없이 생성
+    }
+
+    // 3. 제목별 폴더 생성 (output/제목/)
+    const pageDir = path.join(config.output, baseFilename);
+    await fs.mkdir(pageDir, { recursive: true });
+
+    if (config.verbose) {
+      console.log(`📁 출력 폴더: ${path.relative(process.cwd(), pageDir)}\n`);
+    }
+
+    // 4. 이미지 폴더 생성 및 이미지 파일 이동
+    const imageOutputDir = path.join(pageDir, config.imageDir);
+    await fs.mkdir(imageOutputDir, { recursive: true });
+
+    if (config.verbose && result.imageFiles.length > 0) {
+      console.log(`Processing image files...\n`);
+    }
+
+    let processedMarkdown = result.markdown;
+    for (const imageFile of result.imageFiles) {
+      try {
+        // 파일명에서 공백을 하이픈으로 변경 (마크다운 호환성)
+        const originalFileName = path.basename(imageFile.filename);
+        const safeFileName = originalFileName.replace(/\s+/g, '-');
+
+        // 이미지 파일 복사
+        const targetPath = path.join(imageOutputDir, safeFileName);
+        await fs.copyFile(imageFile.sourcePath, targetPath);
+
+        if (config.verbose) {
+          console.log(`✓ ${safeFileName}`);
+        }
+
+        // 마크다운 내 경로를 상대경로로 변경
+        const originalPath = imageFile.filename;
+        const relativePath = `./${config.imageDir}/${safeFileName}`;
+
+        // Notion이 URL 인코딩하는 방식: 각 경로 부분을 개별적으로 인코딩
+        const pathParts = originalPath.split('/');
+        const encodedPath = pathParts.map(part => encodeURIComponent(part)).join('/');
+
+        // 정규식 특수문자 이스케이프 함수
+        const escapeRegex = (str: string) => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+        // 모든 가능한 형태의 경로를 교체
+        processedMarkdown = processedMarkdown
+          .replace(new RegExp(`\\(${escapeRegex(originalPath)}\\)`, 'g'), `(${relativePath})`)
+          .replace(new RegExp(`\\(${escapeRegex(encodedPath)}\\)`, 'g'), `(${relativePath})`);
+
+      } catch (error) {
+        if (config.verbose) {
+          const errorMsg = error instanceof Error ? error.message : '알 수 없는 오류';
+          console.error(`✗ ${imageFile.filename}: ${errorMsg}`);
+        }
+      }
+    }
+
+    // 5. 마크다운 파일 저장 (제목 폴더 안에)
+    const filename = `${baseFilename}.md`;
+    const filePath = await saveMarkdownFile(pageDir, filename, processedMarkdown);
+
+    // 6. 결과 출력
+    console.log('');
+    logger.success('Conversion complete!');
+    console.log('');
+    console.log(`📁 Folder: ${path.relative(process.cwd(), pageDir)}`);
+    console.log(`📄 Markdown: ${filename}`);
+
+    if (result.imageFiles.length > 0) {
+      console.log(`🖼️  Images: ${config.imageDir}/ (${result.imageFiles.length} files)`);
+    }
+
+    console.log('');
+
+  } catch (error) {
+    if (error instanceof Error) {
+      logger.error(error.message);
+    } else {
+      logger.error('An unknown error occurred.');
+    }
+    process.exit(1);
+  } finally {
+    // 임시 디렉토리 정리
+    try {
+      await fs.rm(tempDir, { recursive: true, force: true });
+    } catch {
+      // 무시
+    }
+  }
+}

package/src/config.ts

@@ -0,0 +1,61 @@
+import { config as dotenvConfig } from 'dotenv';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+
+// 환경 변수 로드
+dotenvConfig();
+
+export interface NotionConfig {
+  tokenV2: string;
+  fileToken: string;
+}
+
+export interface ConverterOptions {
+  output: string;
+  imageDir: string;
+  filename?: string;
+  verbose: boolean;
+}
+
+export interface FullConfig extends NotionConfig, ConverterOptions {}
+
+/**
+ * Notion 인증 설정 가져오기
+ */
+export function getNotionConfig(): NotionConfig {
+  const tokenV2 = process.env.TOKEN_V2 || '';
+  const fileToken = process.env.FILE_TOKEN || '';
+
+  if (!tokenV2 || !fileToken) {
+    throw new Error(
+      'Notion 토큰이 설정되지 않았습니다.\n' +
+      '.env 파일에 TOKEN_V2와 FILE_TOKEN을 설정해주세요.\n' +
+      '자세한 내용은 .env.example을 참고하세요.'
+    );
+  }
+
+  return { tokenV2, fileToken };
+}
+
+/**
+ * 전체 설정 생성
+ */
+export function createConfig(options: ConverterOptions): FullConfig {
+  const notionConfig = getNotionConfig();
+
+  // 출력 디렉토리 절대 경로로 변환
+  const outputDir = resolve(process.cwd(), options.output);
+
+  return {
+    ...notionConfig,
+    ...options,
+    output: outputDir,
+  };
+}
+
+/**
+ * 디렉토리 존재 여부 확인
+ */
+export function ensureDirectoryExists(dir: string): boolean {
+  return existsSync(dir);
+}

package/src/core/exporter.ts

@@ -0,0 +1,75 @@
+import { NotionExporter } from 'notion-exporter';
+import { promises as fs } from 'fs';
+import path from 'path';
+import type { NotionConfig } from '../config.js';
+
+export interface ExportResult {
+  markdown: string;
+  imageFiles: Array<{ filename: string; sourcePath: string }>;
+}
+
+/**
+ * Notion 페이지를 마크다운으로 내보내기
+ */
+export class NotionMarkdownExporter {
+  private exporter: NotionExporter;
+
+  constructor(config: NotionConfig) {
+    this.exporter = new NotionExporter(config.tokenV2, config.fileToken);
+  }
+
+  /**
+   * Notion URL에서 마크다운과 이미지 파일 가져오기
+   */
+  async exportWithImages(notionUrl: string, tempDir: string): Promise<ExportResult> {
+    try {
+      // 임시 디렉토리 생성
+      await fs.mkdir(tempDir, { recursive: true });
+
+      // getMdFiles로 마크다운과 이미지를 함께 다운로드
+      await this.exporter.getMdFiles(notionUrl, tempDir);
+
+      // 다운로드된 파일 목록 가져오기
+      const files = await fs.readdir(tempDir, { withFileTypes: true });
+
+      // 마크다운 파일 찾기
+      const mdFile = files.find(f => f.isFile() && f.name.endsWith('.md'));
+      if (!mdFile) {
+        throw new Error('Markdown file not found.');
+      }
+
+      // 마크다운 내용 읽기
+      const mdPath = path.join(tempDir, mdFile.name);
+      const markdown = await fs.readFile(mdPath, 'utf-8');
+
+      // 이미지 파일 목록 (마크다운이 아닌 파일들)
+      const imageFiles = files
+        .filter(f => f.isFile() && !f.name.endsWith('.md'))
+        .map(f => ({
+          filename: f.name,
+          sourcePath: path.join(tempDir, f.name),
+        }));
+
+      // 디렉토리 내 폴더도 확인 (Notion이 폴더 구조로 저장할 수 있음)
+      const dirs = files.filter(f => f.isDirectory());
+      for (const dir of dirs) {
+        const subFiles = await fs.readdir(path.join(tempDir, dir.name), { withFileTypes: true });
+        for (const subFile of subFiles) {
+          if (subFile.isFile() && !subFile.name.endsWith('.md')) {
+            imageFiles.push({
+              filename: path.join(dir.name, subFile.name),
+              sourcePath: path.join(tempDir, dir.name, subFile.name),
+            });
+          }
+        }
+      }
+
+      return { markdown, imageFiles };
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new Error(`Failed to fetch Notion page: ${error.message}`);
+      }
+      throw new Error('Failed to fetch Notion page.');
+    }
+  }
+}

package/src/core/image-processor.ts

@@ -0,0 +1,118 @@
+import axios from 'axios';
+import { createWriteStream, promises as fs } from 'fs';
+import path from 'path';
+import { v4 as uuidv4 } from 'uuid';
+
+export interface ImageProcessResult {
+  markdown: string;
+  downloadedImages: string[];
+  failedImages: string[];
+}
+
+export interface ProcessorOptions {
+  outputDir: string;
+  imageDir: string;
+  verbose: boolean;
+}
+
+/**
+ * 이미지 다운로드 및 마크다운 경로 변환 처리
+ */
+export class ImageProcessor {
+  private options: ProcessorOptions;
+  private imageOutputDir: string;
+
+  constructor(options: ProcessorOptions) {
+    this.options = options;
+    this.imageOutputDir = path.join(options.outputDir, options.imageDir);
+  }
+
+  /**
+   * 이미지 디렉토리 생성
+   */
+  async ensureImageDirectory(): Promise<void> {
+    await fs.mkdir(this.imageOutputDir, { recursive: true });
+  }
+
+  /**
+   * 단일 이미지 다운로드
+   */
+  private async downloadImage(url: string): Promise<string> {
+    const response = await axios({
+      url,
+      method: 'GET',
+      responseType: 'stream',
+      timeout: 30000, // 30초 타임아웃
+    });
+
+    const extension = response.headers['content-type']?.split('/')[1] || 'png';
+    const fileName = `${uuidv4().slice(0, 8)}.${extension}`;
+    const filePath = path.join(this.imageOutputDir, fileName);
+
+    const writer = response.data.pipe(createWriteStream(filePath));
+
+    return new Promise((resolve, reject) => {
+      writer.on('finish', () => resolve(fileName));
+      writer.on('error', reject);
+    });
+  }
+
+  /**
+   * 마크다운에서 이미지 URL 추출
+   */
+  private extractImageUrls(markdown: string): string[] {
+    const imageUrlRegex = /!\[.*?\]\((https:\/\/[^)]+)\)/g;
+    const matches = [...markdown.matchAll(imageUrlRegex)];
+    return matches.map(match => match[1]);
+  }
+
+  /**
+   * 마크다운 내 이미지 처리
+   */
+  async processMarkdown(markdown: string): Promise<ImageProcessResult> {
+    await this.ensureImageDirectory();
+
+    const imageUrls = this.extractImageUrls(markdown);
+
+    if (this.options.verbose) {
+      console.log(`\n총 ${imageUrls.length}개의 이미지 발견`);
+      console.log(`이미지 다운로드 시작...\n`);
+    }
+
+    let processedMarkdown = markdown;
+    const downloadedImages: string[] = [];
+    const failedImages: string[] = [];
+
+    // 이미지 다운로드 (순차 처리)
+    for (const url of imageUrls) {
+      try {
+        if (this.options.verbose) {
+          console.log(`다운로드 중: ${url}`);
+        }
+
+        const fileName = await this.downloadImage(url);
+        const relativePath = `./${this.options.imageDir}/${fileName}`;
+
+        // 마크다운 내 URL 교체
+        processedMarkdown = processedMarkdown.replaceAll(url, relativePath);
+        downloadedImages.push(fileName);
+
+        if (this.options.verbose) {
+          console.log(`✓ 저장됨: ${relativePath}\n`);
+        }
+      } catch (error) {
+        failedImages.push(url);
+        if (this.options.verbose) {
+          const errorMsg = error instanceof Error ? error.message : '알 수 없는 오류';
+          console.error(`✗ 실패: ${url}\n  ${errorMsg}\n`);
+        }
+      }
+    }
+
+    return {
+      markdown: processedMarkdown,
+      downloadedImages,
+      failedImages,
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { mdCommand } from './commands/md.js';
+import { debugCommand } from './commands/debug.js';
+
+const program = new Command();
+
+program
+  .name('nconv')
+  .description('CLI tool for converting Notion pages to blog-ready markdown')
+  .version('1.0.0');
+
+program
+  .command('md <url>')
+  .description('Convert a Notion page to markdown')
+  .option('-o, --output <dir>', 'Output directory', './output')
+  .option('-i, --image-dir <dir>', 'Image folder name (relative to output)', 'images')
+  .option('-f, --filename <name>', '출력 파일명 (확장자 제외 또는 포함)')
+  .option('-v, --verbose', 'Enable verbose logging', false)
+  .action(async (url: string, options) => {
+    await mdCommand(url, {
+      output: options.output,
+      imageDir: options.imageDir,
+      filename: options.filename,
+      verbose: options.verbose,
+    });
+  });
+
+// 개발 환경에서만 debug 명령어를 활성화
+if (process.env.NODE_ENV !== 'production') {
+  program
+    .command('debug <url>')
+    .description('Debug: Output raw markdown and image URLs')
+    .option('-o, --output <dir>', '출력 디렉토리', './output')
+    .option('-i, --image-dir <dir>', 'Image folder name', 'images')
+    .option('-v, --verbose', 'Enable verbose logging', false)
+    .action(async (url: string, options) => {
+      await debugCommand(url, {
+        output: options.output,
+        imageDir: options.imageDir,
+        filename: '',
+        verbose: options.verbose,
+      });
+    });
+}
+
+program.parse();

package/src/utils/file.ts

@@ -0,0 +1,69 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import slugify from 'slugify';
+import { v4 as uuidv4 } from 'uuid';
+
+/**
+ * Notion URL에서 페이지 제목 추출 (간단한 버전)
+ */
+export function extractTitleFromUrl(notionUrl: string): string | null {
+  try {
+    const url = new URL(notionUrl);
+    const pathname = url.pathname;
+
+    // /Page-Title-abc123 형식에서 제목 부분 추출
+    const match = pathname.match(/\/([^/]+)-[a-f0-9]{32}$/i);
+    if (match) {
+      const title = match[1].replace(/-/g, ' ');
+      return title;
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 안전한 파일명 생성
+ */
+export function generateSafeFilename(title: string | null, extension: string = 'md'): string {
+  if (title) {
+    const slug = slugify(title, {
+      lower: true,
+      strict: true,
+      locale: 'ko',
+    });
+
+    if (slug.length > 0) {
+      return extension ? `${slug}.${extension}` : slug;
+    }
+  }
+
+  // 제목이 없거나 slugify 실패 시 UUID 사용
+  const hash = uuidv4().slice(0, 8);
+  return extension ? `notion-export-${hash}.${extension}` : `notion-export-${hash}`;
+}
+
+/**
+ * 마크다운 파일 저장
+ */
+export async function saveMarkdownFile(
+  outputDir: string,
+  filename: string,
+  content: string
+): Promise<string> {
+  await fs.mkdir(outputDir, { recursive: true });
+
+  const filePath = path.join(outputDir, filename);
+  await fs.writeFile(filePath, content, 'utf-8');
+
+  return filePath;
+}
+
+/**
+ * 파일 경로를 상대 경로로 변환
+ */
+export function toRelativePath(from: string, to: string): string {
+  return path.relative(from, to);
+}

package/src/utils/logger.ts

@@ -0,0 +1,37 @@
+import chalk from 'chalk';
+import ora, { Ora } from 'ora';
+
+/**
+ * 성공 메시지 출력
+ */
+export function success(message: string): void {
+  console.log(chalk.green('✓'), message);
+}
+
+/**
+ * 에러 메시지 출력
+ */
+export function error(message: string): void {
+  console.error(chalk.red('✗'), message);
+}
+
+/**
+ * 정보 메시지 출력
+ */
+export function info(message: string): void {
+  console.log(chalk.blue('ℹ'), message);
+}
+
+/**
+ * 경고 메시지 출력
+ */
+export function warn(message: string): void {
+  console.log(chalk.yellow('⚠'), message);
+}
+
+/**
+ * 스피너 생성
+ */
+export function spinner(text: string): Ora {
+  return ora(text).start();
+}