create-confluence-sync 1.0.2 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-confluence-sync",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Bidirectional Confluence Server documentation sync via Git. Edit XHTML locally, commit, auto-sync with Confluence.",
   "type": "module",
   "bin": {

package/src/agents-md.js

@@ -1,168 +1,97 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-/**
- * Build a tree structure from flat pages map.
- * Returns array of root nodes, each with nested `children`.
- */
-function buildPageTree(pages) {
-  const nodes = {};
-  const roots = [];
-
-  for (const [id, page] of Object.entries(pages)) {
-    nodes[id] = { id, ...page, children: [] };
-  }
-
-  for (const [id, node] of Object.entries(nodes)) {
-    if (node.parentId && nodes[node.parentId]) {
-      nodes[node.parentId].children.push(node);
-    } else {
-      roots.push(node);
-    }
-  }
-
-  // Sort children alphabetically by title at each level
-  const sortChildren = (nodeList) => {
-    nodeList.sort((a, b) => a.title.localeCompare(b.title));
-    for (const node of nodeList) {
-      sortChildren(node.children);
-    }
-  };
-  sortChildren(roots);
-
-  return roots;
-}
-
-/**
- * Render a tree of pages as an indented directory listing.
- * Only visible (non-hidden) pages are shown.
- */
-function renderTree(roots, space, indent = '') {
-  const lines = [];
-
-  for (let i = 0; i < roots.length; i++) {
-    const node = roots[i];
-    if (node.hidden) continue;
-
-    const isLast = i === roots.length - 1;
-    const connector = isLast ? '\u2514\u2500\u2500 ' : '\u251c\u2500\u2500 ';
-    const childIndent = indent + (isLast ? '    ' : '\u2502   ');
-
-    lines.push(`${indent}${connector}${node.title}/`);
-    lines.push(`${childIndent}\u251c\u2500\u2500 ${node.title}.xhtml`);
-
-    const visibleChildren = node.children.filter((c) => !c.hidden);
-    const childLines = renderTree(visibleChildren, space, childIndent);
-    if (childLines.length > 0) {
-      lines.push(...childLines);
-    }
-  }
-
-  return lines;
-}
-
-/**
- * Generate the full AGENTS.md content.
- */
 function buildContent(config, tree) {
   const space = tree.space || config.space || 'SPACE';
   const baseUrl = tree.baseUrl || config.baseUrl || config.url || '';
   const lastSync = tree.lastSync || 'never';
 
-  const roots = buildPageTree(tree.pages || {});
-  const visibleRoots = roots.filter((r) => !r.hidden);
-  const treeLines = renderTree(visibleRoots, space);
-  const treeBlock =
-    treeLines.length > 0
-      ? `docs/${space}/\n${treeLines.join('\n')}`
-      : `docs/${space}/ (empty)`;
-
   return `# AGENTS.md
 
-> Auto-generated by confluence-sync. Do not edit manually.
-> Re-generated on every sync.
+> Автоматически сгенерировано confluence-sync. Не редактировать вручную.
+> Пересоздаётся при каждой синхронизации.
 
-## What is this project
+## Что это за проект
 
-This repository is a **bidirectional documentation sync** between a local file system and **Confluence**.
-All interaction happens through files and git commits — no direct Confluence API calls needed.
+Этот репозиторий — **двусторонняя синхронизация документации** между локальной файловой системой и **Confluence**.
+Вся работа происходит через файлы и git-коммиты — прямые вызовы Confluence API не нужны.
 
-| Parameter | Value |
-|-----------|-------|
+| Параметр | Значение |
+|----------|----------|
 | Confluence URL | ${baseUrl} |
-| Space | ${space} |
-| Last synced | ${lastSync} |
+| Пространство | ${space} |
+| Последняя синхронизация | ${lastSync} |
 
 ---
 
-## File structure
+## Структура файлов
 
 \`\`\`
 project-root/
-\u251c\u2500\u2500 docs/${space}/          <- documentation mirror of Confluence space
-\u251c\u2500\u2500 .confluence/           <- internal data, DO NOT TOUCH
-\u2502   \u251c\u2500\u2500 config.json        <- connection config (in .gitignore)
-\u2502   \u2514\u2500\u2500 tree.json          <- structure map (page IDs, versions, hidden flags)
-\u251c\u2500\u2500 AGENTS.md              <- this file
+\u251c\u2500\u2500 docs/${space}/          <- зеркало пространства Confluence
+\u251c\u2500\u2500 .confluence/           <- внутренние данные, НЕ ТРОГАТЬ
+\u2502   \u251c\u2500\u2500 config.json        <- конфигурация подключения (в .gitignore)
+\u2502   \u2514\u2500\u2500 tree.json          <- карта структуры (ID страниц, версии, скрытые флаги)
+\u251c\u2500\u2500 AGENTS.md              <- этот файл
 \u2514\u2500\u2500 .gitignore
 \`\`\`
 
 ### docs/${space}/
 
-This folder mirrors the Confluence space hierarchy:
+Эта папка зеркалирует иерархию пространства Confluence:
 
-- **Folder** = Confluence page
-- **Nesting** = parent-child relationship
-- **File \`{title}.xhtml\`** inside the folder = page content
+- **Папка** = страница Confluence
+- **Вложенность** = отношение parent-child
+- **Файл \`{название}.xhtml\`** внутри папки = контент страницы
 
 ### .confluence/
 
-Internal sync data. **Never modify these files manually.**
+Внутренние данные синхронизации. **Никогда не редактировать вручную.**
 
-- \`tree.json\` — map of all pages: their IDs, versions, paths, hidden flags
-- \`config.json\` — connection credentials (excluded from git)
+- \`tree.json\` — карта всех страниц: ID, версии, пути, скрытые флаги
+- \`config.json\` — учётные данные подключения (исключён из git)
 
 ---
 
-## File format
+## Формат файлов
 
-Pages are stored in **Confluence Storage Format** (XHTML with Confluence-specific tags).
+Страницы хранятся в **Confluence Storage Format** (XHTML с Confluence-специфичными тегами).
 
-### Basic markup
+### Базовая разметка
 
 \`\`\`xhtml
-<h2>Heading</h2>
-<p>Text with <strong>bold</strong> and <em>italic</em>.</p>
+<h2>Заголовок</h2>
+<p>Текст с <strong>жирным</strong> и <em>курсивом</em>.</p>
 
 <ul>
-  <li>Item 1</li>
-  <li>Item 2</li>
+  <li>Пункт 1</li>
+  <li>Пункт 2</li>
 </ul>
 
 <ol>
-  <li>First</li>
-  <li>Second</li>
+  <li>Первый</li>
+  <li>Второй</li>
 </ol>
 \`\`\`
 
-### Tables
+### Таблицы
 
 \`\`\`xhtml
 <table>
   <tbody>
     <tr>
-      <th>Column A</th>
-      <th>Column B</th>
+      <th>Колонка A</th>
+      <th>Колонка B</th>
     </tr>
     <tr>
-      <td>Value 1</td>
-      <td>Value 2</td>
+      <td>Значение 1</td>
+      <td>Значение 2</td>
     </tr>
   </tbody>
 </table>
 \`\`\`
 
-### Code blocks (Confluence macro)
+### Блоки кода (макрос Confluence)
 
 \`\`\`xhtml
 <ac:structured-macro ac:name="code">
@@ -175,86 +104,109 @@ Pages are stored in **Confluence Storage Format** (XHTML with Confluence-specifi
 </ac:structured-macro>
 \`\`\`
 
-### Info/warning panels
+### Информационные панели
 
 \`\`\`xhtml
 <ac:structured-macro ac:name="info">
   <ac:rich-text-body>
-    <p>This is an informational note.</p>
+    <p>Это информационная заметка.</p>
   </ac:rich-text-body>
 </ac:structured-macro>
 \`\`\`
 
 ---
 
-## Rules
+## Правила
 
-### MANDATORY
+### ОБЯЗАТЕЛЬНО
 
-- Work **only through files and git** — edit \`.xhtml\` files, then \`git commit\`
-- Create/edit \`.xhtml\` files in the correct folder under \`docs/${space}/\`
-- Commit your changes — synchronization is automatic (post-commit hook)
-- Follow valid XHTML format (Confluence Storage Format)
+- Работать **только через файлы и git** — редактировать \`.xhtml\` файлы, затем \`git commit\`
+- Создавать/редактировать \`.xhtml\` файлы в правильной папке внутри \`docs/${space}/\`
+- Коммитить изменения — синхронизация автоматическая (post-commit hook)
+- Соблюдать валидный XHTML формат (Confluence Storage Format)
+- Можно создать голый \`.xhtml\` файл без папки — sync автоматически обернёт его в одноимённую папку
 
-### FORBIDDEN
+### ЗАПРЕЩЕНО
 
-- **DO NOT** touch the \`.confluence/\` folder or any files inside it
-- **DO NOT** call the Confluence API directly
-- **DO NOT** bypass the sync flow
-- **DO NOT** modify git hooks (\`.git/hooks/\`)
-- **DO NOT** commit \`.confluence/config.json\` (it contains credentials)
+- **НЕ ТРОГАТЬ** папку \`.confluence/\` и любые файлы внутри неё
+- **НЕ ВЫЗЫВАТЬ** Confluence API напрямую
+- **НЕ ОБХОДИТЬ** sync flow
+- **НЕ ИЗМЕНЯТЬ** git hooks (\`.git/hooks/\`)
+- **НЕ КОММИТИТЬ** \`.confluence/config.json\` (содержит учётные данные)
 
 ---
 
-## How to create a new page
+## CLI команды
+
+\`\`\`bash
+npx create-confluence-sync sync              # ручная синхронизация
+npx create-confluence-sync sync <file>       # push конкретного файла
+npx create-confluence-sync restore           # восстановить скрытые страницы (интерактивно)
+npx create-confluence-sync restore "Название" # восстановить по имени
+npx create-confluence-sync spaces            # список пространств
+npx create-confluence-sync page <id>         # содержимое страницы
+npx create-confluence-sync tree              # remote дерево
+npx create-confluence-sync local-tree        # локальный tree.json
+npx create-confluence-sync delete <id>       # удалить страницу
+\`\`\`
 
-1. Identify the parent folder where the page should appear in the Confluence hierarchy
-2. Create a folder with the page title: \`docs/${space}/{parent}/New Page/\`
-3. Create a file with the same name: \`docs/${space}/{parent}/New Page/New Page.xhtml\`
-4. Write content in XHTML format (see examples above)
-5. Stage and commit:
-   \`\`\`
-   git add "docs/${space}/{parent}/New Page/"
-   git commit -m "Add page: New Page"
-   \`\`\`
-6. The page will be automatically created in Confluence
+---
+
+## Как найти нужную страницу
+
+- **По файловой системе**: просмотреть \`docs/${space}/\` — структура папок = структура Confluence
+- **По tree.json**: выполнить \`npx create-confluence-sync local-tree\` — вывод JSON со всеми страницами, их ID, путями и статусами
+- **По содержимому**: использовать grep/поиск по \`.xhtml\` файлам в \`docs/${space}/\`
+- **По ID**: \`npx create-confluence-sync page <id>\` — получить содержимое конкретной страницы из Confluence
+
+---
 
-## How to edit a page
+## Как создать новую страницу
 
-1. Find the \`.xhtml\` file for the page you want to edit
-2. Modify the content (keep valid XHTML)
-3. Commit:
+1. Определить родительскую папку в иерархии Confluence
+2. Создать папку с названием страницы: \`docs/${space}/{parent}/Новая страница/\`
+3. Создать файл с тем же именем: \`docs/${space}/{parent}/Новая страница/Новая страница.xhtml\`
+4. Написать контент в XHTML формате (см. примеры выше)
+5. Закоммитить:
    \`\`\`
-   git add "docs/${space}/path/to/Page.xhtml"
-   git commit -m "Update page: Page"
+   git add "docs/${space}/{parent}/Новая страница/"
+   git commit -m "Добавить страницу: Новая страница"
    \`\`\`
-4. Changes will be automatically pushed to Confluence
+6. Страница будет автоматически создана в Confluence
 
-## How to hide (virtually delete) a page
+> Также можно просто создать файл \`Новая страница.xhtml\` без папки — sync автоматически обернёт его в папку \`Новая страница/\`.
 
-Hiding removes the page from your local tree without deleting it from Confluence.
+## Как редактировать страницу
 
-1. Delete the folder/file from the file system
-2. Commit:
+1. Найти \`.xhtml\` файл нужной страницы
+2. Изменить контент (сохраняя валидный XHTML)
+3. Закоммитить:
    \`\`\`
-   git add -A
-   git commit -m "Hide page: Page Name"
+   git add "docs/${space}/путь/к/Страница.xhtml"
+   git commit -m "Обновить страницу: Страница"
    \`\`\`
-3. The file disappears locally, but the Confluence page remains intact
-4. The page will not be pulled back on future syncs
-5. To restore: set \`hidden: false\` for the page in \`.confluence/tree.json\` — this is the **only** allowed manual edit of \`.confluence/\` files — the page will reappear on next sync
+4. Изменения будут автоматически отправлены в Confluence
 
----
+## Как скрыть страницу (виртуальное удаление)
 
-## Current page tree
+Скрытие убирает страницу из локального дерева без удаления из Confluence.
 
-\`\`\`
-${treeBlock}
-\`\`\`
+1. Удалить папку/файл из файловой системы
+2. Закоммитить:
+   \`\`\`
+   git add -A
+   git commit -m "Скрыть страницу: Название"
+   \`\`\`
+3. Файл исчезнет локально, но страница в Confluence останется нетронутой
+4. Страница не будет скачиваться при будущих синхронизациях
+5. Для восстановления использовать команду:
+   \`\`\`
+   npx create-confluence-sync restore
+   \`\`\`
 
 ---
 
-*Generated by confluence-sync*
+*Сгенерировано confluence-sync*
 `;
 }