max-context-share 0.1.0__tar.gz

max_context_share-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.venv/
+*.whl
+
+# uv
+uv.lock
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Archives (keep example/)
+*.tgz
+*.log

max_context_share-0.1.0/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: max-context-share
+Version: 0.1.0
+Summary: Export/import OpenClaw skills, workspace context files, and config fragments as portable .tar.gz bundles
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: aiofiles>=23.0
+Requires-Dist: click>=8.0
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# max-context-share
+
+CLI tool to export and import OpenClaw skills, workspace context files, and config fragments as a portable `.tar.gz` bundle.
+
+> **Note:** This is the Python rewrite of the original TypeScript version. Bundles are **fully compatible** between both versions.
+
+## Running the CLI
+
+### Option A: via pip / uv (recommended)
+
+```bash
+# Install with pip
+pip install max-context-share
+
+# Or install with uv
+uv pip install max-context-share
+
+# Run
+max-ctx export
+max-ctx import ./sample-context.tar.gz
+```
+
+### Option B: run directly from source
+
+Clone or download this repo, then:
+
+```bash
+# 1. Enter the project directory
+cd max-context-share
+
+# 2. Create venv and install with uv
+uv venv .venv --python=3.10
+uv sync
+
+# 3. Run via uv
+uv run max-ctx export
+uv run max-ctx import ./sample-context.tar.gz
+
+# Or activate the venv and run directly
+source .venv/bin/activate
+max-ctx export --dry-run
+```
+
+---
+
+## Usage
+
+### Export
+
+Package your local OpenClaw skills, workspace files, and config fragment into a shareable archive:
+
+```bash
+# Export everything (all skills + workspace files + config)
+max-ctx export
+
+# Specify output path
+max-ctx export --output /tmp/my-context.tar.gz
+
+# Export specific skills only
+max-ctx export --skills github,weather,habit-reminder
+
+# Exclude workspace files or config fragment
+max-ctx export --no-workspace
+max-ctx export --no-config-fragment
+
+# Preview what would be exported
+max-ctx export --dry-run
+
+# JSON output (useful for scripting)
+max-ctx export --dry-run --json
+```
+
+### Import
+
+Import an archive into your local OpenClaw installation:
+
+```bash
+# Import with merge strategy (default: skip existing)
+max-ctx import /tmp/my-context.tar.gz
+
+# Overwrite existing skills and workspace files
+max-ctx import /tmp/my-context.tar.gz --overwrite
+
+# Import only skills, skip workspace files
+max-ctx import /tmp/my-context.tar.gz --no-workspace
+
+# Preview what would be imported
+max-ctx import /tmp/my-context.tar.gz --dry-run
+```
+
+> **Note:** The config fragment is **never written automatically**. On import, its contents are printed so you can review and apply settings manually via `openclaw config set ...`.
+
+---
+
+## Bundle Format
+
+The generated `.tar.gz` contains:
+
+```
+<timestamp>-openclaw-context/
+  manifest.json              # Metadata: schema version, skills list, etc.
+  skills/
+    bundled/                 # Skills shipped with openclaw
+      <slug>/
+        SKILL.md
+        ...
+    managed/                 # Installed via `openclaw skills install`
+      <slug>/
+    personal-agents/         # ~/.agents/skills/
+      <slug>/
+    project-agents/          # <workspace>/.agents/skills/
+      <slug>/
+    workspace/               # <workspace>/skills/
+      <slug>/
+  workspace/
+    AGENTS.md
+    SOUL.md
+    TOOLS.md
+    IDENTITY.md
+    USER.md
+    HEARTBEAT.md
+    BOOTSTRAP.md
+    MEMORY.md
+  config-fragment.json       # Safe config subset (no secrets)
+```
+
+### Config Fragment
+
+The config fragment only includes safe, non-secret fields from `openclaw.json`:
+
+- `agents.defaults` — model, thinking preferences
+- `agents.list[].skills` — per-agent skill allowlists
+- `skills.allowBundled` / `skills.limits`
+
+Credentials, tokens, OAuth settings, gateway config, and any field containing `secret`, `token`, `key`, `password`, `auth`, or `credential` are **never exported**.
+
+---
+
+## Skill Sources
+
+OpenClaw loads skills from multiple locations. `max-ctx export` scans all of them:
+
+| Source | Path | Description |
+|--------|------|-------------|
+| `bundled` | `<openclaw-pkg>/skills/` | Shipped with openclaw (auto-detected via `which openclaw`) |
+| `managed` | `~/.openclaw/skills/` | Installed via `openclaw skills install` |
+| `personal-agents` | `~/.agents/skills/` | Personal skills shared across all workspaces |
+| `project-agents` | `<workspace>/.agents/skills/` | Project-local skills (can be committed to git) |
+| `workspace` | `<workspace>/skills/` | Workspace-local skills |
+
+Precedence on conflict (same slug): `workspace` > `project-agents` > `personal-agents` > `managed` > `bundled`.
+
+---
+
+## Merge Strategies
+
+| Mode | Skills | Workspace files |
+|------|--------|-----------------|
+| `--merge` (default) | Skip existing slugs, print warning | Skip existing files, print notice |
+| `--overwrite` | Replace existing slugs entirely | Overwrite existing files |
+
+---
+
+## Paths
+
+Paths are resolved from environment variables (same conventions as OpenClaw core):
+
+| Path | Default | Override |
+|------|---------|---------|
+| State directory | `~/.openclaw/` | `OPENCLAW_STATE_DIR` |
+| Workspace | `~/.openclaw/workspace/` | `OPENCLAW_PROFILE` |
+| Managed skills | `~/.openclaw/skills/` | — |
+| Config file | `~/.openclaw/openclaw.json` | — |
+| Bundled skills | auto-detected from `openclaw` binary | `OPENCLAW_BUNDLED_SKILLS_DIR` |
+
+Profile support: if `OPENCLAW_PROFILE=prod`, workspace resolves to `~/.openclaw/workspace-prod/`.
+
+---
+
+## Python API (Sync + Async)
+
+You can also use `max-context-share` as a library:
+
+```python
+from max_context_share.export_bundle import (
+    ExportOptions, run_export, async_run_export,
+)
+from max_context_share.import_bundle import (
+    ImportOptions, run_import, async_run_import,
+)
+
+# Sync
+result = run_export(ExportOptions(dry_run=True))
+print(result.skills)
+
+# Async
+import asyncio
+result = asyncio.run(
+    async_run_export(ExportOptions(dry_run=True))
+)
+```
+
+---
+
+## Example
+
+An example bundle is included in the `example/` directory:
+
+```bash
+# Inspect the example bundle
+tar tf example/sample-context.tar.gz
+
+# Do a dry-run import to see what would change
+max-ctx import example/sample-context.tar.gz --dry-run
+```
+
+---
+
+## Development
+
+```bash
+# Setup
+uv venv .venv --python=3.10
+uv sync
+
+# Lint
+uv run ruff check src/ tests/
+
+# Test (60 tests across 6 modules)
+uv run pytest -v
+
+# Run from source
+uv run max-ctx --help
+uv run max-ctx export --dry-run
+```
+
+---
+
+## Cross-Compatibility
+
+Bundles created by the Python version are **fully compatible** with the TypeScript version and vice versa:
+
+- `manifest.json` uses identical camelCase keys (`schemaVersion`, `createdAt`, `workspaceFiles`, `hasConfigFragment`)
+- Archive directory layout is identical
+- Same 8 workspace files, same skill source precedence
+- Same config fragment safe-field extraction

