plane-migrate 0.1.0__tar.gz

plane_migrate-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    name: Lint & Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint — ruff check
+        run: ruff check src/ tests/
+
+      - name: Lint — ruff format check
+        run: ruff format --check src/ tests/
+
+      - name: Run tests
+        run: pytest --cov=planemigrate --cov-report=term-missing --cov-report=xml
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v4
+        if: matrix.python-version == '3.11'
+        with:
+          name: coverage-report
+          path: coverage.xml

plane_migrate-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+dist/
+*.egg-info/
+.env
+*.log
+migration-plan-*.yaml
+# migration state files (<src-proj-id>-<dst-proj-id>.json)
+????????-????-????-????-????????????-????????-????-????-????-????????????.json

plane_migrate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Manish Gupta
+
+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.

plane_migrate-0.1.0/PKG-INFO

@@ -0,0 +1,464 @@
+Metadata-Version: 2.4
+Name: plane-migrate
+Version: 0.1.0
+Summary: Migrate projects between Plane instances or workspaces
+License: MIT License
+        
+        Copyright (c) 2025 Manish Gupta
+        
+        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.
+License-File: LICENSE
+Keywords: migration,plane,project-management
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: plane-sdk<1.0.0,>=0.2.8
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# plane-migrate
+
+A CLI tool to migrate projects between [Plane](https://plane.so) instances or between workspaces on the same instance — with full fidelity, resumable runs, and delta re-runs.
+
+> **Works with**: Plane Cloud (`api.plane.so`) and self-hosted Plane instances (v0.23+)
+
+---
+
+## What gets migrated
+
+| Entity | Details |
+|:-------|:--------|
+| **Work Item Types** | Custom types defined in the source project |
+| **States** | All workflow states; matched by name to avoid duplicates |
+| **Labels** | All labels; matched by name |
+| **Members** | Matched by email across instances; unmatched members flagged in plan |
+| **Estimates** | Estimate schema + all points |
+| **Work Items** | Title, description, state, priority, assignee, labels, type, dates, estimate point, parent — roots first, then children |
+| **Relations** | `blocked_by`, `blocking`, `duplicate`, `relates_to` |
+| **Links** | External URLs attached to work items |
+| **Comments** | Full comment body with author attribution byline |
+| **Modules** | With work item membership |
+| **Cycles** | With work item membership |
+| **Intake** | Intake work items |
+| **Pages** | Requires `--session-cookie` (see [Pages](#pages-migration)) |
+
+### Known limitations
+
+| Gap | Reason |
+|:----|:-------|
+| Activity history | Plane API has no write endpoint for activity entries |
+| File attachments | Plane API has no attachment upload endpoint |
+| Page listing via API | Pages require a browser session cookie |
+
+---
+
+## Installation
+
+**Requires Python 3.11+**
+
+### Recommended — pipx (for CLI use)
+
+[pipx](https://pipx.pypa.io) installs CLI tools in isolated environments and makes them available globally. This is the recommended approach on any system.
+
+```bash
+# Install pipx if you don't have it
+# macOS
+brew install pipx && pipx ensurepath
+
+# Debian / Ubuntu
+sudo apt install pipx && pipx ensurepath
+
+# Install plane-migrate
+pipx install git+https://github.com/mguptahub/plane-migrate.git
+```
+
+### pip (inside a virtualenv)
+
+```bash
+python -m venv venv && source venv/bin/activate
+pip install git+https://github.com/mguptahub/plane-migrate.git
+```
+
+### Local development
+
+```bash
+git clone https://github.com/mguptahub/plane-migrate.git
+cd plane-migrate
+python -m venv venv && source venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Verify:
+
+```bash
+plane-migrate --help
+```
+
+---
+
+## Quick Start
+
+### Step 1 — Dry run
+
+Always start with a dry run. It fetches everything from source, previews what will be created, and writes a **plan YAML** — without touching the destination.
+
+```bash
+plane-migrate \
+  --src-url   https://api.plane.so \
+  --src-token  <source-api-token> \
+  --src-workspace  <source-workspace-slug> \
+  --src-project    <source-project-id-or-key> \
+  --dst-url   https://api.plane.so \
+  --dst-token  <destination-api-token> \
+  --dst-workspace  <destination-workspace-slug> \
+  --dst-project    <destination-project-id-or-key> \
+  --dry-run
+```
+
+This writes a `migration-plan-<timestamp>.yaml` in the current directory.
+
+### Step 2 — Review the plan
+
+```yaml
+members:
+  mapped:
+    - alice@old.com: alice@new.com    # auto-matched by email
+  unmatched:
+    bob@old.com: ""                   # ← fill in destination email
+  _hint: Fill in destination emails for unmatched members, then pass this file via --members-map.
+
+states:
+  create: [Todo, In Progress, Done]
+  skip:   [Backlog]                   # already exist on destination
+
+work_items:
+  total:    142
+  roots:    98
+  children: 44
+
+modules:  [Sprint 1, Sprint 2, Backlog]
+cycles:   [Q1 2025, Q2 2025]
+```
+
+Fill in any blank destination emails under `members.unmatched`.
+
+### Step 3 — Real run
+
+```bash
+plane-migrate \
+  --src-url   https://api.plane.so \
+  --src-token  <source-api-token> \
+  --src-workspace  <source-workspace-slug> \
+  --src-project    <source-project-id-or-key> \
+  --dst-url   https://api.plane.so \
+  --dst-token  <destination-api-token> \
+  --dst-workspace  <destination-workspace-slug> \
+  --dst-project    <destination-project-id-or-key> \
+  --members-map migration-plan-<timestamp>.yaml
+```
+
+---
+
+## Environment Variables
+
+All flags can be set via environment variables — useful for CI or repeated runs:
+
+| Variable | Flag equivalent |
+|:---------|:----------------|
+| `PLANE_SRC_URL` | `--src-url` |
+| `PLANE_SRC_TOKEN` | `--src-token` |
+| `PLANE_SRC_WORKSPACE` | `--src-workspace` |
+| `PLANE_DST_URL` | `--dst-url` |
+| `PLANE_DST_TOKEN` | `--dst-token` |
+| `PLANE_DST_WORKSPACE` | `--dst-workspace` |
+| `PLANE_SESSION_COOKIE` | `--session-cookie` |
+| `PLANE_MIGRATE_LOG` | `--log-file` |
+
+```bash
+export PLANE_SRC_URL=https://api.plane.so
+export PLANE_SRC_TOKEN=plane_api_...
+export PLANE_SRC_WORKSPACE=my-workspace
+export PLANE_DST_URL=https://self-hosted.example.com
+export PLANE_DST_TOKEN=plane_api_...
+export PLANE_DST_WORKSPACE=my-workspace
+
+plane-migrate \
+  --src-project <src-project-id> \
+  --dst-project <dst-project-id>
+```
+
+---
+
+## All CLI Flags
+
+```
+plane-migrate [OPTIONS]
+
+Source:
+  --src-url TEXT          Source Plane instance URL
+  --src-token TEXT        Source API token
+  --src-workspace TEXT    Source workspace slug
+  --src-project TEXT      Source project UUID or key
+
+Destination:
+  --dst-url TEXT          Destination Plane instance URL
+  --dst-token TEXT        Destination API token
+  --dst-workspace TEXT    Destination workspace slug
+  --dst-project TEXT      Destination project UUID or key
+
+Options:
+  --dry-run / -n          Preview what would be migrated — writes a plan YAML
+  --only TEXT             Migrate only specific entities (repeatable)
+  --members-map TEXT      YAML file mapping src emails → dst emails
+  --plan-file TEXT        Where to write the dry-run plan (default: migration-plan-<ts>.yaml)
+  --state-file TEXT       State file path for resumable runs (default: <src>-<dst>.json)
+  --session-cookie TEXT   Browser session cookie for page migration
+  --log-file TEXT         Log file path
+```
+
+---
+
+## Selective Migration — `--only`
+
+Migrate only specific entity types. Can be repeated.
+
+```bash
+# Re-run only links and comments (fill gaps)
+plane-migrate ... --only links --only comments
+
+# Migrate only work items and relations
+plane-migrate ... --only work-items --only relations
+
+# Migrate pages (requires session cookie)
+plane-migrate ... --only pages --session-cookie "..."
+```
+
+**Valid `--only` values:**
+
+| Value | What it migrates |
+|:------|:-----------------|
+| `types` | Work item types |
+| `states` | Workflow states |
+| `labels` | Labels |
+| `members` | Member matching (no destination writes) |
+| `estimates` | Estimate schema + points |
+| `work-items` | All work items (roots + children) |
+| `relations` | Work item relations |
+| `links` | External URL links on work items |
+| `comments` | Work item comments |
+| `modules` | Modules + work item membership |
+| `cycles` | Cycles + work item membership |
+| `intake` | Intake work items |
+| `pages` | Pages (requires `--session-cookie`) |
+
+---
+
+## Resumable Runs & Gap Filling
+
+Every successful write is tracked in a **state file** (`<src-project-id>-<dst-project-id>.json`). If a run is interrupted — network error, rate limit, crash — just rerun the same command. The migrator will:
+
+- **Skip** entities already created (tracked by source ID → destination ID mapping)
+- **Fill gaps** for links and comments — only creates the ones missing per work item
+- **Save state incrementally** — progress is never lost mid-run
+
+```bash
+# Interrupted run — just rerun, it picks up where it left off
+plane-migrate ... --state-file my-migration.json
+```
+
+### State file structure
+
+```json
+{
+  "src_project": "...",
+  "dst_project": "...",
+  "states":      { "<src-state-id>": "<dst-state-id>", ... },
+  "labels":      { "<src-label-id>": "<dst-label-id>", ... },
+  "work_items":  { "<src-item-id>":  "<dst-item-id>",  ... },
+  "modules":     [{ "src": "...", "dst": "...", "workitems": [...] }],
+  "cycles":      [{ "src": "...", "dst": "...", "workitems": [...] }],
+  "links_done":    { "<src-item-id>": ["<src-link-id>", ...] },
+  "comments_done": { "<src-item-id>": ["<src-comment-id>", ...] },
+  "relations":   ["<src-item-id>:relation_type:<src-related-id>", ...]
+}
+```
+
+> Keep the state file between runs. Deleting it causes the migrator to treat everything as new — resulting in duplicates in the destination.
+
+---
+
+## Members Mapping
+
+Members are matched **by email** between source and destination. When the source and destination share the same Plane instance (workspace-to-workspace migration), members are automatically matched.
+
+When migrating across instances, emails may differ. Unmatched members appear in the dry-run plan:
+
+```yaml
+members:
+  unmatched:
+    old-email@company.com: ""    # ← fill in new email
+```
+
+Pass the edited plan file (or any YAML with `src_email: dst_email` pairs) via `--members-map`:
+
+```bash
+plane-migrate ... --members-map migration-plan.yaml
+```
+
+Work items assigned to unmatched members will still be migrated — but without an assignee.
+
+---
+
+## Pages Migration
+
+Pages require a **browser session cookie** because the public API does not expose a page listing endpoint. The session cookie is used only to fetch page content — no writes happen with it.
+
+### Getting the session cookie
+
+1. Open your Plane instance in a browser and log in
+2. Open DevTools → Application → Cookies
+3. Copy the values of `csrftoken` and `session-id`
+4. Pass them as a single string:
+
+```bash
+plane-migrate ... \
+  --session-cookie "csrftoken=abc123; session-id=xyz789"
+```
+
+If `--session-cookie` is not provided, pages are skipped and noted in the summary.
+
+---
+
+## Logging
+
+Every run writes a structured JSON log to `plane-migrate-<timestamp>.log` (or the path from `--log-file` / `PLANE_MIGRATE_LOG`).
+
+Each line is a JSON event:
+
+```json
+{"ts": "2025-04-01T10:23:45Z", "kind": "created", "entity": "work_item", "name": "Fix login bug", "src_id": "abc", "dst_id": "xyz"}
+{"ts": "2025-04-01T10:23:46Z", "kind": "skipped", "entity": "label",     "name": "Bug", "detail": "already exists"}
+{"ts": "2025-04-01T10:23:47Z", "kind": "failed",  "entity": "comment",   "name": "on abc", "detail": "429 Too Many Requests"}
+```
+
+Tail in real time:
+
+```bash
+tail -f plane-migrate-*.log | python3 -c "
+import sys, json
+for line in sys.stdin:
+    e = json.loads(line)
+    print(f\"{e['ts'][11:19]} [{e['kind']:8}] {e['entity']:12} {e['name']}\")
+"
+```
+
+---
+
+## Rate Limiting
+
+The migrator writes at ~3 requests/second (`300ms` delay between writes). On HTTP `429 Too Many Requests`, it backs off automatically:
+
+- Wait 30s → retry
+- Wait 45s → retry
+- Wait 60s → retry
+- Fail and log the error
+
+Failures are logged and counted but do not abort the run. Use `--only` to re-run specific phases after fixing rate limit issues.
+
+---
+
+## Cross-Instance Migration
+
+Migrating from one Plane deployment to another (e.g. Plane Cloud → self-hosted):
+
+```bash
+plane-migrate \
+  --src-url        https://api.plane.so \
+  --src-token      plane_api_<cloud-token> \
+  --src-workspace  my-cloud-workspace \
+  --src-project    <project-id> \
+  --dst-url        https://plane.mycompany.com \
+  --dst-token      plane_api_<selfhosted-token> \
+  --dst-workspace  my-internal-workspace \
+  --dst-project    <project-id> \
+  --members-map    members.yaml
+```
+
+---
+
+## Same-Instance Workspace Migration
+
+Migrating between two workspaces on the same Plane instance (same token works for both):
+
+```bash
+plane-migrate \
+  --src-url        https://api.plane.so \
+  --src-token      plane_api_<token> \
+  --src-workspace  old-workspace \
+  --src-project    <src-project-id> \
+  --dst-url        https://api.plane.so \
+  --dst-token      plane_api_<token> \
+  --dst-workspace  new-workspace \
+  --dst-project    <dst-project-id>
+```
+
+Members are auto-matched by email — no `--members-map` needed.
+
+---
+
+## Comparison with Plane's Native Export
+
+| Capability | CSV Export/Import | JSON Export | plane-migrate |
+|:-----------|:-----------------:|:-----------:|:-------------:|
+| Work items | ✓ (flat) | ✓ | ✓ |
+| States / Labels | names only | names only | ✓ full remap |
+| Comments | ✗ | ✓ | ✓ with attribution |
+| Relations | ✗ | ✓ | ✓ |
+| Links | ✗ | ✓ | ✓ |
+| Modules / Cycles | ✗ | names only | ✓ with membership |
+| Estimates | ✗ | ✗ | ✓ |
+| Pages | ✗ | ✗ | ✓ (session cookie) |
+| Intake | ✗ | ✗ | ✓ |
+| Member remapping | ✗ | ✗ | ✓ |
+| Resumable | ✗ | ✗ | ✓ |
+| Re-importable | ✓ | ✗ | ✓ |
+
+---
+
+## Contributing
+
+Pull requests are welcome. When contributing:
+
+- Keep the migration sequence order (types → states → labels → members → estimates → work-items → relations → links → comments → modules → cycles → intake → pages)
+- All new entity types should follow the same pattern: fetch from source → remap IDs → create on destination → track in state file
+- State must be saved incrementally (per entity, not at the end of the run)
+
+---
+
+## License
+
+MIT