@clovnet/plugin-cli 0.2.2

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@clovnet/plugin-cli",
+  "version": "0.2.2",
+  "description": "Clovnet plugin developer CLI \u2014 create, dev-loop (hot reload + live logs), lifecycle-test and publish plugins against a Clovnet runtime.",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "clovnet-plugin": "bin/cwe-plugin.mjs",
+    "cwe-plugin": "bin/cwe-plugin.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "pnpm build && tsx --test test/*.test.ts",
+    "verify": "pnpm build && tsx --test test/*.test.ts",
+    "prepack": "pnpm build"
+  },
+  "dependencies": {
+    "esbuild": "^0.24.0"
+  },
+  "devDependencies": {
+    "@clovnet/plugin-sdk": "workspace:*",
+    "@cwe/shared": "workspace:*",
+    "@types/node": "^20.16.5",
+    "commander": "^12.1.0",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.1",
+    "typescript": "^5.6.2",
+    "zod": "^3.23.8"
+  },
+  "keywords": [
+    "casinowebengine",
+    "cwe",
+    "plugin",
+    "cli",
+    "igaming"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Clovnet/casino-runtime-core.git",
+    "directory": "packages/plugin-cli"
+  },
+  "homepage": "https://clovnet.com",
+  "bugs": {
+    "url": "https://github.com/Clovnet/casino-runtime-core/issues"
+  },
+  "author": "Clovnet"
+}

package/templates/blank/README.md

@@ -0,0 +1,60 @@
+# __PLUGIN_NAME__
+
+A CasinoWebEngine plugin, scaffolded with `cwe-plugin create`.
+
+## 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
+# each lifecycle key prints a full hook trace: capability calls, events, audit refs, state
+
+pnpm test                                  # unit tests on hooks/handlers via the SDK test kit
+
+cwe-plugin lifecycle cycle                 # conformance sweep: install→enable→configure→disable→
+                                           # uninstall→reinstall, asserting idempotency + clean teardown
+
+cwe-plugin login                           # only needed for shared dev clusters / publishing
+cwe-plugin env add dev-eu https://dev-eu.cwe.dev && cwe-plugin env use dev-eu
+pnpm dev                                   # same loop against the shared cluster, per-dev sandbox
+
+pnpm publish:dev                           # = cwe-plugin publish — always the dev channel:
+                                           # doctor + codegen-diff gate + publish
+```
+
+## What's in this template
+
+| File | Purpose |
+|---|---|
+| `cwe-plugin.json` | project config: plugin key, entry, environments (committed — no secrets, ever) |
+| `src/index.ts` | `definePlugin({ manifest, hooks, handlers })` — the whole platform contract |
+| `src/settings.ts` | Zod-typed tenant settings (one secret field included) |
+| `src/handlers/hooks.ts` | `onInstall` / `onConfigure` / `onUninstall` with commented examples |
+| `src/handlers/routes.ts` | one public route + one player action |
+| `src/handlers/jobs.ts` | one cron job (dry-run with `cwe-plugin jobs run heartbeat`) |
+| `settings.dev.json` | sandbox settings applied by `cwe-plugin lifecycle configure` / the `c` key |
+| `test/hooks.test.ts` | in-memory test-context examples — breakpoints work under `vitest --inspect` |
+
+## Useful commands
+
+```bash
+cwe-plugin env status                # am I pointed at a dev environment? auth? sandbox state?
+cwe-plugin invoke GET /info          # execute a route without curl (add --surface player --player p1)
+cwe-plugin settings set greeting=hi  # validated locally against the schema before it is sent
+cwe-plugin logs --level warn         # standalone log tail for a second terminal
+cwe-plugin doctor --remote           # full server-side validation
+```
+
+Machine-local state (pinned environment fingerprints, log cursors) lives in `.cwe/` — gitignored
+and always safe to delete. Credentials never touch the repo: `cwe-plugin login` stores them in the
+OS keychain.

package/templates/blank/_gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+.cwe/

package/templates/blank/cwe-plugin.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://cwe.dev/schemas/cwe-plugin.json",
+  "plugin": "__PLUGIN_KEY__",
+  "entry": "src/index.ts",
+  "environments": {
+    "local": { "runtimeUrl": "http://localhost:3000" }
+  },
+  "defaultEnvironment": "local"
+}

package/templates/blank/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "cwe-plugin-__PLUGIN_KEY__",
+  "version": "0.1.0",
+  "description": "__PLUGIN_NAME__ \u2014 a CasinoWebEngine plugin",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "cwe-plugin dev",
+    "doctor": "cwe-plugin doctor",
+    "test": "vitest run",
+    "build": "cwe-plugin build",
+    "codegen": "cwe-plugin codegen client",
+    "publish:dev": "cwe-plugin publish"
+  },
+  "dependencies": {
+    "@clovnet/plugin-sdk": "^0.1.4"
+  },
+  "peerDependencies": {
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@clovnet/plugin-cli": "^0.2.0",
+    "@types/node": "^20.16.5",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1",
+    "zod": "^3.23.8"
+  }
+}

package/templates/blank/settings.dev.json

@@ -0,0 +1,8 @@
+{
+  "values": {
+    "greeting": "Hello from the sandbox"
+  },
+  "secrets": {
+    "apiKey": "dev-api-key"
+  }
+}

package/templates/blank/src/handlers/hooks.ts

@@ -0,0 +1,29 @@
+import type { PluginContext } from "@clovnet/plugin-sdk";
+
+/**
+ * Lifecycle hooks. The platform runs each with a 5s watchdog (lifted to 10
+ * minutes under `cwe-plugin lifecycle <action> --debug` so breakpoints work);
+ * a throwing hook marks the plugin `errored` — it never corrupts core data.
+ * Hooks must be idempotent: `cwe-plugin lifecycle cycle` asserts a re-run of
+ * every action is a no-op.
+ */
+export async function onInstall(ctx: PluginContext): Promise<void> {
+  ctx.logger.info("__PLUGIN_KEY__.installed");
+  // Seed data here (idempotently), e.g.:
+  //   await ctx.datasets.collection("records").put("welcome", { id: "welcome" });
+  // For long-running seeds declare `install: { seedTask: "seed" }` in the
+  // manifest and implement it under handlers.tasks — it runs async with
+  // checkpoints instead of blocking the install.
+}
+
+export async function onConfigure(ctx: PluginContext): Promise<void> {
+  // Runs after settings were validated and saved for the tenant.
+  const { greeting } = ctx.settings.get<{ greeting?: string }>();
+  ctx.logger.info("__PLUGIN_KEY__.configured", { greetingLength: greeting?.length ?? 0 });
+}
+
+export async function onUninstall(ctx: PluginContext): Promise<void> {
+  // Datasets are archived automatically on uninstall (and restored if the
+  // plugin is reinstalled) — only clean up EXTERNAL state here.
+  ctx.logger.info("__PLUGIN_KEY__.uninstalled");
+}