max_context_share-0.1.0/README.md

@@ -0,0 +1,246 @@
+# max-context-share
+
+CLI tool to export and import OpenClaw skills, workspace context files, and config fragments as a portable `.tar.gz` bundle.
+
+> **Note:** This is the Python rewrite of the original TypeScript version. Bundles are **fully compatible** between both versions.
+
+## Running the CLI
+
+### Option A: via pip / uv (recommended)
+
+```bash
+# Install with pip
+pip install max-context-share
+
+# Or install with uv
+uv pip install max-context-share
+
+# Run
+max-ctx export
+max-ctx import ./sample-context.tar.gz
+```
+
+### Option B: run directly from source
+
+Clone or download this repo, then:
+
+```bash
+# 1. Enter the project directory
+cd max-context-share
+
+# 2. Create venv and install with uv
+uv venv .venv --python=3.10
+uv sync
+
+# 3. Run via uv
+uv run max-ctx export
+uv run max-ctx import ./sample-context.tar.gz
+
+# Or activate the venv and run directly
+source .venv/bin/activate
+max-ctx export --dry-run
+```
+
+---
+
+## Usage
+
+### Export
+
+Package your local OpenClaw skills, workspace files, and config fragment into a shareable archive:
+
+```bash
+# Export everything (all skills + workspace files + config)
+max-ctx export
+
+# Specify output path
+max-ctx export --output /tmp/my-context.tar.gz
+
+# Export specific skills only
+max-ctx export --skills github,weather,habit-reminder
+
+# Exclude workspace files or config fragment
+max-ctx export --no-workspace
+max-ctx export --no-config-fragment
+
+# Preview what would be exported
+max-ctx export --dry-run
+
+# JSON output (useful for scripting)
+max-ctx export --dry-run --json
+```
+
+### Import
+
+Import an archive into your local OpenClaw installation:
+
+```bash
+# Import with merge strategy (default: skip existing)
+max-ctx import /tmp/my-context.tar.gz
+
+# Overwrite existing skills and workspace files
+max-ctx import /tmp/my-context.tar.gz --overwrite
+
+# Import only skills, skip workspace files
+max-ctx import /tmp/my-context.tar.gz --no-workspace
+
+# Preview what would be imported
+max-ctx import /tmp/my-context.tar.gz --dry-run
+```
+
+> **Note:** The config fragment is **never written automatically**. On import, its contents are printed so you can review and apply settings manually via `openclaw config set ...`.
+
+---
+
+## Bundle Format
+
+The generated `.tar.gz` contains:
+
+```
+<timestamp>-openclaw-context/
+  manifest.json              # Metadata: schema version, skills list, etc.
+  skills/
+    bundled/                 # Skills shipped with openclaw
+      <slug>/
+        SKILL.md
+        ...
+    managed/                 # Installed via `openclaw skills install`
+      <slug>/
+    personal-agents/         # ~/.agents/skills/
+      <slug>/
+    project-agents/          # <workspace>/.agents/skills/
+      <slug>/
+    workspace/               # <workspace>/skills/
+      <slug>/
+  workspace/
+    AGENTS.md
+    SOUL.md
+    TOOLS.md
+    IDENTITY.md
+    USER.md
+    HEARTBEAT.md
+    BOOTSTRAP.md
+    MEMORY.md
+  config-fragment.json       # Safe config subset (no secrets)
+```
+
+### Config Fragment
+
+The config fragment only includes safe, non-secret fields from `openclaw.json`:
+
+- `agents.defaults` — model, thinking preferences
+- `agents.list[].skills` — per-agent skill allowlists
+- `skills.allowBundled` / `skills.limits`
+
+Credentials, tokens, OAuth settings, gateway config, and any field containing `secret`, `token`, `key`, `password`, `auth`, or `credential` are **never exported**.
+
+---
+
+## Skill Sources
+
+OpenClaw loads skills from multiple locations. `max-ctx export` scans all of them:
+
+| Source | Path | Description |
+|--------|------|-------------|
+| `bundled` | `<openclaw-pkg>/skills/` | Shipped with openclaw (auto-detected via `which openclaw`) |
+| `managed` | `~/.openclaw/skills/` | Installed via `openclaw skills install` |
+| `personal-agents` | `~/.agents/skills/` | Personal skills shared across all workspaces |
+| `project-agents` | `<workspace>/.agents/skills/` | Project-local skills (can be committed to git) |
+| `workspace` | `<workspace>/skills/` | Workspace-local skills |
+
+Precedence on conflict (same slug): `workspace` > `project-agents` > `personal-agents` > `managed` > `bundled`.
+
+---
+
+## Merge Strategies
+
+| Mode | Skills | Workspace files |
+|------|--------|-----------------|
+| `--merge` (default) | Skip existing slugs, print warning | Skip existing files, print notice |
+| `--overwrite` | Replace existing slugs entirely | Overwrite existing files |
+
+---
+
+## Paths
+
+Paths are resolved from environment variables (same conventions as OpenClaw core):
+
+| Path | Default | Override |
+|------|---------|---------|
+| State directory | `~/.openclaw/` | `OPENCLAW_STATE_DIR` |
+| Workspace | `~/.openclaw/workspace/` | `OPENCLAW_PROFILE` |
+| Managed skills | `~/.openclaw/skills/` | — |
+| Config file | `~/.openclaw/openclaw.json` | — |
+| Bundled skills | auto-detected from `openclaw` binary | `OPENCLAW_BUNDLED_SKILLS_DIR` |
+
+Profile support: if `OPENCLAW_PROFILE=prod`, workspace resolves to `~/.openclaw/workspace-prod/`.
+
+---
+
+## Python API (Sync + Async)
+
+You can also use `max-context-share` as a library:
+
+```python
+from max_context_share.export_bundle import (
+    ExportOptions, run_export, async_run_export,
+)
+from max_context_share.import_bundle import (
+    ImportOptions, run_import, async_run_import,
+)
+
+# Sync
+result = run_export(ExportOptions(dry_run=True))
+print(result.skills)
+
+# Async
+import asyncio
+result = asyncio.run(
+    async_run_export(ExportOptions(dry_run=True))
+)
+```
+
+---
+
+## Example
+
+An example bundle is included in the `example/` directory:
+
+```bash
+# Inspect the example bundle
+tar tf example/sample-context.tar.gz
+
+# Do a dry-run import to see what would change
+max-ctx import example/sample-context.tar.gz --dry-run
+```
+
+---
+
+## Development
+
+```bash
+# Setup
+uv venv .venv --python=3.10
+uv sync
+
+# Lint
+uv run ruff check src/ tests/
+
+# Test (60 tests across 6 modules)
+uv run pytest -v
+
+# Run from source
+uv run max-ctx --help
+uv run max-ctx export --dry-run
+```
+
+---
+
+## Cross-Compatibility
+
+Bundles created by the Python version are **fully compatible** with the TypeScript version and vice versa:
+
+- `manifest.json` uses identical camelCase keys (`schemaVersion`, `createdAt`, `workspaceFiles`, `hasConfigFragment`)
+- Archive directory layout is identical
+- Same 8 workspace files, same skill source precedence
+- Same config fragment safe-field extraction