create-confluence-sync 1.0.0

package/README.md

@@ -0,0 +1,111 @@
+# create-confluence-sync
+
+Bidirectional documentation sync between local files and Confluence Server via Git.
+
+Edit XHTML files locally, commit — changes sync to Confluence automatically. Someone edits in Confluence — changes sync back on your next commit.
+
+## Quick Start
+
+```bash
+npx create-confluence-sync
+```
+
+The wizard will ask for:
+- Confluence URL
+- Personal Access Token
+- Space to sync
+
+It downloads all pages, sets up Git with auto-sync hooks, and you're ready.
+
+## How It Works
+
+1. You edit `.xhtml` files in `docs/` folder
+2. You `git commit`
+3. Post-commit hook automatically:
+   - Pulls changes from Confluence
+   - Merges with your changes
+   - Pushes your changes to Confluence
+   - Updates the local tree map
+
+## File Structure
+
+After setup:
+```
+your-project/
+├── docs/
+│   └── LLS/                    # your Confluence space
+│       ├── Page Title/
+│       │   ├── Page Title.xhtml
+│       │   └── Child Page/
+│       │       └── Child Page.xhtml
+├── .confluence/
+│   ├── config.json             # connection settings (gitignored)
+│   └── tree.json               # page map (tracked in git)
+├── AGENTS.md                   # instructions for AI agents
+└── .gitignore
+```
+
+## Commands
+
+```bash
+# Setup (first time)
+npx create-confluence-sync
+
+# Manual sync
+npx create-confluence-sync sync
+
+# Push specific file
+npx create-confluence-sync sync "docs/LLS/Page/Page.xhtml"
+
+# Restore hidden pages (interactive)
+npx create-confluence-sync restore
+
+# Restore by name
+npx create-confluence-sync restore "Page Title"
+
+# List spaces
+npx create-confluence-sync spaces
+
+# Get page content
+npx create-confluence-sync page <pageId>
+
+# View remote tree
+npx create-confluence-sync tree
+
+# View local tree
+npx create-confluence-sync local-tree
+
+# Delete page from Confluence
+npx create-confluence-sync delete <pageId>
+```
+
+## Hiding Pages (Virtual Delete)
+
+Delete a file or folder locally and commit. The page stays in Confluence but stops syncing locally. Use `restore` to bring it back.
+
+## Format
+
+Files use Confluence Storage Format (XHTML):
+```html
+<h2>Title</h2>
+<p>Text with <strong>bold</strong> and <em>italic</em>.</p>
+<ul>
+  <li>Item 1</li>
+  <li>Item 2</li>
+</ul>
+```
+
+## AI Agent Compatible
+
+The generated `AGENTS.md` file contains full instructions for AI agents (Claude, GPT, etc.) to create, edit, and manage documentation through the same Git workflow.
+
+## Requirements
+
+- Node.js 20+
+- Git
+- Confluence Server with REST API access
+- Personal Access Token
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "create-confluence-sync",
+  "version": "1.0.0",
+  "description": "Bidirectional Confluence Server documentation sync via Git. Edit XHTML locally, commit, auto-sync with Confluence.",
+  "type": "module",
+  "bin": {
+    "create-confluence-sync": "./src/cli.js"
+  },
+  "main": "./src/cli.js",
+  "scripts": {
+    "start": "node src/cli.js",
+    "test": "node --test tests/e2e.test.js"
+  },
+  "keywords": [
+    "confluence",
+    "sync",
+    "documentation",
+    "git"
+  ],
+  "author": "damix96",
+  "license": "MIT",
+  "dependencies": {
+    "@inquirer/prompts": "^7.10.1"
+  }
+}

package/src/agents-md.js

