clawd-migrate 0.1.0

package/README.md

@@ -0,0 +1,92 @@
+# clawd-migrate
+
+Migrate from **moltbot** or **clawdbot** to **openclaw**. Preserves config, memory, and clawdbook (Moltbook) data. Works on any system.
+
+---
+
+## Quick start
+
+**Requirements:** Node.js 14+ and Python 3.x.
+
+```bash
+npx clawd-migrate
+```
+
+That starts the **interactive menu** (lobster + guided steps). For full install options and all commands, see **[HOW_TO_RUN.md](HOW_TO_RUN.md)**.
+
+---
+
+## What it does
+
+- **Discovers** your existing bot assets (memory files, config, clawdbook/Moltbook).
+- **Backs up** everything into a timestamped folder before any changes.
+- **Migrates** into the openclaw layout: `memory/`, `.config/openclaw/`, `.config/clawdbook/`, and preserves `projects/`.
+
+Supports both **moltbot** and **clawdbot** source layouts; no machine-specific paths.
+
+---
+
+## Install and run
+
+| Method | Command |
+|--------|--------|
+| Run without installing | `npx clawd-migrate` |
+| Install globally | `npm install -g clawd-migrate` then `clawd-migrate` |
+| Install in a project | `npm install clawd-migrate` then `npx clawd-migrate` |
+
+Full details, CLI options, and Python-only usage: **[HOW_TO_RUN.md](HOW_TO_RUN.md)**.
+
+---
+
+## Commands (CLI)
+
+```bash
+clawd-migrate                    # Interactive menu (default)
+clawd-migrate discover [--root PATH]
+clawd-migrate backup [--root PATH] [--backup-dir PATH]
+clawd-migrate migrate [--root PATH] [--no-backup] [--output PATH]
+```
+
+`--root` defaults to the current directory.
+
+---
+
+## What gets migrated
+
+- **Memory/identity:** SOUL.md, USER.md, TOOLS.md, IDENTITY.md, AGENTS.md, MEMORY.md  
+- **Config:** `.config/moltbook/`, `.config/moltbot/` (credentials and API keys)  
+- **Clawdbook/Moltbook:** Kept under `.config/clawdbook` in the openclaw layout  
+- **Extra:** `projects/` (if present)
+
+Backups go under `backups/` (or `--backup-dir`) with prefix `openclaw_migrate_backup_`.
+
+---
+
+## Tests
+
+From the repo root:
+
+```bash
+npm test
+```
+
+Runs Python unit tests for discover, backup, and migrate.
+
+---
+
+## Documentation
+
+| Doc | Description |
+|-----|-------------|
+| [HOW_TO_RUN.md](HOW_TO_RUN.md) | **How to run** – install, interactive mode, CLI, examples |
+| [Documentation/GITHUB.md](Documentation/GITHUB.md) | Publishing this repo to GitHub |
+| [Documentation/NPM_PUBLISH.md](Documentation/NPM_PUBLISH.md) | Publishing to npm |
+| [Documentation/TESTS.md](Documentation/TESTS.md) | Running and writing tests |
+| [Documentation/MIGRATION_SOURCES.md](Documentation/MIGRATION_SOURCES.md) | Moltbot/clawdbot support |
+| [Documentation/MIGRATION_TUI.md](Documentation/MIGRATION_TUI.md) | Interactive TUI (lobster + menu) |
+
+---
+
+## License
+
+MIT

package/bin/clawd-migrate.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const libDir = path.join(__dirname, "..", "lib");
+const env = { ...process.env, PYTHONPATH: libDir };
+
+const candidates = process.platform === "win32" ? ["python"] : ["python3", "python"];
+let result;
+for (const python of candidates) {
+  result = spawnSync(
+    python,
+    ["-m", "clawd_migrate", ...process.argv.slice(2)],
+    { stdio: "inherit", env, shell: process.platform === "win32" }
+  );
+  if (result.error && result.error.code === "ENOENT") continue;
+  break;
+}
+
+if (result.status === null && result.error) {
+  console.error("clawd-migrate: Python not found. Install Python 3 and ensure it is on PATH.");
+  process.exit(1);
+}
+process.exit(result.status != null ? result.status : 1);

package/lib/clawd_migrate/Documentation/GITHUB.md