package/templates/blank/src/handlers/jobs.ts

@@ -0,0 +1,9 @@
+import type { PluginContext } from "@clovnet/plugin-sdk";
+
+/**
+ * Cron jobs run in the worker process on the declared schedule. Dry-run any
+ * time with `cwe-plugin jobs run heartbeat` — output streams into `pnpm dev`.
+ */
+export async function heartbeat(ctx: PluginContext): Promise<void> {
+  ctx.logger.info("__PLUGIN_KEY__.heartbeat", { at: new Date().toISOString() });
+}

package/templates/blank/src/handlers/routes.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import type { PluginContext, PluginRequest } from "@clovnet/plugin-sdk";
+
+/**
+ * Route handlers. Surfaces:
+ *   public   → /api/ext/__PLUGIN_KEY__/…      (no auth)
+ *   player   → /api/ext/__PLUGIN_KEY__/…      (player session required)
+ *   admin    → backoffice-only (staff RBAC)
+ *   callback → server-to-server webhooks (verifySignature)
+ * Try them instantly: `cwe-plugin invoke GET /info` ·
+ * `cwe-plugin invoke GET /me --surface player --player p1`.
+ */
+export const infoOutputSchema = z.object({
+  plugin: z.string(),
+  greeting: z.string(),
+});
+
+export async function info(_req: PluginRequest, ctx: PluginContext) {
+  const settings = ctx.settings.get<{ greeting?: string }>();
+  return {
+    body: {
+      plugin: "__PLUGIN_KEY__",
+      greeting: settings.greeting ?? "Hello from __PLUGIN_NAME__",
+    },
+  };
+}
+
+export const meOutputSchema = z.object({
+  playerId: z.string(),
+  pinged: z.literal(true),
+});
+
+/** A player action (declared in manifest.actions → shows up in the SDK
+ * extension catalog and the generated typed client). */
+export async function getMe(req: PluginRequest, ctx: PluginContext) {
+  const playerId = req.player?.id;
+  if (!playerId) return { status: 401, body: { error: { code: "UNAUTHORIZED" } } };
+  await ctx.events.emit({
+    name: "plugin.__PLUGIN_KEY__.pinged",
+    playerId,
+    payload: { at: new Date().toISOString() },
+  });
+  return { body: { playerId, pinged: true as const } };
+}

