@cwe-platform/plugin-cli 0.1.0

package/README.md

@@ -0,0 +1,28 @@
+# @cwe-platform/plugin-cli
+
+The CWE plugin developer loop. Thin by design: `build` runs your plugin's own tsup; `dev` and
+`validate` talk to a dev runtime's harness endpoints.
+
+```bash
+npx @cwe-platform/plugin-cli build      # tsup + local validateManifest (doctor-lite)
+npx @cwe-platform/plugin-cli push       # build once + sideload to the dev runtime
+npx @cwe-platform/plugin-cli dev        # watch src/ → rebuild → hot-reload sideload
+npx @cwe-platform/plugin-cli validate   # full plugin doctor on the runtime
+```
+
+Config — `cwe-plugin.json` in your plugin repo:
+
+```json
+{
+  "runtimeUrl": "http://localhost:3000",
+  "pluginKey": "player-favorites",
+  "devToken": "<staff bearer token>",
+  "bundle": "dist/index.js"
+}
+```
+
+The sideload endpoint (`PUT /dev/plugins/:key/bundle`) exists only on runtimes with the dev
+harness enabled (`docker compose -f docker-compose.plugindev.yml up` in the platform repo);
+production runtimes reject the harness at config time, so the endpoint 404s there.
+
+MIT © CasinoWebEngine

package/bin/cwe-plugin.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * cwe-plugin — the CWE plugin developer loop:
+ *
+ *   cwe-plugin build      tsup build + local manifest validation
+ *   cwe-plugin dev        watch → rebuild → sideload → report (sub-5s reload)
+ *   cwe-plugin validate   run the runtime's plugin doctor
+ *
+ * Config: cwe-plugin.json (runtimeUrl, pluginKey, devToken, bundle?).
+ */
+import { watch } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { resolve } from "node:path";
+import { Command } from "commander";
+import { fetchTrace, loadConfig, runBuild, sideload, validateOnRuntime } from "../src/lib.mjs";
+
+const program = new Command();
+program.name("cwe-plugin").description("CasinoWebEngine plugin developer CLI").version("0.1.0");
+
+async function validateLocal() {
+  // Import the built bundle + the SDK's doctor-lite from the PLUGIN's own
+  // node_modules (the CLI has no SDK dependency of its own — no dual copies).
+  const config = await loadConfig();
+  const bundleUrl = pathToFileURL(resolve(process.cwd(), config.bundle)).href;
+  const testingUrl = pathToFileURL(
+    resolve(process.cwd(), "node_modules/@cwe-platform/plugin-sdk/dist/testing.js"),
+  ).href;
+  const [{ default: plugin }, { validateManifest }] = await Promise.all([
+    import(`${bundleUrl}?t=${Date.now()}`),
+    import(testingUrl),
+  ]);
+  const result = validateManifest(plugin);
+  for (const warning of result.warnings) console.warn(`  ⚠ ${warning}`);
+  for (const error of result.errors) console.error(`  ✗ ${error}`);
+  if (!result.ok) throw new Error("local manifest validation failed");
+  console.log("  ✓ manifest valid (doctor-lite)");
+}
+
+program
+  .command("build")
+  .description("tsup build + local validateManifest")
+  .action(async () => {
+    await runBuild();
+    await validateLocal();
+  });
+
+program
+  .command("validate")
+  .description("run the plugin doctor on the dev runtime")
+  .action(async () => {
+    const config = await loadConfig();
+    const report = await validateOnRuntime(config);
+    for (const check of report.checks ?? []) {
+      console.log(`  ${check.ok ? "✓" : "✗"} ${check.check}${check.detail ? ` (${check.detail})` : ""}`);
+    }
+    for (const warning of report.warnings ?? []) console.warn(`  ⚠ ${warning}`);
+    if (!report.ok) process.exit(1);
+    console.log(`\n${report.plugin}@${report.version}: doctor OK`);
+  });
+
+program
+  .command("push")
+  .description("build once and sideload to the dev runtime")
+  .action(async () => {
+    const config = await loadConfig();
+    await runBuild();
+    const result = await sideload(config);
+    console.log(`  ✓ sideloaded ${result.plugin}@${result.version} (dev channel, hot-reloaded)`);
+    for (const warning of result.warnings ?? []) console.warn(`  ⚠ ${warning}`);
+  });
+
+program
+  .command("dev")
+  .description("watch src/ → rebuild → sideload → tail the harness trace")
+  .action(async () => {
+    const config = await loadConfig();
+    let building = false;
+    let dirty = false;
+
+    const cycle = async () => {
+      if (building) {
+        dirty = true;
+        return;
+      }
+      building = true;
+      const startedAt = Date.now();
+      try {
+        await runBuild();
+        const result = await sideload(config);
+        console.log(
+          `  ✓ ${result.plugin}@${result.version} reloaded in ${Date.now() - startedAt}ms`,
+        );
+        for (const warning of result.warnings ?? []) console.warn(`  ⚠ ${warning}`);
+        try {
+          const trace = await fetchTrace(config);
+          const last = trace.steps?.[trace.steps.length - 1];
+          if (last) console.log(`  ↳ last trace step: ${last.step} (${last.ok ? "ok" : "FAILED"})`);
+        } catch {
+          // No trace yet — fine.
+        }
+      } catch (error) {
+        console.error(`  ✗ ${error instanceof Error ? error.message : error}`);
+      } finally {
+        building = false;
+        if (dirty) {
+          dirty = false;
+          void cycle();
+        }
+      }
+    };
+
+    console.log(`watching src/ — sideloading '${config.pluginKey}' to ${config.runtimeUrl}`);
+    await cycle();
+    let timer;
+    watch(resolve(process.cwd(), "src"), { recursive: true }, () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => void cycle(), 150); // debounce editor bursts
+    });
+  });
+
+program.parseAsync().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@cwe-platform/plugin-cli",
+  "version": "0.1.0",
+  "description": "CasinoWebEngine plugin developer CLI — build, validate and hot-reload plugins against a dev runtime.",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "cwe-plugin": "./bin/cwe-plugin.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "scripts": {
+    "test": "node --test test/"
+  }
+}

