@knpkv/confluence-to-markdown 0.2.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # @knpkv/confluence-to-markdown
 
+## 0.4.1
+
+### Patch Changes
+
+- [#23](https://github.com/knpkv/npm/pull/23) [`bd5bbf4`](https://github.com/knpkv/npm/commit/bd5bbf4679ae1d41b33182fcca70adf0960f0839) Thanks @konopkov! - feat(confluence-api-client): new package for Confluence Cloud REST API
+
+  New `@knpkv/confluence-api-client` package with Effect-based Confluence Cloud REST API client:
+  - V1 API: `/user`, `/content/{id}/property/{key}` endpoints
+  - V2 API: Pages CRUD with pagination support
+  - Basic auth (email + API token) and OAuth2 (access token + cloud ID)
+  - Effect Layer wrapper with config service
+  - Daily CI workflow for spec updates
+
+  Migrated `confluence-to-markdown` to use new API client package.
+
+- [#24](https://github.com/knpkv/npm/pull/24) [`cbbe42f`](https://github.com/knpkv/npm/commit/cbbe42f8747af8955aacfa64a7e3868035cffec5) Thanks @konopkov! - Fix Confluence link handling and consolidate preprocessing modules
+  - Handle `<ac:link><ac:link-body>` pattern that was being lost during conversion
+  - Consolidate duplicate preprocessing code (deleted `parsers/preprocessing/`)
+  - Remove type assertion casts in favor of Schema.decodeSync
+  - Fix CI: configure git user.name/email in init for fresh repos
+
+- Updated dependencies [[`bd5bbf4`](https://github.com/knpkv/npm/commit/bd5bbf4679ae1d41b33182fcca70adf0960f0839)]:
+  - @knpkv/confluence-api-client@0.2.0
+
+## 0.4.0
+
+### Minor Changes
+
+- [#21](https://github.com/knpkv/npm/pull/21) [`f696d00`](https://github.com/knpkv/npm/commit/f696d0056de28f2871a48a0caac88b696c86ba68) Thanks @konopkov! - Add git version tracking and CLI improvements
+  - Add GitService for git operations with version history replay
+  - Add clone command that pulls pages with full version history
+  - Flatten git commands: confluence commit/log/diff (was: confluence git ...)
+  - Add auth status subcommand
+  - Reorganize bin.ts into separate command files
+  - Add nice error messages without stack traces
+  - Clone fails if already cloned
+
+## 0.3.0
+
+### Minor Changes
+
+- [#19](https://github.com/knpkv/npm/pull/19) [`15b1ff7`](https://github.com/knpkv/npm/commit/15b1ff70e9e7a406ddbc4ce8bcd0673965464421) Thanks @konopkov! - Add OAuth authentication for Confluence Cloud
+  - `confluence auth create` - opens Atlassian Developer Console to create OAuth app
+  - `confluence auth configure` - save client ID/secret
+  - `confluence auth login` - browser-based OAuth flow
+  - `confluence auth logout` - remove stored token
+  - Show login status in `confluence status`
+  - Auto-refresh tokens when expired
+  - Use granular scopes for API v2: read:page:confluence, write:page:confluence
+
+## 0.2.1
+
+### Patch Changes
+
+- [#17](https://github.com/knpkv/npm/pull/17) [`879af56`](https://github.com/knpkv/npm/commit/879af56383230d852e1434efb67e6f5cdffd3507) Thanks @konopkov! - Improve type safety and code organization:
+  - Add MdastRootSchema with runtime validation
+  - Extract preprocessing to separate module
+  - Consolidate duplicate mdastToString utility
+  - Use exhaustive switch statements
+
 ## 0.2.0
 
 ### Minor Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 knpkv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -3,7 +3,7 @@
 > **Warning**
 > This package is experimental and in early development. Code is primarily AI-generated and not yet publicly published. For preview, use snapshot releases.
 
-Sync Confluence Cloud pages to local GitHub Flavored Markdown files.
+Sync Confluence Cloud pages to local GitHub Flavored Markdown files with built-in git version tracking.
 
 ## Installation
 
@@ -13,47 +13,315 @@ npm install @knpkv/confluence-to-markdown effect
 
 ## CLI Usage
 
+### Core Commands
+
 ```bash
-# Initialize configuration
-confluence init --root-page-id 123456 --base-url https://yoursite.atlassian.net
+# Clone pages with full version history
+confluence clone --root-page-id <ID> --base-url <URL>
 
 # Pull pages from Confluence
 confluence pull
+confluence pull -f, --force           # overwrite local changes
+confluence pull --replay-history      # replay each version as separate git commit
 
 # Push local changes to Confluence
 confluence push
+confluence push -n, --dry-run         # preview changes without applying
 
-# Bidirectional sync
-confluence sync
+# Delete a page (interactive selector, deletes local file)
+confluence delete
 
 # Check sync status
 confluence status
 ```
 
+### Authentication Commands
+
+```bash
+# Create OAuth app (opens browser to Atlassian Developer Console)
+confluence auth create
+
+# Configure OAuth credentials
+confluence auth configure --client-id <ID> --client-secret <SECRET>
+
+# Login via browser
+confluence auth login
+confluence auth login --site <URL>    # for accounts with multiple sites
+
+# Check auth status
+confluence auth status
+
+# Logout
+confluence auth logout
+```
+
+### Page Creation
+
+```bash
+# Create a new page (interactive parent selector)
+confluence new
+
+# Workflow:
+# 1. Create new page: confluence new
+# 2. Edit the file
+# 3. Commit: confluence commit -m "Add new page"
+# 4. Push to Confluence: confluence push
+```
+
+### Page Deletion
+
+```bash
+# Delete a page (interactive selector)
+confluence delete
+
+# Workflow:
+# 1. Delete page: confluence delete (or rm <file>)
+# 2. Commit: confluence commit -m "Delete page"
+# 3. Push to Confluence: confluence push  # deletes from Confluence
+```
+
+### Git Commands
+
+```bash
+# Commit current changes
+confluence commit
+confluence commit -m "message"
+
+# Show commit history
+confluence log
+confluence log -n 5               # last 5 commits
+confluence log --oneline          # compact format
+confluence log --since 2024-01-01 # since date
+
+# Show changes in working directory
+confluence diff
+confluence diff --staged          # staged changes only
+confluence diff --commit HEAD~1   # compare with commit
+```
+
+## How It Works
+
+1. `confluence clone` creates `.confluence/` directory, initializes git, and pulls pages with full version history
+2. `confluence pull` downloads pages and auto-commits changes
+3. `confluence pull --replay-history` replays each Confluence version as a separate git commit with original author/date
+4. Version messages from Confluence are preserved in markdown front-matter
+5. Use standard git commands in `.confluence/` for advanced operations
+
+## Git Implementation
+
+### Two-Branch Model
+
+The CLI uses a two-branch model to track sync state:
+
+- **`local`** (current branch): Your working branch for edits
+- **`origin/confluence`**: Tracks the remote Confluence state
+
+```
+Clone:
+  Confluence ──pull──> local + origin/confluence (both at same commit)
+
+Pull:
+  Confluence ──pull──> origin/confluence ──merge──> local
+
+Push:
+  local ──push──> Confluence
+    │
+    └──> origin/confluence (updated to HEAD)
+```
+
+### Commit Behavior
+
+When you commit:
+
+1. **Sync external docs** (if configured): Copies files from external `docsPath` to `.confluence/`
+2. **Stage all changes**: Runs `git add -A`
+3. **Create commit**: Records changes with your message
+
+Note: Front-matter (`contentHash`, `version`) is **not** updated at commit time. Changes are detected by comparing actual content hash vs stored hash.
+
+### Push Behavior
+
+When you push:
+
+1. **Detect changes**: Compares content hash vs stored `contentHash` in front-matter
+2. **Push to Confluence**: Uploads markdown converted to Confluence storage format
+3. **Fetch canonical content**: Downloads what Confluence actually stored (may differ slightly)
+4. **Amend commit**: Updates local file with canonical content so future clones match exactly
+5. **Update tracking branch**: Moves `origin/confluence` to HEAD
+
+Multiple local commits combine into a single Confluence version (uses last commit's message).
+
+### Content Hash Tracking
+
+Each markdown file has front-matter with a `contentHash` field:
+
+```yaml
+---
+pageId: "123456"
+version: 42
+title: My Page
+contentHash: 7a8b9c... # SHA-256 of markdown content
+---
+```
+
+- After clone/pull: `contentHash` matches the actual content
+- After local edit: content differs from `contentHash` → detected as "needs push"
+- After push: `contentHash` updated to match canonical Confluence content
+
+### Why Canonical Content?
+
+Confluence may transform your content (normalize whitespace, reorder attributes, etc.). By fetching and storing the canonical content after push:
+
+- `clone` on another machine produces **identical** files
+- Git history shows exactly what Confluence has
+- No false "modified" status from round-trip differences
+
+## Authentication
+
+### OAuth (recommended)
+
+#### 1. Create OAuth App
+
+1. Go to [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/)
+2. Click **Create** → **OAuth 2.0 integration**
+3. Enter app name (e.g., "Confluence CLI")
+4. Configure permissions in **Permissions** tab:
+   - Add **Confluence API** with scopes:
+     - `read:page:confluence` - read pages
+     - `write:page:confluence` - push changes
+     - `delete:page:confluence` - delete pages
+   - Add **User Identity API**:
+     - `read:me` - get current user info
+5. In **Authorization** tab, set callback URL: `http://localhost:8585/callback`
+6. In **Settings** tab, copy **Client ID** and **Secret**
+
+#### 2. Configure and Login
+
+```bash
+# Configure with your client ID and secret
+confluence auth configure --client-id <ID> --client-secret <SECRET>
+
+# Login via browser
+confluence auth login
+
+# Check login status
+confluence status
+
+# Logout
+confluence auth logout
+```
+
+### API Token (alternative)
+
+```bash
+export CONFLUENCE_API_KEY=your-api-token
+export CONFLUENCE_EMAIL=your-email@example.com
+```
+
+Generate API token at [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens).
+
+### Security Notes
+
+- OAuth credentials stored in `~/.confluence/` with restricted permissions (0600)
+- Treat these files as sensitive - do not share or commit
+- Create separate OAuth apps per developer for team projects
+- Tokens auto-refresh; if refresh fails, re-run `confluence auth login`
+
 ## Configuration
 
-Create `.confluence.json` in your project root:
+Initialize configuration with `confluence clone`:
+
+```bash
+confluence clone --root-page-id 123456 --base-url https://yoursite.atlassian.net
+```
+
+This creates `.confluence/config.json` in your project root:
 
 ```json
 {
   "rootPageId": "123456",
   "baseUrl": "https://yoursite.atlassian.net",
-  "spaceKey": "DEV",
-  "docsPath": ".docs/confluence"
+  "docsPath": ".confluence/docs",
+  "excludePatterns": [],
+  "saveSource": false,
+  "trackedPaths": ["**/*.md"]
 }
 ```
 
-## Environment Variables
+### Configuration Options
 
-```bash
-export CONFLUENCE_API_KEY=your-api-token
-export CONFLUENCE_EMAIL=your-email@example.com
+| Option            | Description                           | Default            |
+| ----------------- | ------------------------------------- | ------------------ |
+| `rootPageId`      | Confluence page ID to sync from       | Required           |
+| `baseUrl`         | Confluence Cloud URL                  | Required           |
+| `spaceKey`        | Optional space key                    | -                  |
+| `docsPath`        | Local path for markdown files         | `.confluence/docs` |
+| `excludePatterns` | Glob patterns to exclude              | `[]`               |
+| `saveSource`      | Save original HTML alongside markdown | `false`            |
+| `trackedPaths`    | Glob patterns for git tracking        | `["**/*.md"]`      |
+
+## Directory Structure
+
+```
+project/
+├── .confluence/
+│   ├── config.json      # Configuration file
+│   ├── .git/            # Git repository for version tracking
+│   └── docs/            # Synced markdown files
+│       ├── page1.md
+│       ├── page1/       # Children of page1
+│       │   └── child.md
+│       └── subdir/
+│           └── page2.md
+└── ...
+```
+
+### Page Hierarchy Rules
+
+Directory structure determines Confluence page hierarchy:
+
+- Files in `docs/` root → children of root page
+- `foo.md` → page "foo"
+- `foo/` directory → contains children of "foo.md"
+- `foo/bar.md` → child page of "foo.md"
+
+Example structure:
+
+```
+docs/
+├── guide.md           # Child of root
+├── guide/             # Children of guide.md
+│   ├── getting-started.md
+│   └── advanced.md
+└── reference.md       # Child of root
+```
+
+### New Page Front-matter
+
+New pages require only a `title` in front-matter:
+
+```yaml
+---
+title: "My New Page"
+---
+Page content here...
+```
+
+After pushing, the file is updated with full metadata:
+
+```yaml
+---
+pageId: "123456"
+version: 1
+title: "My New Page"
+updated: 2024-01-15T10:30:00.000Z
+parentId: "789012"
+contentHash: "7a8b9c..."
+---
 ```
 
 ## Known Limitations
 
-- **Page creation**: Creating new pages from local markdown is not yet implemented
-- **Conflict detection**: Bidirectional sync does not detect conflicts (last write wins)
 - **Attachments**: Image and file attachments are not synced
 - **Comments**: Page comments are not preserved
 

package/dist/ConfluenceAuth.d.ts

@@ -0,0 +1,76 @@
+import * as CommandExecutor from "@effect/platform/CommandExecutor";
+import * as HttpClient from "@effect/platform/HttpClient";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type { FileSystemError } from "./ConfluenceError.js";
+import { AuthMissingError, OAuthError } from "./ConfluenceError.js";
+import type { OAuthConfig, OAuthUser } from "./Schemas.js";
+/**
+ * Options for the login method.
+ */
+export interface LoginOptions {
+    /** Site URL to select (for accounts with multiple sites) */
+    readonly siteUrl?: string;
+}
+/**
+ * Information about an accessible Confluence site.
+ */
+export interface AccessibleSite {
+    readonly id: string;
+    readonly name: string;
+    readonly url: string;
+}
+/**
+ * ConfluenceAuth service interface.
+ *
+ * @category Services
+ */
+export interface ConfluenceAuthService {
+    /** Configure OAuth client credentials */
+    readonly configure: (config: OAuthConfig) => Effect.Effect<void, FileSystemError>;
+    /** Check if OAuth is configured */
+    readonly isConfigured: () => Effect.Effect<boolean, FileSystemError>;
+    /** Start OAuth login flow. Returns list of sites if multiple are available. */
+    readonly login: (options?: LoginOptions) => Effect.Effect<ReadonlyArray<AccessibleSite> | void, OAuthError | FileSystemError>;
+    /** Remove stored authentication */
+    readonly logout: () => Effect.Effect<void, OAuthError | FileSystemError>;
+    /** Get access token, refreshing if needed */
+    readonly getAccessToken: () => Effect.Effect<string, AuthMissingError | OAuthError | FileSystemError>;
+    /** Get cloud ID from stored token */
+    readonly getCloudId: () => Effect.Effect<string, AuthMissingError | FileSystemError>;
+    /** Get current user info from stored token */
+    readonly getCurrentUser: () => Effect.Effect<OAuthUser | null, FileSystemError>;
+    /** Check if user is logged in */
+    readonly isLoggedIn: () => Effect.Effect<boolean, FileSystemError>;
+}
+declare const ConfluenceAuth_base: Context.TagClass<ConfluenceAuth, "@knpkv/confluence-to-markdown/ConfluenceAuth", ConfluenceAuthService>;
+/**
+ * ConfluenceAuth service tag.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect"
+ * import { ConfluenceAuth } from "@knpkv/confluence-to-markdown/ConfluenceAuth"
+ *
+ * Effect.gen(function* () {
+ *   const auth = yield* ConfluenceAuth
+ *   const isLoggedIn = yield* auth.isLoggedIn()
+ *   if (!isLoggedIn) {
+ *     yield* auth.login()
+ *   }
+ * })
+ * ```
+ *
+ * @category Services
+ */
+export declare class ConfluenceAuth extends ConfluenceAuth_base {
+}
+/**
+ * Layer for ConfluenceAuth service.
+ *
+ * @category Layers
+ */
+export declare const layer: Layer.Layer<ConfluenceAuth, never, HttpClient.HttpClient | CommandExecutor.CommandExecutor>;
+export {};
+//# sourceMappingURL=ConfluenceAuth.d.ts.map

package/dist/ConfluenceAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfluenceAuth.d.ts","sourceRoot":"","sources":["../src/ConfluenceAuth.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,eAAe,MAAM,kCAAkC,CAAA;AACnE,OAAO,KAAK,UAAU,MAAM,6BAA6B,CAAA;AAEzD,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAEzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAIrC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAWnE,OAAO,KAAK,EAAE,WAAW,EAAc,SAAS,EAAE,MAAM,cAAc,CAAA;AAqEtE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAAC,CAAA;IACjF,mCAAmC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,eAAe,CAAC,CAAA;IACpE,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,CACd,OAAO,CAAC,EAAE,YAAY,KACnB,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,cAAc,CAAC,GAAG,IAAI,EAAE,UAAU,GAAG,eAAe,CAAC,CAAA;IACtF,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,eAAe,CAAC,CAAA;IACxE,6CAA6C;IAC7C,QAAQ,CAAC,cAAc,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,GAAG,eAAe,CAAC,CAAA;IACrG,qCAAqC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,eAAe,CAAC,CAAA;IACpF,8CAA8C;IAC9C,QAAQ,CAAC,cAAc,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,GAAG,IAAI,EAAE,eAAe,CAAC,CAAA;IAC/E,iCAAiC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,eAAe,CAAC,CAAA;CACnE;;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,cAAe,SAAQ,mBAGjC;CAAG;AA6YN;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAC7B,cAAc,EACd,KAAK,EACL,UAAU,CAAC,UAAU,GAAG,eAAe,CAAC,eAAe,CACnB,CAAA"}