package/templates/blank/src/index.ts

@@ -0,0 +1,68 @@
+import { definePlugin } from "@clovnet/plugin-sdk";
+import { settings } from "./settings.js";
+import { onConfigure, onInstall, onUninstall } from "./handlers/hooks.js";
+import { getMe, info, infoOutputSchema, meOutputSchema } from "./handlers/routes.js";
+import { heartbeat } from "./handlers/jobs.js";
+
+/**
+ * __PLUGIN_NAME__ — scaffolded from the `blank` template.
+ *
+ * The manifest is the plugin's entire contract with the platform: routes,
+ * jobs, datasets, permissions, settings. Everything NOT declared here is
+ * denied at runtime (and `cwe-plugin doctor` catches drift before the host
+ * does). Changing the manifest in `pnpm dev` triggers a reinstall prompt —
+ * handler-only edits hot-reload in under 2s.
+ */
+export default definePlugin({
+  manifest: {
+    key: "__PLUGIN_KEY__",
+    name: "__PLUGIN_NAME__",
+    author: "you",
+    version: "0.1.0",
+    kind: "__PLUGIN_KIND__",
+    runtimeCompat: ">=0.1.0 <0.2.0",
+    description: "__PLUGIN_NAME__ — scaffolded with cwe-plugin create.",
+    permissions: {
+      // Explicit allowlists — commands/events not listed here are denied.
+      commands: [],
+      events: {
+        subscribe: [],
+        emit: ["plugin.__PLUGIN_KEY__.pinged"],
+      },
+    },
+    settings,
+    routes: [
+      {
+        method: "GET",
+        path: "/info",
+        surface: "public",
+        handler: "info",
+        output: infoOutputSchema,
+        rateLimit: { windowSec: 60, max: 120 },
+      },
+      {
+        method: "GET",
+        path: "/me",
+        surface: "player",
+        handler: "getMe",
+        output: meOutputSchema,
+      },
+    ],
+    actions: [
+      {
+        key: "getMe",
+        route: "GET /me",
+        title: "Ping as the current player",
+        kind: "query",
+      },
+    ],
+    jobs: {
+      heartbeat: { schedule: "0 6 * * *", handler: "heartbeat", timeoutSec: 60 },
+    },
+  },
+  hooks: { onInstall, onConfigure, onUninstall },
+  handlers: {
+    routes: { info, getMe },
+    jobs: { heartbeat },
+  },
+});

package/templates/blank/src/settings.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { settingsField, type PluginSettingsSchema } from "@clovnet/plugin-sdk";
+
+/**
+ * Typed per-tenant settings. Each field pairs backoffice UI metadata with the
+ * Zod validator the platform enforces at the boundary. Secret fields are
+ * stored encrypted, are write-only over the API and never appear in logs.
+ */
+export const settings: PluginSettingsSchema = {
+  fields: {
+    greeting: settingsField.string({
+      label: "Greeting",
+      description: "Returned by the public /info route.",
+      default: "Hello from __PLUGIN_NAME__",
+      zod: z.string().min(1).max(120),
+    }),
+    apiKey: settingsField.string({
+      label: "API key",
+      description: "Example write-only secret — read it with ctx.secrets.get('apiKey').",
+      secret: true,
+    }),
+  },
+};

