@cwe-platform/plugin-cli

cwe-plugin — the CasinoWebEngine plugin developer CLI. One tool that carries you from create → login → env → dev (hot reload + live logs) → lifecycle testing → publish.

The golden path

pnpm create cwe-plugin my-cashback         # scaffold: manifest, handlers, tests, config
cd my-cashback && pnpm install

pnpm dev                                   # = cwe-plugin dev
#  → first contact with the scaffold's preset `local` environment: the handshake verifies
#    class=local + devHarness=true and pins its fingerprint  → green banner
#  → doctor passes → sandbox tenant resolved → plugin installed+enabled (prompted)
#  → esbuild watch starts, bundle hot-loaded, log stream attached
#  → edit src/handlers/routes.ts, save → rebuilt + hot-reloaded in <2s, logs streaming live

# in the dev session (keyboard):  i install · e enable · c configure · x disable · u uninstall
#                                 r reload · d doctor · l clear · q quit

pnpm test                                  # unit tests via @cwe-platform/plugin-sdk/testing

cwe-plugin lifecycle cycle                 # conformance sweep: install→enable→configure→
                                           # disable→uninstall→reinstall, asserts idempotency

cwe-plugin login                           # only needed for shared dev clusters / publishing
cwe-plugin env add dev-eu https://dev-eu.example && cwe-plugin env use dev-eu
pnpm dev                                   # same loop against the shared cluster

pnpm publish:dev                           # = cwe-plugin publish — always the dev channel

Environments & safety

The CLI resolves every runtime's GET /.well-known/cwe-environment descriptor and enforces a fail-closed policy: dev-loop commands (dev, logs, lifecycle, settings, invoke, jobs, tasks, sandbox, doctor --remote) run ONLY against environments with the dev harness mounted and class ∈ {local, development}. An environment that does not declare itself is treated as production. There is no --force. Environment fingerprints are pinned on env add (SSH known_hosts style) — if a URL later resolves to a different environment the CLI hard-stops.

Project config lives in cwe-plugin.json (committed — never holds secrets):

{
  "$schema": "https://cwe.dev/schemas/cwe-plugin.json",
  "plugin": "my-cashback",                 // must equal manifest.key
  "entry": "src/index.ts",
  "environments": {
    "local":  { "runtimeUrl": "http://localhost:3000" },
    "dev-eu": { "runtimeUrl": "https://dev-eu.example" }
  },
  "defaultEnvironment": "local"
}

Machine-local state (env override, pinned fingerprints, log cursor) lives in .cwe/state.json (gitignored, safe to delete). Credentials live in the OS keychain (macOS Keychain / libsecret), falling back to ~/.config/cwe/credentials.json chmod 0600.

Commands

| Command | What it does | |---|---| | create [name] | Scaffold a plugin (--kind, --template blank\|cashback\|provider-skeleton) | | env add/use/list/status | Manage runtime environments (handshake, fingerprint pin, live status) | | login / whoami / logout | Device-code staff login (per the environment's auth.cli mode) | | token create --ttl 1h --scope publish | Mint a non-refreshable CI token (CWE_PLUGIN_TOKEN) | | dev | The dev session: watch → bundle → hot load → live logs → interactive keys | | logs | Standalone log/trace tail (--level, --surface, --grep, --json, --since) | | lifecycle install/enable/configure/disable/uninstall/upgrade [--debug] | Run real lifecycle commands, print full hook traces | | lifecycle cycle | CI-grade conformance sweep with idempotency assertions | | settings schema/get/set/apply | Inspect + change sandbox settings (secrets write-only) | | sandbox reset [--yes] | Wipe this plugin's state on the sandbox tenant | | invoke <METHOD> <path> | Route console: execute a declared route, print response + capability trace | | jobs list/run · tasks run | Job dry-runs and task runs with live progress | | doctor [--remote] | Static manifest checks; --remote runs the full runtime doctor | | build / codegen client | One-off bundle / deterministic @cwe-plugins/<key>-client codegen | | publish / promote / yank / versions | Publish to the dev channel; manage released versions |

Every read command supports --json. --env <name> overrides the default environment per invocation. Auth is auto-refreshing (single-flight, 30s server-side rotation grace); in CI set CWE_PLUGIN_TOKEN — it is used verbatim, never refreshed, never stored.

Requirements

• Node ≥ 20, a CWE runtime with the dev harness enabled (DEV_HARNESS_ENABLED=true, CWE_ENV_CLASS=local|development, sandbox tenant seeded — see the Runtime Core repo's docker-compose.plugindev.yml for the one-command local stack).
• The target plugin project must have @cwe-platform/plugin-sdk installed (the CLI loads the project's own SDK copy for doctor/codegen, so CLI and SDK versions never skew).