create-struxa-extension 2.0.0

package/README.md

@@ -0,0 +1,42 @@
+# create-struxa-extension
+
+Scaffold a new [Struxa](https://struxa.cloud) extension.
+
+```bash
+# with npm
+npm create struxa-extension my-ext
+
+# or directly
+npx create-struxa-extension my-ext --template react
+```
+
+Options:
+
+- `<dir>` — target directory (required); its name becomes the extension id.
+- `--template, -t` — `react` (default) or `vanilla`.
+- `--name, -n` — display name (defaults to a title-cased id).
+
+Then:
+
+```bash
+cd my-ext
+npm install
+npm run build        # -> dist/ (the package the registry publishes)
+```
+
+Add `<path>/dist` to your registry's `registry.config.json`, run the registry
+build, and install from **Admin → Extensions**.
+
+## What you get
+
+- `manifest.json` — id, permissions, and a panel page at `/<id>`.
+- `server/index.js` — a `register(ctx)` entry exposing `ext.<id>.ping` (extend it
+  with your own oRPC procedures, hooks, scoped DB/settings via `ctx`).
+- `src/` — the UI. The **react** template uses `@struxa/extension-sdk/react`
+  (`useHostBridge`) and `@struxa/extension-sdk/client` (`createHostClient`); the
+  **vanilla** template uses the same SDK without a UI framework. Both bundle with
+  esbuild into `dist/web`.
+
+> Until `@struxa/extension-sdk` is published to your registry, use a local link
+> for development: `npm install ../struxa/packages/extension-sdk` (or
+> `npm link @struxa/extension-sdk`).

package/index.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as p from "@clack/prompts";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const TEXT_EXT = new Set([
+  ".json",
+  ".ts",
+  ".tsx",
+  ".js",
+  ".mjs",
+  ".html",
+  ".md",
+  ".gitignore",
+]);
+
+function slugify(s) {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 63);
+}
+
+function titleize(slug) {
+  return slug.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+// Pre-fill from CLI args so the tool is still scriptable.
+const args = process.argv.slice(2);
+let argDir = null, argTemplate = null, argName = null;
+let nonInteractive = !process.stdin.isTTY;
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if ((a === "--template" || a === "-t") && args[i + 1]) argTemplate = args[++i];
+  else if ((a === "--name" || a === "-n") && args[i + 1]) argName = args[++i];
+  else if (a === "--yes" || a === "-y") nonInteractive = true;
+  else if (!a.startsWith("-")) argDir ??= a;
+}
+
+p.intro("Create a Struxa Extension");
+
+// --- directory ---
+let dir;
+if (argDir) {
+  dir = argDir;
+} else if (nonInteractive) {
+  p.cancel("--dir is required in non-interactive mode.");
+  process.exit(1);
+} else {
+  const rawDir = await p.text({
+    message: "Target directory",
+    placeholder: "my-extension",
+    validate: (v) => (v.trim() ? undefined : "Required."),
+  });
+  if (p.isCancel(rawDir)) { p.cancel("Cancelled."); process.exit(0); }
+  dir = String(rawDir);
+}
+const targetDir = path.resolve(process.cwd(), dir);
+if (existsSync(targetDir) && readdirSync(targetDir).length > 0) {
+  p.cancel(`"${dir}" already exists and is not empty.`);
+  process.exit(1);
+}
+
+// --- extension id ---
+const defaultId = slugify(path.basename(targetDir));
+let id;
+if (nonInteractive) {
+  id = defaultId;
+} else {
+  const rawId = await p.text({
+    message: "Extension id",
+    initialValue: defaultId,
+    validate: (v) =>
+      /^[a-z][a-z0-9-]{1,62}$/.test(v)
+        ? undefined
+        : "Must be a lowercase slug (letters, numbers, hyphens).",
+  });
+  if (p.isCancel(rawId)) { p.cancel("Cancelled."); process.exit(0); }
+  id = String(rawId);
+}
+
+// --- display name ---
+let name;
+if (argName) {
+  name = argName;
+} else if (nonInteractive) {
+  name = titleize(id);
+} else {
+  const rawName = await p.text({
+    message: "Display name",
+    initialValue: titleize(id),
+    validate: (v) => (v.trim() ? undefined : "Required."),
+  });
+  if (p.isCancel(rawName)) { p.cancel("Cancelled."); process.exit(0); }
+  name = String(rawName);
+}
+
+// --- template ---
+let template;
+if (argTemplate) {
+  template = argTemplate;
+} else if (nonInteractive) {
+  template = "react";
+} else {
+  const rawTemplate = await p.select({
+    message: "Template",
+    options: [
+      {
+        value: "react",
+        label: "React",
+        hint: "TypeScript + React — builds to dist/ with struxa build",
+      },
+      {
+        value: "vanilla",
+        label: "Vanilla JS",
+        hint: "No build step — plain HTML + JS, loads SDK from CDN",
+      },
+    ],
+  });
+  if (p.isCancel(rawTemplate)) { p.cancel("Cancelled."); process.exit(0); }
+  template = String(rawTemplate);
+}
+
+// --- features (React only) ---
+let features = [];
+if (template === "react" && !nonInteractive) {
+  const rawFeatures = await p.multiselect({
+    message: "Add features",
+    options: [
+      {
+        value: "add-slots",
+        label: "Widget slots",
+        hint: "inject a widget into host pages (e.g. server overview)",
+      },
+      {
+        value: "add-database",
+        label: "Database tables",
+        hint: "own MySQL tables via the db:own permission",
+      },
+      {
+        value: "add-hooks",
+        label: "Lifecycle hooks",
+        hint: "subscribe to events like server.created",
+      },
+    ],
+    required: false,
+  });
+  if (p.isCancel(rawFeatures)) { p.cancel("Cancelled."); process.exit(0); }
+  features = rawFeatures;
+}
+
+// --- scaffold ---
+const s = p.spinner();
+s.start("Scaffolding…");
+
+const templateDir = path.join(here, "templates", template);
+if (!existsSync(templateDir)) {
+  s.stop("Failed.");
+  p.cancel(`Template "${template}" not found.`);
+  process.exit(1);
+}
+
+mkdirSync(targetDir, { recursive: true });
+cpSync(templateDir, targetDir, {
+  recursive: true,
+  filter: (src) => {
+    // widget.tsx is added only when add-slots is selected.
+    const rel = src.slice(templateDir.length);
+    if (rel === `${path.sep}src${path.sep}widget.tsx` || rel === "/src/widget.tsx") return false;
+    return true;
+  },
+});
+
+// Replace __EXT_ID__ / __EXT_NAME__ placeholders across the tree.
+(function walk(d) {
+  for (const entry of readdirSync(d)) {
+    const fp = path.join(d, entry);
+    if (statSync(fp).isDirectory()) {
+      walk(fp);
+    } else if (TEXT_EXT.has(path.extname(entry)) || entry === ".gitignore") {
+      writeFileSync(
+        fp,
+        readFileSync(fp, "utf8")
+          .replaceAll("__EXT_ID__", id)
+          .replaceAll("__EXT_NAME__", name),
+      );
+    }
+  }
+})(targetDir);
+
+// Apply React feature flags.
+if (template === "react") {
+  const manifestPath = path.join(targetDir, "manifest.json");
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  const serverPath = path.join(targetDir, "server", "index.js");
+  let serverSrc = readFileSync(serverPath, "utf8");
+  const dbPrefix = `ext_${id.replaceAll("-", "_")}`;
+
+  if (features.includes("add-database")) {
+    manifest.permissions = [...new Set([...manifest.permissions, "db:own"])];
+    mkdirSync(path.join(targetDir, "migrations"), { recursive: true });
+    writeFileSync(
+      path.join(targetDir, "migrations", "0000_init.sql"),
+      [
+        `-- Tables must be prefixed ${dbPrefix}_`,
+        `CREATE TABLE ${dbPrefix}_items (`,
+        `  id VARCHAR(36) NOT NULL PRIMARY KEY,`,
+        `  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP`,
+        `);`,
+        "",
+      ].join("\n"),
+    );
+    serverSrc = serverSrc.replace(
+      "const pp = ctx.procedures",
+      `// ctx.db is available (db:own) — use Drizzle or raw SQL:\n    // e.g. await ctx.db.execute(sql\`SELECT * FROM ${dbPrefix}_items\`);\n    const pp = ctx.procedures`,
+    );
+  }
+
+  if (features.includes("add-hooks")) {
+    manifest.permissions = [...new Set([...manifest.permissions, "hook:server.created"])];
+    serverSrc = serverSrc.replace(
+      "    return { router };",
+      `    ctx.hooks.on("server.created", async ({ server }) => {\n      ctx.logger.info("server created", { id: server.id });\n    });\n\n    return { router };`,
+    );
+  }
+
+  if (features.includes("add-slots")) {
+    if (!manifest.ui) manifest.ui = { pages: [], slots: [] };
+    if (!manifest.ui.slots) manifest.ui.slots = [];
+    manifest.ui.slots.push({ slot: "server.overview.after", widget: `/${id}/widget` });
+
+    const widgetSrc = readFileSync(path.join(templateDir, "src", "widget.tsx"), "utf8")
+      .replaceAll("__EXT_ID__", id)
+      .replaceAll("__EXT_NAME__", name);
+    writeFileSync(path.join(targetDir, "src", "widget.tsx"), widgetSrc);
+  }
+
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+  writeFileSync(serverPath, serverSrc);
+}
+
+s.stop("Done.");
+
+p.note(
+  [
+    `  cd ${dir}`,
+    `  npm install`,
+    `  npm run build`,
+    ``,
+    `Then add "<path>/dist" to your registry and publish.`,
+  ].join("\n"),
+  "Next steps",
+);
+
+p.outro(`Created "${name}" (${id})`);

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "create-struxa-extension",
+  "version": "2.0.0",
+  "description": "Interactive scaffolder for Struxa extensions.",
+  "type": "module",
+  "bin": {
+    "create-struxa-extension": "index.mjs"
+  },
+  "files": ["index.mjs", "templates", "README.md"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.10.0"
+  },
+  "license": "MIT"
+}