@@ -0,0 +1,75 @@
+# This repository: clawd-migrate only
+
+**This folder (`clawd_migrate`) is the full repository.** There is one Git repo here; everything you need to publish lives in this directory.
+
+---
+
+## First-time: push to a new GitHub repo
+
+### 1. Create an empty repo on GitHub
+
+1. Go to [github.com](https://github.com) and sign in.
+2. Click **New repository** (or **+** → **New repository**).
+3. **Repository name:** e.g. `clawd-migrate`
+4. **Public**
+5. Do **not** add a README, .gitignore, or license (you already have them in this folder).
+6. Click **Create repository**.
+
+### 2. Add, commit, and push from this folder
+
+From **this folder** (the `clawd_migrate` directory):
+
+```bash
+git add .
+git status   # confirm .gitignore is excluding lib/, __pycache__, node_modules/
+git commit -m "Initial commit: clawd-migrate for moltbot/clawdbot to openclaw"
+git branch -M main
+git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO.git
+git push -u origin main
+```
+
+Replace `YOUR_USERNAME` and `YOUR_REPO` with your GitHub username and repo name (e.g. `clawd-migrate`).
+
+**Using SSH instead of HTTPS:**
+
+```bash
+git remote add origin git@github.com:YOUR_USERNAME/YOUR_REPO.git
+git push -u origin main
+```
+
+---
+
+## After the first push
+
+### Link package.json to the repo (optional)
+
+In `package.json`, set:
+
+```json
+"repository": {
+  "type": "git",
+  "url": "https://github.com/YOUR_USERNAME/YOUR_REPO.git"
+}
+```
+
+Then:
+
+```bash
+git add package.json
+git commit -m "Add repository URL to package.json"
+git push
+```
+
+### Publish to npm (optional)
+
+1. [npmjs.com](https://www.npmjs.com) account and `npm login`.
+2. From this folder: `npm publish` (or `npm publish --access public` for a scoped package).
+
+---
+
+## What’s in this repo
+
+- **Tracked:** All source (`.py`, `bin/`, `scripts/`, `tests/`, `Documentation/`), `package.json`, `README.md`, `HOW_TO_RUN.md`, `.gitignore`.
+- **Ignored:** `lib/` (generated on npm publish), `__pycache__/`, `node_modules/`.
+
+Clone this repo and run `npm test` to run tests, or install via npm once published.

package/lib/clawd_migrate/Documentation/MIGRATION_SOURCES.md

@@ -0,0 +1,48 @@
+# Migration Sources (moltbot / clawdbot) – Feature Tracking
+
+## Overview
+
+**clawd_migrate** supports upgrading from **moltbot** or **clawdbot** to **openclaw**. The tool is generalized for any user's system: no machine-specific paths, no user-specific references. Safe to publish and use anywhere.
+
+## Status
+
+- **Added:** 2025-02-01
+- **Source systems:** moltbot, clawdbot (discovery and migration for both)
+
+## What Was Generalized
+
+| Before | After |
+|--------|--------|
+| Clawdbot-only discovery | Unified discovery for moltbot + clawdbot |
+| `discover_clawdbot_assets` | `discover_source_assets` (canonical); `discover_clawdbot_assets` kept as alias |
+| Backup prefix `clawdbot_backup_` | `openclaw_migrate_backup_` (generic) |
+| User-specific comments (e.g. PipelineGPT) | Generic descriptions only |
+| Config: CLAWDBOT_* only | Config: SOURCE_* (union of moltbot + clawdbot paths) |
+
+## Source Layouts Supported
+
+- **Memory/identity:** SOUL.md, USER.md, TOOLS.md, IDENTITY.md, AGENTS.md, MEMORY.md (either system).
+- **Config (clawdbot):** `.config/moltbook/`, `.config/moltbook/credentials.json`.
+- **Config (moltbot):** `.config/moltbot/`, `.config/moltbot/credentials.json`; moltbook paths also checked.
+- **Extra:** `projects/` (both systems).
+- **Clawdbook/Moltbook:** Credentials and API keys from moltbook/moltbot paths are kept separate under `.config/clawdbook` in openclaw.
+
+## Files Touched
+
+- `config.py` – SOURCE_* names, moltbot paths, generic backup prefix, no machine-specific paths.
+- `discover.py` – `discover_source_assets()`, uses SOURCE_*; `discover_clawdbot_assets` alias.
+- `migrate.py` – Uses `discover_source_assets`; `is_clawdbook` includes moltbot paths.
+- `backup.py` – Uses `discover_source_assets`.
+- `__init__.py` – Exports `discover_source_assets` and `discover_clawdbot_assets`.
+- `__main__.py` – Help/description text: "moltbot or clawdbot"; "Source root".
+- `tui.py` – Banner and discover copy: "moltbot or clawdbot", "any user's system".
+
+## Backward Compatibility
+
+- `discover_clawdbot_assets(root)` still works; it calls `discover_source_assets(root)`.
+- Existing CLI flags and behavior unchanged; only copy and discovery scope updated.
+
+## Notes
+
+- Adding a new source system (e.g. another bot) only requires extending `SOURCE_*` in `config.py` and any path logic in `discover.py` / `migrate.py`.
+- No absolute paths or user names; all paths are relative to the chosen root (default: cwd).

package/lib/clawd_migrate/Documentation/MIGRATION_TUI.md

@@ -0,0 +1,51 @@
+# Migration TUI – Feature Tracking
+
+## Overview
+
+Interactive terminal UI for **clawd_migrate** that shows a lobster ASCII art on load and guides users through the migration process (discover -> backup -> migrate). Supports **moltbot or clawdbot** as source; works on any user's system (no machine-specific paths).
+
+## Status
+
+- **Added:** 2025-02-01
+- **Entry points:** `python -m clawd_migrate` (no args) or `python -m clawd_migrate run`
+
+## Features
+
+| Feature | Status |
+|--------|--------|
+| Lobster ASCII art on load (red lobster + cyan “CLAWD MIGRATE” text) | Done |
+| Welcome banner and tagline | Done |
+| Choose working directory (default: cwd) | Done |
+| Menu: Discover assets | Done |
+| Menu: Create backup only | Done |
+| Menu: Run full migration (backup first) | Done |
+| Menu: Migrate without backup (with warning) | Done |
+| Menu: Change working directory | Done |
+| Menu: Quit | Done |
+| ANSI colors (Windows Terminal / PowerShell 7+ / Unix) | Done |
+| Feature doc in Documentation/ | Done |
+
+## Usage
+
+```bash
+# Interactive mode (default)
+python -m clawd_migrate
+
+# Explicit interactive mode
+python -m clawd_migrate run
+
+# Existing CLI still works
+python -m clawd_migrate discover [--root PATH]
+python -m clawd_migrate backup [--root PATH] [--backup-dir PATH]
+python -m clawd_migrate migrate [--root PATH] [--no-backup] [--output PATH]
+```
+
+## Files
+
+- `tui.py` – TUI logic, lobster art, menu, discover/backup/migrate flows
+- `__main__.py` – Wires no-args and `run` to TUI; keeps existing subcommands
+
+## Notes
+
+- Colors use ANSI escape codes; supported in Windows Terminal and modern PowerShell.
+- Lobster art is ASCII-only for broad terminal compatibility.

package/lib/clawd_migrate/Documentation/NPM_PUBLISH.md

@@ -0,0 +1,51 @@
+# NPM Publish – Feature Tracking
+
+## Overview
+
+**clawd_migrate** is deployable to NPM so users can install and run it with `npm install clawd-migrate` or `npx clawd-migrate`. The NPM package wraps the Python tool; Node runs the bin script, which invokes Python with the bundled package.
+
+## Status
+
+- **Added:** 2025-02-01
+- **Package name:** `clawd-migrate`
+- **Bin:** `clawd-migrate` → `bin/clawd-migrate.js`
+
+## Requirements for users
+
+- **Node.js** 14+ (to run the npm-installed command)
+- **Python** 3.x (required by the migration tool)
+
+## Package layout (published tarball)
+
+- `package.json`
+- `bin/clawd-migrate.js` – runs `python -m clawd_migrate` with `PYTHONPATH=lib`
+- `lib/clawd_migrate/` – Python package (copied on prepublish from repo root)
+
+## Repo layout (development)
+
+- Python source stays at repo root (`__init__.py`, `config.py`, etc.).
+- `prepublishOnly` runs `scripts/copy-py.js`, which copies `.py` files and `Documentation/` into `lib/clawd_migrate/` so the npm pack includes the correct structure.
+
+## Files added
+
+| File | Purpose |
+|------|--------|
+| `package.json` | NPM package manifest, bin, files, prepublishOnly |
+| `bin/clawd-migrate.js` | Cross-platform bin: sets PYTHONPATH, runs Python module |
+| `scripts/copy-py.js` | Copies Python package into `lib/clawd_migrate/` for publish |
+| `README.md` | Install and usage for npm/GitHub |
+| `Documentation/NPM_PUBLISH.md` | This doc |
+
+## Publishing (manual)
+
+1. Bump version in `package.json` (and optionally in `__init__.py`).
+2. From repo root: `npm run prepublishOnly` (optional; runs automatically on publish).
+3. `npm publish` (requires npm login and publish rights).
+
+Scoped package (e.g. `@yourscope/clawd-migrate`): set `"name": "@yourscope/clawd-migrate"` in `package.json` and use `npm publish --access public` if the scope is unscoped by default.
+
+## Notes
+
+- The bin script uses `python3` on non-Windows and `python` on Windows; users must have Python on PATH.
+- Only `bin/` and `lib/` are included in the tarball (`files` in package.json).
+- Do not commit `lib/` if it’s generated; it’s created during prepublish and packed from there.

package/lib/clawd_migrate/Documentation/NPM_WALKTHROUGH.md

@@ -0,0 +1,130 @@
+# Step-by-step: Publish clawd-migrate to npm
+
+Follow these in order to publish this package to npm so anyone can run `npx clawd-migrate`.
+
+---
+
+## Step 1: Create an npm account (if you don’t have one)
+
+1. Go to [npmjs.com/signup](https://www.npmjs.com/signup).
+2. Sign up with email (or GitHub).
+3. Confirm your email if prompted.
+
+---
+
+## Step 2: Log in to npm from the terminal
+
+From any directory:
+
+```bash
+npm login
+```
+
+- **Username:** your npm username  
+- **Password:** your npm password  
+- **Email:** (your email, or one already on the account)  
+- **OTP:** if you have 2FA, enter the code from your app or email  
+
+You should see: `Logged in as YOUR_USERNAME on https://registry.npmjs.org/`.
+
+---
+
+## Step 3: (Optional) Set repository URL in package.json
+
+If this repo is on GitHub, add the URL so the npm page links to it. In `package.json`, set:
+
+```json
+"repository": {
+  "type": "git",
+  "url": "https://github.com/YOUR_USERNAME/clawd-migrate.git"
+}
+```
+
+Replace `YOUR_USERNAME` with your GitHub username. You can also set `"author": "Your Name <you@example.com>"` if you want.
+
+---
+
+## Step 4: Check the package name
+
+Open `package.json` and confirm:
+
+- **name:** `clawd-migrate` (must be unique on npm; if taken, use a scoped name like `@yourusername/clawd-migrate`).
+- **version:** e.g. `0.1.0` (you can leave as-is for first publish).
+
+If you use a scoped name (e.g. `@yourusername/clawd-migrate`), you’ll need `npm publish --access public` in Step 6.
+
+---
+
+## Step 5: Dry run (see what will be published)
+
+From the **clawd_migrate** folder (repo root):
+
+```bash
+cd c:\Users\Douglas\clawd\clawd_migrate
+npm pack --dry-run
+```
+
+This lists the files that would go in the tarball. You should see `bin/` and `lib/` (and package.json); no Python source at root (it’s copied into `lib/clawd_migrate/` by the prepublish script).
+
+Optional: create a real tarball and inspect it:
+
+```bash
+npm pack
+```
+
+That creates `clawd-migrate-0.1.0.tgz`. You can delete it after; it’s not needed for publish.
+
+---
+
+## Step 6: Publish
+
+From the **clawd_migrate** folder:
+
+```bash
+npm publish
+```
+
+- If the **name** is unscoped (`clawd-migrate`): that’s it.
+- If the **name** is scoped (e.g. `@yourusername/clawd-migrate`): run:
+
+  ```bash
+  npm publish --access public
+  ```
+
+You should see something like: `+ clawd-migrate@0.1.0` (or your scoped name).
+
+---
+
+## Step 7: Verify
+
+1. Open [npmjs.com/package/clawd-migrate](https://www.npmjs.com/package/clawd-migrate) (or your scoped package URL).
+2. Install and run:
+
+   ```bash
+   npx clawd-migrate discover
+   ```
+
+If that runs and shows JSON (or the interactive menu with no args), you’re done.
+
+---
+
+## Later: bump version and publish again
+
+1. Edit `package.json`: bump **version** (e.g. `0.1.0` → `0.1.1` or `0.2.0`). Optionally bump `__init__.py` `__version__` to match.
+2. From repo root:
+
+   ```bash
+   npm publish
+   ```
+
+---
+
+## Troubleshooting
+
+| Issue | What to do |
+|-------|------------|
+| `You must verify your email` | Verify the email in the link npm sent. |
+| `Package name already taken` | Change **name** in package.json (e.g. `clawd-migrate-tools`) or use a scoped name: `@yourusername/clawd-migrate` and `npm publish --access public`. |
+| `403 Forbidden` | You’re not logged in or don’t have permission; run `npm login` again. |
+| `prepublishOnly` fails | Run `node scripts/copy-py.js` from repo root; fix any errors (e.g. missing files). |
+| Users get “Python not found” | The package requires Python 3 on PATH; say so in README (already there). |

package/lib/clawd_migrate/Documentation/TESTS.md

@@ -0,0 +1,43 @@
+# Tests – Feature Tracking
+
+## Overview
+
+**clawd_migrate** has Python unit tests for discover, backup, and migrate. They use a temporary directory with a fake moltbot/clawdbot layout and assert the expected files and layout.
+
+## Status
+
+- **Added:** 2025-02-01
+- **Runner:** `unittest` (stdlib; no extra deps)
+
+## What is tested
+
+| Test | What it checks |
+|------|----------------|
+| `TestDiscover.test_discover_finds_memory_config_extra` | Discover returns memory (SOUL.md, USER.md, TOOLS.md), config, clawdbook, and extra (projects/) |
+| `TestBackup.test_backup_creates_dir_and_copies_files` | Backup dir exists; SOUL.md, USER.md, credentials.json, projects/readme.txt, _manifest.txt present |
+| `TestMigrate.test_migrate_creates_openclaw_layout` | Migration creates memory/, .config/openclaw/, .config/clawdbook/; copies memory and clawdbook; no errors; projects/ preserved |
+
+## How to run
+
+From repo root (the `clawd_migrate` directory):
+
+```bash
+# Via npm (sets PYTHONPATH to parent so package is found)
+npm test
+
+# Via Python (from parent of clawd_migrate so clawd_migrate is on path)
+cd .. && PYTHONPATH=. python -m unittest discover -s clawd_migrate/tests -p "test_*.py" -v
+
+# Or from repo root with PYTHONPATH to parent
+PYTHONPATH=.. python -m unittest discover -s tests -p "test_*.py" -v
+```
+
+## Files
+
+- `tests/__init__.py` – Marks tests package.
+- `tests/test_migrate.py` – Discover, backup, migrate tests; adds parent of repo root to `sys.path` so `clawd_migrate` is importable.
+- `scripts/run-tests.js` – Used by `npm test`; sets `PYTHONPATH` to parent dir and runs `python -m unittest discover`.
+
+## Bug fix in migrate
+
+In-place migration (output_root same as root) was copying "extra" files onto themselves, causing `shutil.copy2` to raise "same file". Migrate now skips copying when `src_path.resolve() == dest.resolve()`.

package/lib/clawd_migrate/__init__.py

@@ -0,0 +1,18 @@
+"""
+clawd_migrate - Migrate from moltbot or clawdbot to openclaw while preserving
+configuration, memory, and clawdbook (Moltbook) data. Works for any user's system.
+"""
+
+__version__ = "0.1.0"
+
+from .backup import create_backup
+from .discover import discover_source_assets, discover_clawdbot_assets
+from .migrate import run_migration
+
+__all__ = [
+    "create_backup",
+    "discover_source_assets",
+    "discover_clawdbot_assets",
+    "run_migration",
+    "__version__",
+]

package/lib/clawd_migrate/__main__.py

@@ -0,0 +1,101 @@
+"""
+CLI for clawd_migrate. Usage:
+  python -m clawd_migrate              # Interactive TUI (lobster + menu)
+  python -m clawd_migrate run          # Same as above
+  python -m clawd_migrate discover [--root PATH]
+  python -m clawd_migrate backup  [--root PATH] [--backup-dir PATH]
+  python -m clawd_migrate migrate [--root PATH] [--no-backup] [--output PATH]
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from . import create_backup, discover_source_assets, run_migration
+from . import __version__
+
+
+def cmd_discover(root: Path) -> int:
+    assets = discover_source_assets(root)
+    print(json.dumps(assets, indent=2))
+    return 0
+
+
+def cmd_backup(root: Path, backup_dir: Path) -> int:
+    path = create_backup(root=root, backup_dir=backup_dir)
+    print(f"Backup created: {path}")
+    return 0
+
+
+def cmd_migrate(root: Path, no_backup: bool, output: Path) -> int:
+    if no_backup:
+        print("Warning: --no-backup set; no backup will be created.", file=sys.stderr)
+    result = run_migration(root=root, backup_first=not no_backup, output_root=output or root)
+    if result["backup_path"]:
+        print(f"Backup: {result['backup_path']}")
+    print(f"Memory copied: {len(result['memory_copied'])} files")
+    print(f"Config copied: {len(result['config_copied'])} files")
+    print(f"Clawdbook (safe): {len(result['clawdbook_copied'])} files")
+    if result["errors"]:
+        print("Errors:", file=sys.stderr)
+        for e in result["errors"]:
+            print(f"  {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Migrate moltbot or clawdbot to openclaw; preserve config, memory, and clawdbook data."
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command", required=False)
+
+    # interactive TUI (default when no command)
+    p_run = sub.add_parser("run", help="Interactive terminal UI (lobster + guided menu)")
+    p_run.set_defaults(func=lambda a: _run_tui())
+
+    # discover
+    p_discover = sub.add_parser("discover", help="List clawdbot assets (config, memory, clawdbook)")
+    p_discover.add_argument("--root", type=Path, default=None, help="Source root (default: cwd)")
+    p_discover.set_defaults(func=lambda a: cmd_discover(Path(a.root or os.getcwd())))
+
+    # backup
+    p_backup = sub.add_parser("backup", help="Create timestamped backup (no migration)")
+    p_backup.add_argument("--root", type=Path, default=None, help="Clawdbot root (default: cwd)")
+    p_backup.add_argument("--backup-dir", type=Path, default=None, help="Backup parent dir (default: root/backups)")
+    p_backup.set_defaults(
+        func=lambda a: cmd_backup(
+            Path(a.root or os.getcwd()),
+            Path(a.backup_dir) if a.backup_dir else None,
+        )
+    )
+
+    # migrate
+    p_migrate = sub.add_parser("migrate", help="Migrate to openclaw (backup first unless --no-backup)")
+    p_migrate.add_argument("--root", type=Path, default=None, help="Source root (default: cwd)")
+    p_migrate.add_argument("--no-backup", action="store_true", help="Skip backup (not recommended)")
+    p_migrate.add_argument("--output", type=Path, default=None, help="Openclaw output root (default: root)")
+    p_migrate.set_defaults(
+        func=lambda a: cmd_migrate(
+            Path(a.root or os.getcwd()),
+            a.no_backup,
+            Path(a.output) if a.output else None,
+        )
+    )
+
+    args = parser.parse_args()
+    if args.command is None:
+        return _run_tui()
+    return args.func(args)
+
+
+def _run_tui() -> int:
+    from .tui import run_tui
+    return run_tui()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/lib/clawd_migrate/backup.py

@@ -0,0 +1,66 @@
+"""
+Create a timestamped backup of source bot (moltbot/clawdbot) config, memory, and clawdbook data.
+Never overwrite; always safe. Works for any user's system.
+"""
+
+import os
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional
+
+from .config import DEFAULT_BACKUP_DIR, BACKUP_PREFIX
+from .discover import discover_source_assets
+
+
+def create_backup(
+    root: Optional[Path] = None,
+    backup_dir: Optional[Path] = None,
+    asset_paths: Optional[dict] = None,
+) -> Path:
+    """
+    Copy all discovered (or provided) assets into a timestamped backup directory.
+    Returns the path to the backup directory.
+    """
+    root = Path(root or os.getcwd()).resolve()
+    backup_base = Path(backup_dir or root / DEFAULT_BACKUP_DIR)
+    backup_base.mkdir(parents=True, exist_ok=True)
+
+    stamp = datetime.utcnow().strftime("%Y%m%d_%H%M%S")
+    backup_path = backup_base / f"{BACKUP_PREFIX}{stamp}"
+    backup_path.mkdir(parents=True, exist_ok=True)
+
+    assets = asset_paths or discover_source_assets(root)
+    all_paths: List[str] = (
+        assets.get("memory", [])
+        + assets.get("config", [])
+        + assets.get("clawdbook", [])
+        + assets.get("extra", [])
+    )
+    all_paths = list(dict.fromkeys(all_paths))
+
+    for src in all_paths:
+        src_path = Path(src)
+        if not src_path.is_file():
+            continue
+        try:
+            rel = src_path.relative_to(root)
+        except ValueError:
+            rel = src_path.name
+        dest = backup_path / rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src_path, dest)
+
+    # Also write a manifest so we know what was backed up
+    manifest = backup_path / "_manifest.txt"
+    with open(manifest, "w", encoding="utf-8") as f:
+        f.write(f"Backup at {stamp}\nRoot: {root}\n\n")
+        for k, v in assets.items():
+            if isinstance(v, list):
+                f.write(f"{k}:\n")
+                for p in v:
+                    f.write(f"  {p}\n")
+            else:
+                f.write(f"{k}: {v}\n")
+
+    return backup_path

package/lib/clawd_migrate/config.py

@@ -0,0 +1,48 @@
+"""
+Migration configuration: paths and patterns for source bots (moltbot / clawdbot)
+vs openclaw target layout. Works for any user's system; no machine-specific paths.
+"""
+
+# --- Source layouts (moltbot and clawdbot) ---
+# Memory/identity files that may exist in either system
+SOURCE_MEMORY_FILES = [
+    "SOUL.md",      # Who the bot is
+    "USER.md",      # Who the human is
+    "TOOLS.md",     # Local notes, device names, env-specific
+    "IDENTITY.md",  # Bot identity (if present)
+    "AGENTS.md",    # Agent instructions (if present)
+    "MEMORY.md",    # Long-term memory (if present)
+]
+
+# Config paths: union of moltbot and clawdbot locations (credentials, API keys)
+SOURCE_CONFIG_PATHS = [
+    # Clawdbot
+    ".config/moltbook/credentials.json",
+    ".config/moltbook/",
+    # Moltbot
+    ".config/moltbot/credentials.json",
+    ".config/moltbot/",
+    ".config/moltbook/",  # Moltbot may also use moltbook for Clawdbook
+]
+
+# Deduplicate while preserving order
+SOURCE_CONFIG_PATHS = list(dict.fromkeys(SOURCE_CONFIG_PATHS))
+
+# Extra paths: project docs and scripts (both systems)
+SOURCE_EXTRA_DIRS = [
+    "projects/",
+]
+
+# --- Openclaw (target) layout ---
+OPENCLAW_MEMORY_DIR = "memory"
+OPENCLAW_CONFIG_DIR = ".config/openclaw"
+OPENCLAW_CLAWDBOOK_DIR = ".config/clawdbook"
+
+# Backup (generic; no product name in prefix)
+DEFAULT_BACKUP_DIR = "backups"
+BACKUP_PREFIX = "openclaw_migrate_backup_"
+
+# Backward compatibility: same names used by discover
+CLAWDBOT_MEMORY_FILES = SOURCE_MEMORY_FILES
+CLAWDBOT_CONFIG_PATHS = SOURCE_CONFIG_PATHS
+CLAWDBOT_EXTRA_PATTERNS = SOURCE_EXTRA_DIRS

package/lib/clawd_migrate/discover.py

@@ -0,0 +1,69 @@
+"""
+Discover source bot assets (moltbot or clawdbot): config, memory, and clawdbook data.
+Works on any user's system; no machine-specific paths.
+"""
+
+import os
+from pathlib import Path
+from typing import Optional
+
+from .config import (
+    SOURCE_CONFIG_PATHS,
+    SOURCE_MEMORY_FILES,
+    SOURCE_EXTRA_DIRS,
+)
+
+
+def discover_source_assets(root: Optional[Path] = None) -> dict:
+    """
+    Scan root (or cwd) for moltbot/clawdbot config, memory, and clawdbook data.
+    Returns paths that exist, grouped by type. Safe for any user's system.
+    """
+    root = Path(root or os.getcwd()).resolve()
+    out = {
+        "root": str(root),
+        "memory": [],
+        "config": [],
+        "clawdbook": [],
+        "extra": [],
+    }
+
+    # Memory files
+    for name in SOURCE_MEMORY_FILES:
+        p = root / name
+        if p.is_file():
+            out["memory"].append(str(p))
+
+    # Config paths (moltbook/clawdbook = credentials, API keys)
+    for rel in SOURCE_CONFIG_PATHS:
+        p = root / rel
+        if p.exists():
+            if p.is_dir():
+                for f in p.rglob("*"):
+                    if f.is_file():
+                        out["config"].append(str(f))
+                if str(p) not in [os.path.dirname(c) for c in out["config"]]:
+                    out["clawdbook"].append(str(p))
+            else:
+                out["config"].append(str(p))
+                if "moltbook" in rel.lower() or "moltbot" in rel.lower() or "credentials" in rel.lower():
+                    out["clawdbook"].append(str(p))
+
+    out["config"] = list(dict.fromkeys(out["config"]))
+
+    # Extra dirs (e.g. projects/)
+    for rel in SOURCE_EXTRA_DIRS:
+        rel_clean = rel.rstrip("/")
+        extra_path = root / rel_clean
+        if extra_path.is_dir():
+            for f in extra_path.rglob("*"):
+                if f.is_file():
+                    out["extra"].append(str(f))
+
+    out["clawdbook"] = list(dict.fromkeys(out["clawdbook"]))
+    return out
+
+
+def discover_clawdbot_assets(root: Optional[Path] = None) -> dict:
+    """Alias for discover_source_assets (backward compatibility)."""
+    return discover_source_assets(root)

package/lib/clawd_migrate/migrate.py

@@ -0,0 +1,106 @@
+"""
+Migrate moltbot or clawdbot assets to openclaw layout.
+Always runs after a backup; never mutates originals without backup.
+Works for any user's system.
+"""
+
+import os
+import shutil
+from pathlib import Path
+from typing import Optional
+
+from .config import (
+    OPENCLAW_MEMORY_DIR,
+    OPENCLAW_CONFIG_DIR,
+    OPENCLAW_CLAWDBOOK_DIR,
+)
+from .discover import discover_source_assets
+from .backup import create_backup
+
+
+def run_migration(
+    root: Optional[Path] = None,
+    backup_first: bool = True,
+    output_root: Optional[Path] = None,
+) -> dict:
+    """
+    Migrate moltbot/clawdbot config, memory, and clawdbook data to openclaw structure.
+    If backup_first is True (default), creates a timestamped backup before any copy.
+    output_root defaults to root (in-place migration into new dirs).
+    Returns summary: backup_path, memory_copied, config_copied, clawdbook_copied.
+    """
+    root = Path(root or os.getcwd()).resolve()
+    out_root = Path(output_root or root).resolve()
+    assets = discover_source_assets(root)
+    result = {
+        "backup_path": None,
+        "memory_copied": [],
+        "config_copied": [],
+        "clawdbook_copied": [],
+        "errors": [],
+    }
+
+    if backup_first:
+        result["backup_path"] = str(create_backup(root=root, asset_paths=assets))
+
+    memory_dir = out_root / OPENCLAW_MEMORY_DIR
+    config_dir = out_root / OPENCLAW_CONFIG_DIR
+    clawdbook_dir = out_root / OPENCLAW_CLAWDBOOK_DIR
+    memory_dir.mkdir(parents=True, exist_ok=True)
+    config_dir.mkdir(parents=True, exist_ok=True)
+    clawdbook_dir.mkdir(parents=True, exist_ok=True)
+
+    # Copy memory files into openclaw memory/
+    for src in assets.get("memory", []):
+        src_path = Path(src)
+        if src_path.is_file():
+            dest = memory_dir / src_path.name
+            try:
+                shutil.copy2(src_path, dest)
+                result["memory_copied"].append(str(dest))
+            except Exception as e:
+                result["errors"].append(f"memory {src}: {e}")
+
+    # Clawdbook/Moltbook data: keep separate and safe (credentials, API keys)
+    def is_clawdbook(path_str: str) -> bool:
+        p = path_str.lower()
+        return "moltbook" in p or "clawdbook" in p or "moltbot" in p
+
+    for src in assets.get("config", []):
+        src_path = Path(src)
+        if not src_path.is_file():
+            continue
+        if is_clawdbook(src):
+            dest = clawdbook_dir / src_path.name
+            try:
+                shutil.copy2(src_path, dest)
+                result["clawdbook_copied"].append(str(dest))
+            except Exception as e:
+                result["errors"].append(f"clawdbook {src}: {e}")
+        else:
+            dest = config_dir / src_path.name
+            try:
+                shutil.copy2(src_path, dest)
+                result["config_copied"].append(str(dest))
+            except Exception as e:
+                result["errors"].append(f"config {src}: {e}")
+
+    # Extra (e.g. projects/) -> openclaw projects under output root (preserve layout)
+    for src in assets.get("extra", []):
+        src_path = Path(src)
+        if src_path.is_file():
+            try:
+                rel = src_path.relative_to(root)
+            except ValueError:
+                rel = Path("projects") / src_path.name
+            dest = out_root / rel
+            if src_path.resolve() == dest.resolve():
+                continue  # in-place: same file, skip copy
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            try:
+                shutil.copy2(src_path, dest)
+                result["config_copied"].append(str(dest))
+            except Exception as e:
+                result["errors"].append(f"extra {src}: {e}")
+
+    return result

package/lib/clawd_migrate/tui.py

@@ -0,0 +1,173 @@
+"""
+Interactive terminal UI for clawd_migrate.
+Shows a lobster on load and guides users through discover -> backup -> migrate.
+Works for moltbot or clawdbot on any user's system.
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+from . import create_backup, discover_source_assets, run_migration
+
+# ANSI codes (work in Windows Terminal, PowerShell 7+, and Unix)
+RESET = "\033[0m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+CYAN = "\033[36m"
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+MAGENTA = "\033[35m"
+RED = "\033[31m"
+
+
+def style(s: str, *codes: str) -> str:
+    return "".join(codes) + s + RESET
+
+
+# ASCII lobster (body in RED, eyes in BOLD, "CLAWD MIGRATE" in CYAN)
+LOBSTER_LINES = [
+    "",
+    "        \\    ___       ",
+    "         \\  /   \\      ____  _      _    ____",
+    "          \\| o o |    / ___|| | __ _| | _|  _ \\ _ __ ___   ___",
+    "           \\___/     \\___ \\| |/ _` | |/ / | | | '_ ` _ \\ / _ \\",
+    "          /     \\     ___) | | (_| |   <  | |_| | | | | | | (_) |",
+    "         (_______)   |____/|_|\\__,_|_|\\_\\ |____/|_| |_| |_|\\___/",
+    "",
+]
+
+
+def print_banner() -> None:
+    """Print the lobster ASCII art and welcome message."""
+    print()
+    for line in LOBSTER_LINES:
+        if not line.strip():
+            print(line)
+            continue
+        # Split lobster (left) from "CLAWD MIGRATE" text (right)
+        sep = " ____"
+        if sep in line and ("/   \\" in line or "|" in line):
+            left, right = line.split(sep, 1)
+            print(style(left, RED) + style(sep + right, CYAN))
+        elif "o o" in line:
+            left, right = line.split("o o", 1)
+            print(style(left, RED) + style("o", BOLD) + " " + style("o", BOLD) + style(right, RED))
+        else:
+            # Lobster-only line
+            print(style(line, RED))
+    print(style("  Migrate from moltbot or clawdbot to openclaw safely  ", BOLD, CYAN))
+    print(style("  Discover -> Backup -> Migrate  ", DIM))
+    print()
+
+
+def get_root() -> Path:
+    """Prompt for root path or use cwd."""
+    cwd = Path(os.getcwd()).resolve()
+    print(style(f"  Working directory: {cwd}", DIM))
+    raw = input(style("  Use this directory? [Y/n] or enter a path: ", YELLOW)).strip()
+    if not raw or raw.lower() == "y" or raw.lower() == "yes":
+        return cwd
+    p = Path(raw).expanduser().resolve()
+    if not p.is_dir():
+        print(style(f"  Not a directory: {p}", RED))
+        return cwd
+    return p
+
+
+def do_discover(root: Path) -> None:
+    """Run discover and print results in a readable way."""
+    print(style("\n  Discovering assets (moltbot / clawdbot)...\n", CYAN))
+    assets = discover_source_assets(root)
+    print(style("  Root: ", DIM) + assets["root"])
+    for key in ("memory", "config", "clawdbook", "extra"):
+        items = assets.get(key, [])
+        label = key.capitalize()
+        print(style(f"  {label}: {len(items)} item(s)", GREEN if items else DIM))
+        for path in items[:10]:
+            print(style("    ", DIM) + path)
+        if len(items) > 10:
+            print(style(f"    ... and {len(items) - 10} more", DIM))
+    print()
+    if input(style("  Show full JSON? [y/N]: ", YELLOW)).strip().lower() == "y":
+        print(json.dumps(assets, indent=2))
+    print()
+
+
+def do_backup(root: Path) -> None:
+    """Create a timestamped backup."""
+    print(style("\n  Creating backup...\n", CYAN))
+    try:
+        path = create_backup(root=root)
+        print(style(f"  Backup created: {path}", GREEN))
+    except Exception as e:
+        print(style(f"  Error: {e}", RED))
+    print()
+
+
+def do_migrate(root: Path, no_backup: bool) -> None:
+    """Run migration (optionally with backup first)."""
+    if not no_backup:
+        print(style("  Migration will create a backup first.", DIM))
+    else:
+        print(style("  Skipping backup (--no-backup).", YELLOW))
+    confirm = input(style("  Proceed with migration? [y/N]: ", YELLOW)).strip().lower()
+    if confirm != "y" and confirm != "yes":
+        print(style("  Cancelled.", DIM))
+        return
+    print(style("\n  Migrating...\n", CYAN))
+    result = run_migration(root=root, backup_first=not no_backup, output_root=None)
+    if result["backup_path"]:
+        print(style(f"  Backup: {result['backup_path']}", GREEN))
+    print(style(f"  Memory copied: {len(result['memory_copied'])} files", GREEN))
+    print(style(f"  Config copied: {len(result['config_copied'])} files", GREEN))
+    print(style(f"  Clawdbook (safe): {len(result['clawdbook_copied'])} files", GREEN))
+    if result["errors"]:
+        print(style("  Errors:", RED))
+        for e in result["errors"]:
+            print(style(f"    {e}", RED))
+    else:
+        print(style("\n  Migration complete.", BOLD, GREEN))
+    print()
+
+
+def main_menu(root: Path) -> bool:
+    """Show main menu; return False to exit."""
+    print(style("  [1] Discover assets (config, memory, clawdbook)", CYAN))
+    print(style("  [2] Create backup only (no migration)", CYAN))
+    print(style("  [3] Run full migration (backup first, then migrate)", CYAN))
+    print(style("  [4] Migrate without backup (not recommended)", YELLOW))
+    print(style("  [5] Change working directory", DIM))
+    print(style("  [q] Quit", DIM))
+    print()
+    choice = input(style("  Choose [1-5 / q]: ", BOLD, MAGENTA)).strip().lower()
+    if choice == "q" or choice == "quit":
+        return False
+    if choice == "1":
+        do_discover(root)
+        return True
+    if choice == "2":
+        do_backup(root)
+        return True
+    if choice == "3":
+        do_migrate(root, no_backup=False)
+        return True
+    if choice == "4":
+        do_migrate(root, no_backup=True)
+        return True
+    if choice == "5":
+        new_root = get_root()
+        return main_menu(new_root)
+    print(style("  Unknown option.", RED))
+    return True
+
+
+def run_tui() -> int:
+    """Entry point for the interactive TUI. Returns exit code."""
+    print_banner()
+    root = get_root()
+    while main_menu(root):
+        pass
+    print(style("\n  Bye!\n", DIM))
+    return 0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "clawd-migrate",
+  "version": "0.1.0",
+  "description": "Migrate from moltbot or clawdbot to openclaw. Preserves config, memory, and clawdbook (Moltbook) data.",
+  "author": "",
+  "license": "MIT",
+  "bin": {
+    "clawd-migrate": "bin/clawd-migrate.js"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "scripts": {
+    "prepublishOnly": "node scripts/copy-py.js",
+    "test": "node scripts/run-tests.js"
+  },
+  "keywords": [
+    "openclaw",
+    "moltbot",
+    "clawdbot",
+    "migration",
+    "clawdbook",
+    "moltbook"
+  ],
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}