@dockstat/outline-sync 1.1.3 → 1.2.0

package/README.md

@@ -1,271 +1,253 @@
-# outline-sync — `@dockstat/outline-sync`
+# Outline Sync
 
-Sync Outline (app.getoutline.com) collections ↔ Markdown in your repo.
-Designed for multi-collection pipelines.
-Features:
+Bidirectional sync for Outline wiki to local folders with CI/CD support.
 
-* Two-way sync (pull / push / timestamp-based sync)
-* Multi-collection support (`--collection` repeatable)
-* Folder-based default storage (each page → `<slug>/README.md`, children inherit folders)
-* Per-collection mapping file for custom paths
-* Config-driven: `configs/outline-sync.json`, `<collection>.config.json`, `<collection>.pages.json`
-* Whitespace/newline-agnostic diffs (formatting-only changes are ignored)
-* Uses Git commit time when available (falls back to fs mtime)
-* Dry-run mode, backups of overwritten files
+## Installation
 
----
+```bash
+bun install
+bun run build
+```
+
+## Configuration
 
-# Install
+### Option 1: Config File (Recommended)
 
-Using `bunx` (recommended):
+Create `outline-sync.config.json`:
 
 ```bash
-bunx @dockstat/outline-sync <command> [flags]
+outline-sync init
 ```
 
-> Security note: prefer `OUTLINE_API_KEY=...` in CI or environment. Passing `--api-key="..."` is supported but may expose the key in process lists or shell history.
+Then edit the generated file:
 
----
+```json
+{
+  "url": "https://your-outline.com",
+  "token": "your_api_token",
+  "outputDir": "./outline-docs",
+  "customPaths": {
+    "doc-id-abc123": "../../README.md",
+    "doc-id-xyz789": "custom/important-doc.md"
+  }
+}
+```
+
+**Custom Paths:**
+- Document IDs can be found in the Outline URL or via the API
+- Paths starting with `..` are relative to current working directory
+- Other paths are relative to `outputDir`
 
-# Quickstart (recommended)
+**Finding Document IDs:**
+1. Open document in Outline
+2. Check URL: `https://outline.com/doc/my-document-abc123` (ID is `abc123`)
+3. Or run initial sync and check frontmatter in generated files
 
-1. Set your API key:
+### Option 2: Environment Variables
 
 ```bash
-export OUTLINE_API_KEY="sk_..."   # recommended for local / CI usage
+export OUTLINE_URL=https://your-outline.com
+export OUTLINE_TOKEN=your_api_token
+export OUTLINE_OUTPUT_DIR=./outline-docs
 ```
 
-2. Interactive setup (lists collections and lets you register one):
+### Option 3: CLI Arguments
 
-```bash
-bunx @dockstat/outline-sync setup
-```
+Pass configuration via command line (takes precedence over other methods).
 
-3. Bootstrap a collection (non-interactive):
+## Usage
 
-```bash
-bunx @dockstat/outline-sync init --collection="COLLECTION_UUID"
-# or multiple:
-bunx @dockstat/outline-sync init --collection="id1" --collection="id2"
-```
+### Commands
 
-This creates/updates:
+**Initialize config file:**
 
-* `configs/outline-sync.json` — top-level config listing collections
-* `configs/<collection-id>.config.json` — per-collection mapping config
-* `configs/<collection-id>.pages.json` — assembled manifest of pages (used by sync)
-* `docs/...` — markdown files saved folder-based (`<slug>/README.md`)
+```bash
+outline-sync init
+```
 
-4. Run a dry-run sync:
+**One-time sync (down only):**
 
 ```bash
-bunx @dockstat/outline-sync sync --collection="COLLECTION_UUID" --dry-run
+outline-sync sync
+# or with config file
+outline-sync sync --config custom-config.json
 ```
 
-5. Run an actual sync/push/pull:
+**Watch mode (bidirectional):**
 
 ```bash
-bunx @dockstat/outline-sync sync --collection="COLLECTION_UUID"
-bunx @dockstat/outline-sync pull --collection="COLLECTION_UUID"
-bunx @dockstat/outline-sync push --collection="COLLECTION_UUID"
+outline-sync watch
 ```
 
-You can pass `--collection` multiple times to run against several collections in one invocation:
+**CI/CD mode:**
 
 ```bash
-bunx @dockstat/outline-sync sync \
-  --collection="id-one" --collection="id-two" \
-  --dry-run
+outline-sync ci
 ```
 
-You can also pass `--api-key="sk_..."` or `--base-url="https://custom.outline"` on the CLI; these override environment variables.
+## API Reference (CLI Commands)
 
----
+### `outline-sync init`
 
-# CLI reference
+Creates a sample `outline-sync.config.json` configuration file in the current directory.
 