@@ -0,0 +1,273 @@
+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.
+
+## 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.
+
+| Parameter | Value |
+|-----------|-------|
+| Confluence URL | ${baseUrl} |
+| Space | ${space} |
+| Last synced | ${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
+\u2514\u2500\u2500 .gitignore
+\`\`\`
+
+### docs/${space}/
+
+This folder mirrors the Confluence space hierarchy:
+
+- **Folder** = Confluence page
+- **Nesting** = parent-child relationship
+- **File \`{title}.xhtml\`** inside the folder = page content
+
+### .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)
+
+---
+
+## File format
+
+Pages are stored in **Confluence Storage Format** (XHTML with Confluence-specific tags).
+
+### Basic markup
+
+\`\`\`xhtml
+<h2>Heading</h2>
+<p>Text with <strong>bold</strong> and <em>italic</em>.</p>
+
+<ul>
+  <li>Item 1</li>
+  <li>Item 2</li>
+</ul>
+
+<ol>
+  <li>First</li>
+  <li>Second</li>
+</ol>
+\`\`\`
+
+### Tables
+
+\`\`\`xhtml
+<table>
+  <tbody>
+    <tr>
+      <th>Column A</th>
+      <th>Column B</th>
+    </tr>
+    <tr>
+      <td>Value 1</td>
+      <td>Value 2</td>
+    </tr>
+  </tbody>
+</table>
+\`\`\`
+
+### Code blocks (Confluence macro)
+
+\`\`\`xhtml
+<ac:structured-macro ac:name="code">
+  <ac:parameter ac:name="language">java</ac:parameter>
+  <ac:plain-text-body><![CDATA[public class Example {
+    public static void main(String[] args) {
+        System.out.println("Hello");
+    }
+}]]></ac:plain-text-body>
+</ac:structured-macro>
+\`\`\`
+
+### Info/warning panels
+
+\`\`\`xhtml
+<ac:structured-macro ac:name="info">
+  <ac:rich-text-body>
+    <p>This is an informational note.</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)
+
+### 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)
+
+---
+
+## How to create a new page
+
+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
+
+## 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:
+   \`\`\`
+   git add "docs/${space}/path/to/Page.xhtml"
+   git commit -m "Update page: Page"
+   \`\`\`
+4. Changes will be automatically pushed to Confluence
+
+## How to hide (virtually delete) a page
+
+Hiding removes the page from your local tree without deleting it from Confluence.
+
+1. Delete the folder/file from the file system
+2. Commit:
+   \`\`\`
+   git add -A
+   git commit -m "Hide page: Page Name"
+   \`\`\`
+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
+
+---
+
+## Current page tree
+
+\`\`\`
+${treeBlock}
+\`\`\`
+
+---
+
+*Generated by confluence-sync*
+`;
+}
+
+/**
+ * Generate and write AGENTS.md to the project root.
+ *
+ * @param {string} projectRoot - absolute path to project root
+ * @param {object} config - parsed config (baseUrl/url, space, token)
+ * @param {object} tree - parsed tree.json (space, pages, lastSync, etc.)
+ */
+export function generateAgentsMd(projectRoot, config, tree) {
+  const content = buildContent(config, tree);
+  const filePath = path.join(projectRoot, 'AGENTS.md');
+  fs.writeFileSync(filePath, content, 'utf-8');
+  return filePath;
+}

package/src/api.js

