npm package: @launchthatbot/convex-plugin
Description: OpenClaw plugin package for deterministic Convex bootstrap and migration workflows.
Latest version: 0.1.1

# @launchthatbot/convex-plugin

OpenClaw plugin for full Convex lifecycle, sync, and storage workflows.

This package is intentionally separate from `@launchthatbot/convex-backend`:

- `@launchthatbot/convex-backend` remains the skill/instruction package.
- `@launchthatbot/convex-plugin` provides lifecycle, provisioning, sync orchestration, storage profile controls, and migration diagnostics.

## What this plugin includes

- `openclaw.plugin.json` manifest with plugin id and config schema.
- TypeScript plugin entrypoint (`src/index.ts`).
- Typed plugin API via `openclaw/plugin-sdk`.
- Lifecycle + sync tool:
  - `convex_connection_lifecycle`
    - `connect_begin`
    - `connect_status`
    - `connect_disconnect`
    - `provision_run`
    - `provision_status`
    - `health_check`
    - `sync_backfill`
- Tool:
  - `convex_project_scan` - structured scan with `scan` (`env | logic | cron-memory | all`) and optional `rootPath`.
- Slash commands:
  - `/convex-connect-begin [--scope project|team] [--server <id>]`
  - `/convex-connect-status [--connection <id>]`
  - `/convex-connect-disconnect [--connection <id>]`
  - `/convex-provision-run [--connection <id>] [--server <id>]`
  - `/convex-provision-status [--connection <id>]`
  - `/convex-health-check [--connection <id>]`
  - `/convex-sync-backfill [--connection <id>] [--domains memory,dailyLogs,agentState,events] [--window-days 30]`
  - `/convex-migration-mode` - report migration policy.
  - `/convex-env-diff [rootPath]` - compare local `.env*` keys vs Convex env keys (excluding `CONVEX_DEPLOY_KEY` and `CONVEX_DEPLOYMENT`).
  - `/convex-unmigrated-logic [rootPath]` - find local logic candidates likely not yet migrated into Convex.
  - `/convex-cron-memory-scan [rootPath]` - scan cron-like code and memory/daily-log files that could move to Convex.

## Install (OpenClaw)

```bash
openclaw plugins install @launchthatbot/convex-plugin
```

Then enable/configure under `plugins.entries.launchthatbot-convex` in your OpenClaw config.

## Config

`openclaw.plugin.json` supports:

- `launchthatbotApiBaseUrl`
- `workspaceId`
- `instanceName`
- `deploymentMode`: `external | managed`
- `managed.serverId`
- `connection.connectionId`
- `connection.scope`: `project | team`
- `sync.enabledDomains`: subset of `memory`, `dailyLogs`, `agentState`, `events`
- `sync.batchSize`
- `sync.backfillWindowDays`
- `sync.maxRetryAttempts`
- `storage.profile`: `local-only | convex-managed | convex-r2-offload`
- `storage.r2.enabled`
- `storage.r2.credentialRef`
- `features.enableLifecycle`
- `features.enableBackfill`
- `features.enableR2Offload`
- `defaultMigrationMode`: `"one-by-one"` or `"blanket"`
- `requireExplicitCleanupApproval`: `true|false`

## Development

```bash
pnpm --filter @launchthatbot/convex-plugin build
pnpm --filter @launchthatbot/convex-plugin test
```

## Rollout plan

Use staged feature-flag rollout to reduce risk:

1. Enable `features.enableLifecycle` only.
2. Enable `features.enableBackfill` and validate sync state/receipts/backfill jobs.
3. Enable `features.enableR2Offload` with `storage.profile=convex-r2-offload` on pilot tenants.
4. Monitor health via `convex-health-check` and keep migration scan commands active during rollout:
   - `/convex-env-diff`
   - `/convex-unmigrated-logic`
   - `/convex-cron-memory-scan`