-```
-Usage:
-  OUTLINE_API_KEY=... bunx @dockstat/outline-sync [command] [--collection=ID]... [--dry-run] [--api-key="..."]
-
-Commands:
-  setup                    - interactive setup (list & add a collection)
-  list-collections         - print the collections visible to the API key
-  init --collection=ID     - bootstrap pages.json + markdown for collection (repeatable)
-  pull --collection=ID     - pull remote changes into local files (repeatable)
-  push --collection=ID     - push local changes to remote (repeatable)
-  sync --collection=ID     - bidirectional sync (timestamp-based) (repeatable)
-
-Flags:
-  --collection=ID          Repeatable; run command for multiple collection ids
-  --dry-run                Preview actions (no writes to Outline or disk)
-  --api-key="..."          Provide Outline API key (overrides env var)
-  --base-url="..."         Custom Outline base URL (overrides default)
-  --help, -h
+**Example:**
+```bash
+outline-sync init
 ```
 
----
+### `outline-sync sync [options]`
 
-# Config layout & examples
+Performs a one-time synchronization from your Outline wiki to your local folder. This command only pulls changes from Outline.
 
-Project layout:
+**Options:**
 
-```
-configs/
-  outline-sync.json            # top-level config (collections list)
-  <collection_id>.config.json  # mapping rules + saveDir for a collection
-  <collection_id>.pages.json   # assembled pages manifest used by sync
-docs/                           # markdown files (default saveDir)
+- `--url <url>`: The URL of your Outline instance. Can also be set via `OUTLINE_URL` env var or config file.
+- `--token <token>`: Your Outline API token. Can also be set via `OUTLINE_TOKEN` env var or config file.
+- `--output <dir>`: The local directory where documents will be stored. Default: `./outline-docs`
+- `--config <path>`: Path to config file. Default: `./outline-sync.config.json`
+
+**Example:**
+```bash
+outline-sync sync --url https://my.outline.app --token <YOUR_TOKEN> --output ~/my-wiki
 ```
 
-## `configs/outline-sync.json` (top-level)
+### `outline-sync watch [options]`
 
-```json
-{
-  "collections": [
-    {
-      "id": "COLLECTION_UUID",
-      "name": "Support Docs",
-      "saveDir": "docs",
-      "pagesFile": "configs/COLLECTION_UUID.pages.json",
-      "configFile": "configs/COLLECTION_UUID.config.json"
-    }
-  ]
-}
-```
+Starts a persistent process that watches for changes in your local directory and syncs them to Outline, and also pulls new changes from Outline periodically. This enables bidirectional synchronization.
 
-## `configs/<collection_id>.config.json` (mapping rules)
+**Options:**
 
-```json
-{
-  "collectionId": "COLLECTION_UUID",
-  "saveDir": "docs",
-  "mappings": [
-    {
-      "match": { "id": "doc-id-123" },
-      "path": "guides/setup/"         // directory mapping → will place doc as guides/setup/README.md
-    },
-    {
-      "match": { "title": "API Reference" },
-      "path": "reference/README.md"    // explicit filename mapping
-    }
-  ]
-}
-```
+- `--url <url>`: The URL of your Outline instance.
+- `--token <token>`: Your Outline API token.
+- `--output <dir>`: The local directory being watched. Default: `./outline-docs`
+- `--config <path>`: Path to config file. Default: `./outline-sync.config.json`
 
-Rules:
+**Example:**
+```bash
+outline-sync watch
+```
 
-* Match by `id` (preferred) or `title` (exact match).
-* `path` can be:
+### `outline-sync ci [options]`
 
-  * directory-like (`guides/setup/` or any path without `.md`) → page becomes `<path>/README.md` and children inherit that directory,
-  * explicit file (`reference/README.md`) → used verbatim (relative to project root unless you give an absolute path),
-  * bare filename → placed under parent directory or `saveDir`.
+Executes a CI/CD-friendly synchronization. This command first pulls all documents from Outline, then checks for any local changes in your configured output directory, and finally pushes those local changes back to Outline. Designed for automated environments.
 
-## `configs/<collection_id>.pages.json` (generated)
+**Options:**
 
-This is a manifest of pages used by the sync engine. Example:
+- `--url <url>`: The URL of your Outline instance.
+- `--token <token>`: Your Outline API token.
+- `--output <dir>`: The local directory to synchronize. Default: `./outline-docs`
+- `--config <path>`: Path to config file. Default: `./outline-sync.config.json`
 