package/templates/react/manifest.json

@@ -0,0 +1,13 @@
+{
+  "id": "__EXT_ID__",
+  "name": "__EXT_NAME__",
+  "version": "1.0.0",
+  "description": "__EXT_NAME__ — a Struxa extension.",
+  "struxaApi": "^1.0.0",
+  "permissions": ["api:protected"],
+  "ui": {
+    "pages": [
+      { "route": "/__EXT_ID__", "section": "panel", "label": "__EXT_NAME__", "icon": "Blocks" }
+    ]
+  }
+}

package/templates/react/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "__EXT_ID__",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "__EXT_NAME__ — a Struxa extension (React).",
+  "scripts": {
+    "build": "struxa build",
+    "dev": "struxa dev"
+  },
+  "dependencies": {
+    "@struxa/extension-build": "^1.0.0",
+    "@struxa/extension-sdk": "^1.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  }
+}

package/templates/react/server/index.js

@@ -0,0 +1,22 @@
+/**
+ * Server entry — plain ESM, imports nothing (runs from the data volume). The
+ * capability-scoped `ctx` is the only sanctioned host surface.
+ */
+export default {
+  async register(ctx) {
+    ctx.logger.info("__EXT_ID__ registered", { version: ctx.version });
+
+    const pp = ctx.procedures.protectedProcedure;
+    const router = pp
+      ? {
+          ping: pp.handler(({ context }) => ({
+            ok: true,
+            ts: Date.now(),
+            user: context?.session?.user?.id ?? null,
+          })),
+        }
+      : {};
+
+    return { router };
+  },
+};

