@clovnet/plugin-cli 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog — @clovnet/plugin-cli
+
+## 0.2.2 (2026-07)
+
+- `--version` reports the real package version. `CLI_VERSION` was a hardcoded literal in
+  `src/program.ts` that nobody bumped, so 0.2.1 shipped to npm announcing itself as `0.2.0`. It is
+  now read from `package.json` (`../package.json` resolves to the package root from both the source
+  tree and the bundled `dist/cli.js`), and `test/cli.test.ts` asserts the built binary's `--version`
+  matches `package.json` so it cannot drift again.
+
+## 0.2.1 (2026-07)
+
+Hardening release — adversarial review (5 dimensions + verify pass) confirmed 11 findings, all
+fixed with regression coverage. No CLI surface or config-schema changes; 0.2.0 projects work as-is.
+
+**Security:**
+
+- `env status` no longer sends the stored refresh token to a fingerprint-mismatched environment —
+  the environment pin is enforced *before* any authenticated call.
+- `refresh` only discards credentials on a genuine auth failure (401 / known auth codes). 5xx and
+  429 now surface `RUNTIME_UNAVAILABLE` and keep the token, so a runtime blip no longer logs you out.
+- A failed `secret-tool` keychain write is reported instead of silently falling through.
+
+**Fixes:**
+
+- SSE client tolerates a runtime restart: handles the `cursorReset` marker and a low-seq heuristic,
+  so log streaming no longer goes dark after an api restart.
+- `publish` loads the freshly built bundle before running the remote doctor (was doctoring a stale
+  bundle).
+- `lifecycle install --version` pins the requested version instead of resolving max semver.
+- `lifecycle` load-first is unconditional for `install`/`enable`/`configure`/`upgrade` and the cycle
+  sweep — a no-op install against an already-installed plugin used to leave a fresh api without the
+  code, breaking a later `configure`.
+- `dev` coalesces rebuilds that land while a build is already in flight.
+
+## 0.2.0 (2026-07)
+
+Complete rebuild in TypeScript per `PLUGIN_DEV_CLI_PROMPT.md` — the CLI is now the full plugin
+developer product, not a sideload script.
+
+**Breaking changes (migration from 0.1.x):**
+
+- `cwe-plugin.json` schema changed: flat `{runtimeUrl, pluginKey, devToken?, bundle?}` →
+  `{plugin, entry, environments: {name: {runtimeUrl}}, defaultEnvironment}` (Zod-validated,
+  unknown keys rejected). A leftover `devToken` key is rejected with a migration hint —
+  **tokens no longer live in the project file** (they were committed plaintext); credentials
+  now live in the OS keychain (fallback `~/.config/cwe/credentials.json`, 0600).
+- `login` switched from email/password (cookie scrape) to the RFC-8628-shaped device-code flow
+  against `/auth/staff/device*`; refresh tokens rotate automatically (single-flight, file-locked).
+  `CWE_STAFF_EMAIL`/`CWE_STAFF_PASSWORD` relogin is gone; CI uses `CWE_PLUGIN_TOKEN`
+  (`cwe-plugin token create --ttl 1h --scope publish`).
+- `push` is gone — `dev` hot-loads via the new `POST /dev/plugins/:key/load`
+  (`bundleBase64` + checksum + manifestHash); builds use esbuild directly (single ESM bundle,
+  SDK + zod external, inline sourcemaps in dev, 10 MB cap) instead of spawning the project's tsup.
+- Dev-loop commands enforce the environment class policy (descriptor handshake, fingerprint
+  pinning, exit 2 on violation, no `--force`).
+
+**New:**
+
+- `create` (three templates: blank, cashback, provider-skeleton) + `pnpm create cwe-plugin`.
+- `env add/use/list/status`; `whoami`/`logout`/`token create`.
+- `dev` interactive session: live log/trace streaming (SSE with cursor resume), lifecycle keys,
+  manifest-change reinstall prompts, `--auto-install`/`--auto-reinstall`.
+- `logs` standalone tail with `--level/--surface/--grep/--json`.
+- `lifecycle …` with full hook traces (capability calls, audit refs, outbox events),
+  `--debug` (10-minute hook watchdog for breakpoint sessions), `lifecycle cycle` conformance sweep.
+- `settings schema/get/set/apply`, `sandbox reset`, `invoke`, `jobs list/run`, `tasks run`,
+  `doctor [--remote]`, `publish/promote/yank/versions`.
+- `codegen client` carried over unchanged (still runs via the target project's own SDK copy).
+
+## 0.1.2 (2026-07)
+
+Legacy JS CLI: `login` (password), `build` (tsup), `codegen client`, `validate`, `push`, `dev`
+(watch + sideload via `PUT /dev/plugins/:key/bundle`). The `PUT /bundle` endpoint remains
+supported by current runtimes, so 0.1.x keeps working during migration.

package/LICENSE

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

package/README.md

@@ -0,0 +1,92 @@
+# @clovnet/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
+
+```bash
+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 @clovnet/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):
+
+```jsonc
+{
+  "$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 `@clovnet/plugin-sdk` installed (the CLI loads the
+  project's own SDK copy for doctor/codegen, so CLI and SDK versions never skew).

package/bin/cwe-plugin.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// Thin launcher — all logic lives in the tsup-built dist/cli.js. In the
+// workspace, run `pnpm --filter @clovnet/plugin-cli build` once first.
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const dist = new URL("../dist/cli.js", import.meta.url);
+if (!existsSync(fileURLToPath(dist))) {
+  console.error(
+    "cwe-plugin: dist/cli.js not found — build the CLI first: pnpm --filter @clovnet/plugin-cli build",
+  );
+  process.exit(1);
+}
+await import(dist.href);