-```json
-{
-  "collectionId": "COLLECTION_UUID",
-  "pages": [
-    {
-      "title": "Product",
-      "file": "docs/product/README.md",
-      "id": "doc-product-id",
-      "children": [
-        {
-          "title": "Getting Started",
-          "file": "docs/product/getting-started/README.md",
-          "id": "doc-getting-started-id",
-          "children": []
-        }
-      ]
-    }
-  ]
-}
+**Example:**
+```bash
+outline-sync ci --output ./project-docs
 ```
 
-`pages.json` is updated when new remote documents are created (IDs get written back).
-
 ---
 
-# How syncing & conflict resolution works
+## Examples
 
-* The tool uses Git commit timestamp (if file is tracked) as the authoritative local timestamp. If Git info isn't available, it falls back to filesystem modification time.
-* For `sync` (default bidirectional flow): the *newer* version wins (remote.updatedAt vs local timestamp). The tool **ignores whitespace/newline-only differences** when deciding whether content actually differs — if the only difference is formatting, no update is performed.
-* For `pull`: remote always wins and overwrites the local file if content differs (ignoring whitespace).
-* For `push`: local always wins; remote is updated if content differs (ignoring whitespace).
-* When writing to existing local files, a backup is created: `path/to/file.md.outline-sync.bak.<timestamp>`.
+### Example 1: Root README
 
----
+Place a specific document as your project's main README:
 
-# File layout style
+```json
+{
+  "customPaths": {
+    "doc-abc123": "../../README.md"
+  }
+}
+```
 
-Default behavior: folder-based.
+### Example 2: Mixed Structure
 
-For each page:
+Combine auto-organized docs with custom locations:
 
-```
-<saveDir>/<ancestor-slug>/<page-slug>/README.md
+```json
+{
+  "outputDir": "./docs",
+  "customPaths": {
+    "doc-home": "../../README.md",
+    "doc-api": "../../API.md",
+    "doc-contrib": "../../CONTRIBUTING.md"
+  }
+}
 ```
 
-Example Outline structure:
+Other documents without custom paths will be organized in `./docs` by collection.
 
-* Product
+### Example 3: Getting Document IDs
 
-  * Getting Started
+After first sync, check the frontmatter:
 
-    * Install
-
-Results in:
+````markdown
+---
+id: abc123def456
+title: My Document
+collectionId: xyz789
+parentDocumentId: null
+updatedAt: '2024-01-15T10:30:00Z'
+urlId: my-document-abc123
+---
 
-```
-docs/product/README.md
-docs/product/getting-started/README.md
-docs/product/getting-started/install/README.md
+Document content here...
 ```
 
-You can override per-page locations in the `<collection_id>.config.json` mappings (see above).
+Use the `id` field in your `customPaths` configuration.
 
----
-
-# Advanced notes
+## Features
 
-* **Multiple collections:** pass `--collection` multiple times to operate on multiple collections in order. If `--collection` is not provided, the tool will operate on all collections listed in `configs/outline-sync.json`.
-* **API key sources:** first CLI `--api-key`, then `OUTLINE_API_KEY` env var. Passing `--api-key` sets `process.env.OUTLINE_API_KEY` early so imports read it properly.
-* **Base URL:** `--base-url` for self-hosted/alternate Outline instances.
-* **Dry-run:** always test with `--dry-run` before doing real `push`/`sync`.
-* **Mappings precedence:** `id` match wins over `title` match; explicit mapping wins and children will inherit directories if mapping points to a directory.
-* **Mapping templates:** not supported by default; you can use direct paths and directories via `path` in mapping rules.
+- ✅ Sync Outline → Local
+- ✅ Sync Local → Outline
+- ✅ Each doc in own folder with README.md
+- ✅ Custom path mapping for specific documents
+- ✅ Frontmatter metadata preservation
+- ✅ CI/CD integration
+- ✅ File watching
 
----
+## CI/CD Integration
 
-# Troubleshooting
+### GitHub Actions
 
-* "Manifest not found": run `init --collection=ID` or `setup` to create `configs/<collection_id>.pages.json`.
-* API errors / auth: check `OUTLINE_API_KEY` (or pass `--api-key`) and `--base-url`. Ensure token has access to the collection.
-* Permissions / writing files: make sure the process has write permissions for `docs/` and `configs/`.
-* Large collections: the Outline API is paginated (the client already pages with limit=100). If you hit rate limits, re-run with fewer collections at a time or add retries in your CI.
+```yaml
+name: Outline Sync
 
----
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "0 */6 * * *" # Every 6 hours
 
-# Contributing & development
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v1
+      - run: bun install
+      - run: bun run ci
+        env:
+          OUTLINE_URL: ${{ secrets.OUTLINE_URL }}
+          OUTLINE_TOKEN: ${{ secrets.OUTLINE_TOKEN }}
+      - uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "docs: sync from Outline"
+```
 
-Contributions welcome!
+Store `outline-sync.config.json` in your repo (without sensitive tokens):
 
-* Repo layout is modular (`bin/cli.ts`, `lib/*.ts`) — feel free to add features:
+```json
+{
+  "outputDir": "./docs",
+  "customPaths": {
+    "doc-abc123": "../../README.md"
+  }
+}
+```
 
-  * mapping templates (`{{slug}}`) or glob rules
-  * parallel collection sync with a `--concurrent` flag
-  * a `--api-key-file` option to read secrets from a file
-  * richer conflict resolution (merge or interactive prompts)
+Tokens can be passed via environment variables in CI.
 
-When developing locally:
+## License
 
-```bash
-# run CLI against a local checkout
-bun run bin/cli.ts setup
-bun run bin/cli.ts init --collection="..."
-```
+MIT