package/templates/react/src/App.tsx

@@ -0,0 +1,47 @@
+import { useState } from "react";
+import { useHostBridge } from "@struxa/extension-sdk/react";
+import { createHostClient } from "@struxa/extension-sdk/client";
+
+const client = createHostClient<{
+  ext: { "__EXT_ID__": { ping: () => Promise<unknown> } };
+}>();
+
+export function App() {
+  const { context, toast } = useHostBridge();
+  const [result, setResult] = useState("Ready.");
+
+  async function ping() {
+    try {
+      setResult(JSON.stringify(await client.ext["__EXT_ID__"].ping(), null, 2));
+    } catch (err) {
+      setResult(`error: ${String(err)}`);
+    }
+  }
+
+  const card: React.CSSProperties = {
+    margin: 24,
+    maxWidth: 640,
+    padding: 20,
+    borderRadius: 12,
+    border: "1px solid var(--border, #2a2a2e)",
+    background: "var(--card, #141416)",
+    color: "var(--foreground, #e7e7e9)",
+    fontFamily: "ui-sans-serif, system-ui, sans-serif",
+  };
+
+  return (
+    <div style={card}>
+      <h1 style={{ fontSize: 18, margin: "0 0 4px" }}>__EXT_NAME__</h1>
+      <p style={{ fontSize: 13, color: "var(--muted-foreground, #9a9aa2)", marginTop: 0 }}>
+        Signed in as {context?.session.userId ?? "…"}
+      </p>
+      <div style={{ display: "flex", gap: 8 }}>
+        <button onClick={ping}>Call ping</button>
+        <button onClick={() => toast("success", "Hello!")}>Toast</button>
+      </div>
+      <pre style={{ background: "var(--muted, #1b1b1f)", padding: 12, borderRadius: 8, marginTop: 12 }}>
+        {result}
+      </pre>
+    </div>
+  );
+}