package/templates/blank/test/hooks.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { createTestContext } from "@clovnet/plugin-sdk/testing";
+import type { PluginRequest } from "@clovnet/plugin-sdk";
+import plugin from "../src/index.js";
+import { getMe } from "../src/handlers/routes.js";
+
+/**
+ * Unit tests on the in-memory test context — no runtime, no docker, and
+ * `vitest --inspect` breakpoints inside hooks/handlers just work. The fake
+ * enforces the SAME permission rules as production: an undeclared command,
+ * a foreign dataset or a non-allowlisted host throws here too.
+ */
+const asRequest = (partial: Partial<PluginRequest>): PluginRequest =>
+  ({ params: {}, query: {}, headers: {}, ...partial }) as PluginRequest;
+
+describe("__PLUGIN_KEY__", () => {
+  it("installs and configures cleanly (idempotent)", async () => {
+    const t = createTestContext(plugin, {
+      tenantId: "t-test",
+      settings: { greeting: "Hi!" },
+      secrets: { apiKey: "test-key" },
+    });
+    await t.runHook("onInstall");
+    await t.runHook("onInstall"); // hooks must tolerate re-runs
+    await t.runHook("onConfigure");
+    expect(t.recorder.commands).toHaveLength(0); // this template moves no money
+  });
+
+  it("emits the ping event for the current player", async () => {
+    const t = createTestContext(plugin, { settings: { greeting: "Hi!" } });
+    const response = await getMe(asRequest({ player: { id: "p1" } }), t.ctx);
+    expect(response.body).toMatchObject({ playerId: "p1", pinged: true });
+    expect(t.recorder.events).toHaveLength(1);
+    expect(t.recorder.events[0]?.name).toBe("plugin.__PLUGIN_KEY__.pinged");
+  });
+
+  it("rejects anonymous callers on the player surface", async () => {
+    const t = createTestContext(plugin, { settings: { greeting: "Hi!" } });
+    const response = await getMe(asRequest({}), t.ctx);
+    expect(response.status).toBe(401);
+    expect(t.recorder.events).toHaveLength(0);
+  });
+});

package/templates/blank/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["src", "test"]
+}

package/templates/cashback/README.md