package/src/lib.mjs

@@ -0,0 +1,84 @@
+/**
+ * @cwe-platform/plugin-cli internals. Deliberately thin: build = the plugin's
+ * own tsup, validate/dev = HTTP against the dev runtime's harness endpoints.
+ * Plain ESM JS — the CLI ships source, no build step of its own.
+ */
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { join, resolve } from "node:path";
+
+/** cwe-plugin.json: { runtimeUrl, devToken, pluginKey, bundle? } */
+export async function loadConfig(cwd = process.cwd()) {
+  const path = join(cwd, "cwe-plugin.json");
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    throw new Error(
+      `Missing cwe-plugin.json in ${cwd} — create it with { "runtimeUrl": "http://localhost:3000", "pluginKey": "<key>", "devToken": "<staff token>" }`,
+    );
+  }
+  const config = JSON.parse(raw);
+  for (const field of ["runtimeUrl", "pluginKey"]) {
+    if (!config[field]) throw new Error(`cwe-plugin.json is missing '${field}'`);
+  }
+  return {
+    runtimeUrl: String(config.runtimeUrl).replace(/\/$/, ""),
+    pluginKey: config.pluginKey,
+    devToken: config.devToken ?? "",
+    bundle: config.bundle ?? "dist/index.js",
+  };
+}
+
+export function runBuild(cwd = process.cwd()) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn("npx", ["tsup"], { cwd, stdio: "inherit", shell: process.platform === "win32" });
+    child.on("exit", (code) => {
+      if (code === 0) resolvePromise(undefined);
+      else reject(new Error(`tsup exited with code ${code}`));
+    });
+    child.on("error", reject);
+  });
+}
+
+async function api(config, method, path, body) {
+  const response = await fetch(`${config.runtimeUrl}${path}`, {
+    method,
+    headers: {
+      "content-type": "application/json",
+      ...(config.devToken ? { authorization: `Bearer ${config.devToken}` } : {}),
+    },
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+  });
+  const text = await response.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : {};
+  } catch {
+    json = { raw: text };
+  }
+  if (!response.ok) {
+    const message = json?.error?.message ?? json?.message ?? text.slice(0, 300);
+    throw new Error(`${method} ${path} → HTTP ${response.status}: ${message}`);
+  }
+  return json;
+}
+
+/** Upload the built bundle to the dev runtime (checksum-verified sideload). */
+export async function sideload(config, cwd = process.cwd()) {
+  const bundlePath = resolve(cwd, config.bundle);
+  const bundle = await readFile(bundlePath, "utf8");
+  const checksum = createHash("sha256").update(bundle, "utf8").digest("hex");
+  return api(config, "PUT", `/dev/plugins/${config.pluginKey}/bundle`, { bundle, checksum });
+}
+
+/** Run the full plugin doctor on the runtime. */
+export function validateOnRuntime(config) {
+  return api(config, "POST", `/dev/plugins/${config.pluginKey}/validate`, {});
+}
+
+/** Fetch the last stored harness trace (plugin logs/steps). */
+export function fetchTrace(config) {
+  return api(config, "GET", `/dev/plugins/${config.pluginKey}/trace`);
+}