package/templates/react/src/main.tsx

@@ -0,0 +1,5 @@
+import { createExtension } from "@struxa/extension-sdk/react";
+
+import { App } from "./App";
+
+createExtension(<App />);

package/templates/react/src/page.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>__EXT_NAME__</title>
+    <style>body { margin: 0; background: var(--background, #0b0b0c); }</style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./bundle.js"></script>
+  </body>
+</html>

package/templates/react/src/widget.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>__EXT_NAME__ widget</title>
+    <style>body { margin: 0; background: var(--card, #141416); }</style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./bundle.js"></script>
+  </body>
+</html>

package/templates/react/src/widget.tsx

@@ -0,0 +1,24 @@
+import { createExtension, useHostBridge } from "@struxa/extension-sdk/react";
+
+function Widget() {
+  const { context } = useHostBridge();
+  return (
+    <div
+      style={{
+        padding: 16,
+        borderRadius: 12,
+        border: "1px solid var(--border, #2a2a2e)",
+        background: "var(--card, #141416)",
+        color: "var(--foreground, #e7e7e9)",
+        fontFamily: "ui-sans-serif, system-ui, sans-serif",
+      }}
+    >
+      <strong>__EXT_NAME__</strong>
+      <div style={{ fontSize: 12, color: "var(--muted-foreground, #9a9aa2)" }}>
+        {context?.params?.serverId ?? "slot widget"}
+      </div>
+    </div>
+  );
+}
+
+createExtension(<Widget />);

package/templates/react/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "types": []
+  },
+  "include": ["src"]
+}

package/templates/vanilla/build.mjs

@@ -0,0 +1,35 @@
+import { copyFileSync, cpSync, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as esbuild from "esbuild";
+
+/**
+ * Builds this extension into dist/ — the package contract the registry ships.
+ * The SDK is bundled inline by esbuild (the "vanilla" template still uses a
+ * bundler so it can import the SDK; it just doesn't use a UI framework).
+ */
+const root = path.dirname(fileURLToPath(import.meta.url));
+const dist = path.join(root, "dist");
+
+rmSync(dist, { recursive: true, force: true });
+mkdirSync(path.join(dist, "web"), { recursive: true });
+
+await esbuild.build({
+  entryPoints: [path.join(root, "src/main.js")],
+  bundle: true,
+  format: "esm",
+  target: "es2020",
+  minify: true,
+  outfile: path.join(dist, "web/bundle.js"),
+  logLevel: "info",
+});
+copyFileSync(path.join(root, "src/index.html"), path.join(dist, "web/index.html"));
+
+copyFileSync(path.join(root, "manifest.json"), path.join(dist, "manifest.json"));
+cpSync(path.join(root, "server"), path.join(dist, "server"), { recursive: true });
+if (existsSync(path.join(root, "migrations"))) {
+  cpSync(path.join(root, "migrations"), path.join(dist, "migrations"), { recursive: true });
+}
+writeFileSync(path.join(dist, "package.json"), JSON.stringify({ type: "module" }, null, 2) + "\n");
+
+console.log("Built dist/ — point the registry at this dir to publish.");

package/templates/vanilla/manifest.json

@@ -0,0 +1,13 @@
+{
+  "id": "__EXT_ID__",
+  "name": "__EXT_NAME__",
+  "version": "1.0.0",
+  "description": "__EXT_NAME__ — a Struxa extension.",
+  "struxaApi": "^1.0.0",
+  "permissions": ["api:protected"],
+  "ui": {
+    "pages": [
+      { "route": "/__EXT_ID__", "section": "panel", "label": "__EXT_NAME__", "icon": "Boxes" }
+    ]
+  }
+}

package/templates/vanilla/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "__EXT_ID__",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "__EXT_NAME__ — a Struxa extension (vanilla JS).",
+  "scripts": {
+    "build": "node build.mjs"
+  },
+  "dependencies": {
+    "@struxa/extension-sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.24.0"
+  }
+}

package/templates/vanilla/server/index.js

@@ -0,0 +1,22 @@
+/**
+ * Server entry — plain ESM, imports nothing (runs from the data volume). The
+ * capability-scoped `ctx` is the only sanctioned host surface.
+ */
+export default {
+  async register(ctx) {
+    ctx.logger.info("__EXT_ID__ registered", { version: ctx.version });
+
+    const pp = ctx.procedures.protectedProcedure;
+    const router = pp
+      ? {
+          ping: pp.handler(({ context }) => ({
+            ok: true,
+            ts: Date.now(),
+            user: context?.session?.user?.id ?? null,
+          })),
+        }
+      : {};
+
+    return { router };
+  },
+};

package/templates/vanilla/src/index.html

@@ -0,0 +1,34 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>__EXT_NAME__</title>
+    <style>
+      body {
+        margin: 0;
+        padding: 24px;
+        font-family: ui-sans-serif, system-ui, sans-serif;
+        background: var(--background, #0b0b0c);
+        color: var(--foreground, #e7e7e9);
+      }
+      .card {
+        max-width: 640px;
+        padding: 20px;
+        border-radius: 12px;
+        border: 1px solid var(--border, #2a2a2e);
+        background: var(--card, #141416);
+      }
+      pre { background: var(--muted, #1b1b1f); padding: 12px; border-radius: 8px; }
+    </style>
+  </head>
+  <body>
+    <div class="card">
+      <h1 style="font-size:18px;margin:0 0 4px">__EXT_NAME__</h1>
+      <p id="who" style="font-size:13px;color:var(--muted-foreground,#9a9aa2)">…</p>
+      <button id="ping">Call ping</button>
+      <pre id="out">Ready.</pre>
+    </div>
+    <script type="module" src="./bundle.js"></script>
+  </body>
+</html>

package/templates/vanilla/src/main.js

@@ -0,0 +1,23 @@
+import { createBridge, createHostClient } from "@struxa/extension-sdk/client";
+
+// Host bridge: theme mirroring, session context, auto-resize, toast/navigate.
+const bridge = createBridge({
+  autoResize: true,
+  onInit: (ctx) => {
+    document.getElementById("who").textContent = `Signed in as ${ctx.session.userId ?? "—"}`;
+  },
+});
+
+// Host API client (same-origin, cookie-authed).
+const client = createHostClient();
+
+document.getElementById("ping").addEventListener("click", async () => {
+  const out = document.getElementById("out");
+  try {
+    const res = await client.ext["__EXT_ID__"].ping();
+    out.textContent = JSON.stringify(res, null, 2);
+    bridge.toast("success", "pong");
+  } catch (err) {
+    out.textContent = `error: ${String(err)}`;
+  }
+});