@@ -0,0 +1,61 @@
+# __PLUGIN_NAME__
+
+A CasinoWebEngine cashback plugin (the reference-plugin shape), scaffolded with `cwe-plugin create`.
+
+## 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
+# each lifecycle key prints a full hook trace: capability calls, events, audit refs, state
+
+pnpm test                                  # unit tests on hooks/handlers via the SDK test kit
+
+cwe-plugin lifecycle cycle                 # conformance sweep: install→enable→configure→disable→
+                                           # uninstall→reinstall, asserting idempotency + clean teardown
+
+cwe-plugin login                           # only needed for shared dev clusters / publishing
+cwe-plugin env add dev-eu https://dev-eu.cwe.dev && cwe-plugin env use dev-eu
+pnpm dev                                   # same loop against the shared cluster, per-dev sandbox
+
+pnpm publish:dev                           # = cwe-plugin publish — always the dev channel:
+                                           # doctor + codegen-diff gate + publish
+```
+
+## What's in this template
+
+| File | Purpose |
+|---|---|
+| `cwe-plugin.json` | project config: plugin key, entry, environments (committed — no secrets, ever) |
+| `src/index.ts` | `definePlugin({ manifest, hooks, handlers })` — the whole platform contract |
+| `src/settings.ts` | Zod-typed tenant settings (one secret field included) |
+| `src/handlers/hooks.ts` | `onInstall` / `onConfigure` / `onUninstall` with commented examples |
+| `src/handlers/routes.ts` | player actions `getSummary`/`listPeriods`/`claim` + admin `accrue` |
+| `src/handlers/jobs.ts` | nightly accrual sweep (dry-run with `cwe-plugin jobs run nightly-accrual`) |
+| `settings.dev.json` | sandbox settings applied by `cwe-plugin lifecycle configure` / the `c` key |
+| `test/hooks.test.ts` | in-memory test-context examples — breakpoints work under `vitest --inspect` |
+
+## Useful commands
+
+```bash
+cwe-plugin env status                # am I pointed at a dev environment? auth? sandbox state?
+cwe-plugin invoke POST /accrue --surface admin --body '{"playerId":"p1","amount":5}'
+cwe-plugin invoke GET /summary --surface player --player p1
+cwe-plugin settings set greeting=hi  # validated locally against the schema before it is sent
+cwe-plugin logs --level warn         # standalone log tail for a second terminal
+cwe-plugin doctor --remote           # full server-side validation
+```
+
+Machine-local state (pinned environment fingerprints, log cursors) lives in `.cwe/` — gitignored
+and always safe to delete. Credentials never touch the repo: `cwe-plugin login` stores them in the
+OS keychain.

package/templates/cashback/_gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+.cwe/

package/templates/cashback/cwe-plugin.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://cwe.dev/schemas/cwe-plugin.json",
+  "plugin": "__PLUGIN_KEY__",
+  "entry": "src/index.ts",
+  "environments": {
+    "local": { "runtimeUrl": "http://localhost:3000" }
+  },
+  "defaultEnvironment": "local"
+}

package/templates/cashback/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "cwe-plugin-__PLUGIN_KEY__",
+  "version": "0.1.0",
+  "description": "__PLUGIN_NAME__ \u2014 a CasinoWebEngine plugin",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "cwe-plugin dev",
+    "doctor": "cwe-plugin doctor",
+    "test": "vitest run",
+    "build": "cwe-plugin build",
+    "codegen": "cwe-plugin codegen client",
+    "publish:dev": "cwe-plugin publish"
+  },
+  "dependencies": {
+    "@clovnet/plugin-sdk": "^0.1.4"
+  },
+  "peerDependencies": {
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@clovnet/plugin-cli": "^0.2.0",
+    "@types/node": "^20.16.5",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1",
+    "zod": "^3.23.8"
+  }
+}

package/templates/cashback/settings.dev.json

@@ -0,0 +1,9 @@
+{
+  "values": {
+    "cashbackPercent": 10,
+    "payoutCurrency": "EUR"
+  },
+  "secrets": {
+    "reportingApiKey": "dev-reporting-key"
+  }
+}

package/templates/cashback/src/handlers/hooks.ts

@@ -0,0 +1,19 @@
+import type { PluginContext } from "@clovnet/plugin-sdk";
+
+/**
+ * Lifecycle hooks — all idempotent (`cwe-plugin lifecycle cycle` asserts a
+ * re-run of every action is a no-op). Datasets archive automatically on
+ * uninstall, so there is nothing to clean up here.
+ */
+export async function onInstall(ctx: PluginContext): Promise<void> {
+  ctx.logger.info("__PLUGIN_KEY__.installed");
+}
+
+export async function onConfigure(ctx: PluginContext): Promise<void> {
+  const { cashbackPercent } = ctx.settings.get<{ cashbackPercent?: number }>();
+  ctx.logger.info("__PLUGIN_KEY__.configured", { cashbackPercent: cashbackPercent ?? 5 });
+}
+
+export async function onUninstall(ctx: PluginContext): Promise<void> {
+  ctx.logger.info("__PLUGIN_KEY__.uninstalled");
+}

package/templates/cashback/src/handlers/jobs.ts

@@ -0,0 +1,23 @@
+import type { PluginContext } from "@clovnet/plugin-sdk";
+import { type AccrualPeriod } from "./routes.js";
+
+/**
+ * Nightly sweep: periods still `accruing` at the cycle boundary become
+ * `claimable`. Idempotent by construction (flipping twice is a no-op) —
+ * dry-run any time with `cwe-plugin jobs run nightly-accrual`.
+ */
+export async function nightlyAccrual(ctx: PluginContext): Promise<void> {
+  const periods = ctx.datasets.collection<AccrualPeriod>("accrual_periods");
+  let cursor: string | undefined;
+  let flipped = 0;
+  for (;;) {
+    const page = await periods.query({ where: { status: "accruing" }, cursor, limit: 200 });
+    for (const record of page.records) {
+      await periods.put(record.key, { ...record.value, status: "claimable" });
+      flipped += 1;
+    }
+    if (!page.nextCursor) break;
+    cursor = page.nextCursor;
+  }
+  ctx.logger.info("__PLUGIN_KEY__.nightly_accrual", { flipped });
+}