@@ -0,0 +1,207 @@
+import https from 'node:https';
+import http from 'node:http';
+
+process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
+
+function request(baseUrl, token, method, path, body = null) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(path, baseUrl);
+    const transport = url.protocol === 'https:' ? https : http;
+
+    const options = {
+      method,
+      hostname: url.hostname,
+      port: url.port || (url.protocol === 'https:' ? 443 : 80),
+      path: url.pathname + url.search,
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Accept': 'application/json',
+      },
+    };
+
+    const payload = body !== null ? JSON.stringify(body) : null;
+
+    if (payload !== null) {
+      options.headers['Content-Type'] = 'application/json; charset=utf-8';
+      options.headers['Content-Length'] = Buffer.byteLength(payload);
+    }
+
+    const req = transport.request(options, (res) => {
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('end', () => {
+        const buffer = Buffer.concat(chunks);
+
+        if (res.statusCode >= 400) {
+          const text = buffer.toString('utf-8');
+          let message;
+          try {
+            const json = JSON.parse(text);
+            message = json.message || json.errorMessage || text;
+          } catch {
+            message = text;
+          }
+          reject(new Error(`Confluence API error ${res.statusCode}: ${message}`));
+          return;
+        }
+
+        resolve({ statusCode: res.statusCode, buffer, headers: res.headers });
+      });
+    });
+
+    req.on('error', reject);
+
+    if (payload !== null) {
+      req.write(payload);
+    }
+
+    req.end();
+  });
+}
+
+async function jsonRequest(baseUrl, token, method, path, body = null) {
+  const { buffer } = await request(baseUrl, token, method, path, body);
+  const text = buffer.toString('utf-8');
+  if (!text) return null;
+  return JSON.parse(text);
+}
+
+export function createApiClient(config) {
+  const { baseUrl, token } = config;
+
+  async function getSpaces() {
+    const data = await jsonRequest(baseUrl, token, 'GET', '/rest/api/space');
+    return data.results;
+  }
+
+  async function getPageTree(spaceKey) {
+    const pages = {};
+    let start = 0;
+    const limit = 500;
+
+    while (true) {
+      const data = await jsonRequest(
+        baseUrl, token, 'GET',
+        `/rest/api/content?spaceKey=${encodeURIComponent(spaceKey)}&expand=ancestors,version&limit=${limit}&start=${start}`
+      );
+
+      if (!data.results || data.results.length === 0) break;
+
+      for (const page of data.results) {
+        const ancestors = page.ancestors || [];
+        const parentId = ancestors.length > 0
+          ? String(ancestors[ancestors.length - 1].id)
+          : null;
+
+        pages[String(page.id)] = {
+          title: page.title,
+          parentId,
+          version: page.version.number,
+        };
+      }
+
+      if (data.size + data.start >= data.totalSize) break;
+      start += data.results.length;
+    }
+
+    return pages;
+  }
+
+  async function getPageContent(pageId) {
+    const data = await jsonRequest(
+      baseUrl, token, 'GET',
+      `/rest/api/content/${pageId}?expand=body.storage,version`
+    );
+
+    return {
+      title: data.title,
+      body: data.body?.storage?.value || '',
+      version: data.version?.number || 0,
+    };
+  }
+
+  async function getPageAttachments(pageId) {
+    const data = await jsonRequest(
+      baseUrl, token, 'GET',
+      `/rest/api/content/${pageId}/child/attachment`
+    );
+
+    return (data.results || []).map((att) => ({
+      id: String(att.id),
+      title: att.title,
+      version: att.version?.number || 0,
+      downloadPath: att._links?.download || null,
+    }));
+  }
+
+  async function createPage(spaceKey, parentId, title, body) {
+    const payload = {
+      type: 'page',
+      title,
+      space: { key: spaceKey },
+      body: {
+        storage: {
+          value: body,
+          representation: 'storage',
+        },
+      },
+    };
+
+    if (parentId) {
+      payload.ancestors = [{ id: String(parentId) }];
+    }
+
+    const data = await jsonRequest(baseUrl, token, 'POST', '/rest/api/content', payload);
+
+    return {
+      id: String(data.id),
+      version: data.version.number,
+    };
+  }
+
+  async function updatePage(pageId, title, body, currentVersion) {
+    const payload = {
+      type: 'page',
+      title,
+      version: { number: currentVersion + 1 },
+      body: {
+        storage: {
+          value: body,
+          representation: 'storage',
+        },
+      },
+    };
+
+    const data = await jsonRequest(
+      baseUrl, token, 'PUT',
+      `/rest/api/content/${pageId}`,
+      payload
+    );
+
+    return {
+      id: String(data.id),
+      version: data.version.number,
+    };
+  }
+
+  async function downloadAttachment(downloadPath) {
+    const { buffer } = await request(baseUrl, token, 'GET', downloadPath);
+    return buffer;
+  }
+
+  async function deletePage(pageId) {
+    await request(baseUrl, token, 'DELETE', `/rest/api/content/${pageId}`);
+    return { deleted: true, pageId: String(pageId) };
+  }
+
+  return {
+    getSpaces,
+    getPageTree,
+    getPageContent,
+    getPageAttachments,
+    createPage,
+    updatePage,
+    deletePage,
+    downloadAttachment,
+  };
+}