@botonic/nx-plugin 2.23.0

package/src/generators/custom-message/generator.js

@@ -0,0 +1,235 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var generator_exports = {};
+__export(generator_exports, {
+  default: () => generator_default
+});
+module.exports = __toCommonJS(generator_exports);
+var import_devkit = require("@nx/devkit");
+var import_bot_app_utils = require("../shared/bot-app-utils");
+const MODULE_DIR = __dirname;
+function normalizeOptions(tree, options) {
+  const { projectRoot, sourceRoot } = (0, import_bot_app_utils.validateBotAppProject)(
+    tree,
+    options.project
+  );
+  const paths = (0, import_bot_app_utils.resolveStandardPaths)(sourceRoot);
+  const name = (0, import_devkit.names)(options.name);
+  const fileName = name.fileName;
+  const className = name.className;
+  const propertyName = name.propertyName;
+  const constantName = name.constantName.toUpperCase();
+  const customMessagesPath = options.directory ? `${sourceRoot}/client/custom-messages/${options.directory}` : `${sourceRoot}/client/custom-messages`;
+  return {
+    ...options,
+    projectName: options.project,
+    projectRoot,
+    fileName,
+    className,
+    propertyName,
+    constantName,
+    customMessagesPath,
+    constantsPath: paths.constantsPath,
+    actionsPath: paths.actionsPath,
+    routesPath: paths.routesPath
+  };
+}
+function addFilesToProject(tree, options) {
+  const name = (0, import_devkit.names)(options.name);
+  const templateOptions = {
+    ...options,
+    ...name,
+    name: name.fileName
+    // __name__ in filenames must be kebab-case
+  };
+  (0, import_devkit.generateFiles)(
+    tree,
+    (0, import_devkit.joinPathFragments)(MODULE_DIR, "files"),
+    options.customMessagesPath,
+    templateOptions
+  );
+  if (options.skipTests) {
+    const testFilePath = `${options.customMessagesPath}/${options.fileName}.spec.tsx`;
+    if (tree.exists(testFilePath)) {
+      tree.delete(testFilePath);
+    }
+  }
+  if (options.skipAction) {
+    const actionPath = `${options.customMessagesPath}/${options.fileName}-output.ts`;
+    if (tree.exists(actionPath)) {
+      tree.delete(actionPath);
+    }
+  } else {
+    const sourceActionPath = `${options.customMessagesPath}/${options.fileName}-output.ts`;
+    const targetActionPath = `${options.actionsPath}/${options.fileName}.ts`;
+    if (tree.exists(sourceActionPath)) {
+      const content = tree.read(sourceActionPath, "utf-8");
+      tree.write(targetActionPath, content);
+      tree.delete(sourceActionPath);
+    }
+  }
+}
+function updateCustomMessagesIndex(tree, options) {
+  const indexPath = `${options.customMessagesPath}/index.ts`;
+  if (!tree.exists(indexPath)) {
+    tree.write(
+      indexPath,
+      `import { CUSTOM_MESSAGE_TYPES } from '../../shared/constants'
+
+export const customMessages = {
+  [CUSTOM_MESSAGE_TYPES.${options.constantName}]: ${options.className},
+}
+`
+    );
+    return;
+  }
+  const content = tree.read(indexPath, "utf-8");
+  const lines = content.split("\n");
+  const importStatement = `import { ${options.className} } from './${options.directory ? options.directory + "/" : ""}${options.fileName}'`;
+  let importInsertIndex = 0;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].startsWith("import")) {
+      importInsertIndex = i + 1;
+    } else if (lines[i].trim() === "" && importInsertIndex > 0) {
+      break;
+    }
+  }
+  lines.splice(importInsertIndex, 0, importStatement);
+  const exportLineIndex = lines.findIndex(
+    (line) => line.includes("export const customMessages")
+  );
+  if (exportLineIndex !== -1) {
+    let braceIndex = exportLineIndex;
+    while (braceIndex < lines.length && !lines[braceIndex].includes("{")) {
+      braceIndex++;
+    }
+    if (braceIndex < lines.length) {
+      const braceLine = lines[braceIndex];
+      if (braceLine.trim() === "{" || braceLine.includes("{}")) {
+        const newEntry = `  [CUSTOM_MESSAGE_TYPES.${options.constantName}]: ${options.className},`;
+        if (braceLine.includes("{}")) {
+          lines[braceIndex] = braceLine.replace("{}", `{
+${newEntry}
+}`);
+        } else {
+          lines.splice(braceIndex + 1, 0, newEntry);
+        }
+      } else {
+        let closingBraceIndex = braceIndex;
+        let braceCount = 0;
+        for (let i = braceIndex; i < lines.length; i++) {
+          for (const char of lines[i]) {
+            if (char === "{") braceCount++;
+            if (char === "}") braceCount--;
+          }
+          if (braceCount === 0) {
+            closingBraceIndex = i;
+            break;
+          }
+        }
+        const newEntry = `  [CUSTOM_MESSAGE_TYPES.${options.constantName}]: ${options.className},`;
+        lines.splice(closingBraceIndex, 0, newEntry);
+      }
+    }
+  }
+  tree.write(indexPath, lines.join("\n"));
+}
+function updateConstantsFile(tree, options) {
+  if (!tree.exists(options.constantsPath)) {
+    tree.write(
+      options.constantsPath,
+      `export const CUSTOM_MESSAGE_TYPES = {
+  ${options.constantName}: '${options.fileName}',
+} as const
+
+export const WEBVIEWS = {
+  // Add your webviews here
+} as const
+
+export const PAYLOADS = {
+  // Add your payloads here
+} as const
+`
+    );
+    return;
+  }
+  (0, import_bot_app_utils.addConstEntry)(
+    tree,
+    options.constantsPath,
+    "CUSTOM_MESSAGE_TYPES",
+    options.constantName,
+    options.fileName
+  );
+}
+function updateActionsIndex(tree, options) {
+  if (options.skipAction) {
+    return;
+  }
+  (0, import_bot_app_utils.addExportToIndex)(
+    tree,
+    `${options.actionsPath}/index.ts`,
+    `export * from './${options.fileName}'`
+  );
+}
+function updateRoutes(tree, options) {
+  if (options.skipAction) {
+    return;
+  }
+  const actionImport = `${options.propertyName}Output`;
+  (0, import_bot_app_utils.addActionImportToRoutes)(tree, options.routesPath, actionImport);
+  (0, import_bot_app_utils.insertRouteBeforeFlowBuilder)(tree, options.routesPath, [
+    `    {`,
+    `      text: '${options.fileName}',`,
+    `      action: async () => await ${actionImport}(botContext),`,
+    `    },`
+  ]);
+}
+async function generator_default(tree, options) {
+  console.log(`Creating custom message: ${options.name}`);
+  const normalizedOptions = normalizeOptions(tree, options);
+  console.log(`Project: ${normalizedOptions.projectName}`);
+  console.log(`Location: ${normalizedOptions.customMessagesPath}`);
+  addFilesToProject(tree, normalizedOptions);
+  updateConstantsFile(tree, normalizedOptions);
+  updateCustomMessagesIndex(tree, normalizedOptions);
+  updateActionsIndex(tree, normalizedOptions);
+  updateRoutes(tree, normalizedOptions);
+  await (0, import_devkit.formatFiles)(tree);
+  console.log(
+    `
+Successfully created custom message: ${normalizedOptions.className}`
+  );
+  console.log(`Next steps:`);
+  console.log(
+    `  1. Customize the component in: ${normalizedOptions.customMessagesPath}/${normalizedOptions.fileName}.tsx`
+  );
+  if (!options.skipAction) {
+    console.log(
+      `  2. Update the action in: ${normalizedOptions.actionsPath}/${normalizedOptions.fileName}.ts`
+    );
+    console.log(
+      `  3. Test by typing '${normalizedOptions.fileName}' in the webchat`
+    );
+  }
+  if (!options.skipTests) {
+    console.log(
+      `  4. Update the tests in: ${normalizedOptions.customMessagesPath}/${normalizedOptions.fileName}.spec.tsx`
+    );
+  }
+}

package/src/generators/custom-message/schema.d.ts

@@ -0,0 +1,7 @@
+export interface CustomMessageGeneratorSchema {
+    name: string;
+    project: string;
+    directory?: string;
+    skipTests?: boolean;
+    skipAction?: boolean;
+}

package/src/generators/custom-message/schema.js

@@ -0,0 +1,16 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var schema_exports = {};
+module.exports = __toCommonJS(schema_exports);

package/src/generators/custom-message/schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "cli": "nx",
+  "$id": "CustomMessage",
+  "title": "Create a custom message component for Botonic",
+  "description": "Generate a custom message component with automatic registration in the bot application.",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The name of the custom message component.",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "What name would you like to use for the custom message?",
+      "pattern": "^[a-zA-Z].*$"
+    },
+    "project": {
+      "type": "string",
+      "description": "The name of the botonic project to add the custom message to.",
+      "x-prompt": "Which botonic project should this custom message be added to?",
+      "$default": {
+        "$source": "projectName"
+      }
+    },
+    "directory": {
+      "type": "string",
+      "description": "The directory within custom-messages to create the component (optional).",
+      "alias": "dir"
+    },
+    "skipTests": {
+      "type": "boolean",
+      "description": "Skip generating test files.",
+      "default": false
+    },
+    "skipAction": {
+      "type": "boolean",
+      "description": "Skip generating an example action that uses this custom message.",
+      "default": false
+    }
+  },
+  "required": ["name", "project"]
+}

package/src/generators/preset/files/.cursor/commands/update-bot.md

@@ -0,0 +1,5 @@
+# Update Botonic Bot
+
+Applies pending bot-app migrations from `.botonic/pending-bot-migrations.json` to a single bot.
+
+Follow the full workflow in: `node_modules/@botonic/nx-plugin/src/cursor-commands/update-bot.md`

package/src/generators/preset/files/.cursor/commands/update-botonic.md

@@ -0,0 +1,5 @@
+# Update Botonic Workspace
+
+Updates the Botonic plugin to the latest version and queues pending bot-app migrations.
+
+Follow the full workflow in: `node_modules/@botonic/nx-plugin/src/cursor-commands/update-botonic.md`

package/src/generators/preset/files/.cursor/scripts/update-bot/discover-bots.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# Discovers botonic bot apps and their current versions.
+# Uses nx show projects with tag:botonic:bot-app filter.
+# Run from workspace root. Output: JSON array of { name, path, version }.
+# Usage: bash .cursor/scripts/update-bot/discover-bots.sh
+
+set -euo pipefail
+
+# Ensure we're in workspace root (contains apps/ or nx.json)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+GIT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+REL_ROOT="$(cd "$SCRIPT_DIR/../../../" && pwd)"
+if [[ -n "$GIT_ROOT" ]] && [[ -f "$GIT_ROOT/nx.json" ]]; then
+  ROOT="$GIT_ROOT"
+elif [[ -d "$REL_ROOT/apps" ]] || [[ -f "$REL_ROOT/nx.json" ]]; then
+  ROOT="$REL_ROOT"
+else
+  ROOT="${GIT_ROOT:-.}"
+fi
+cd "$ROOT"
+
+# List bot apps via nx (tag:botonic:bot-app)
+# Nx may print plugin messages to stdout; use tail -1 to get JSON only
+names=$(npx nx show projects --projects "tag:botonic:bot-app" --json 2>/dev/null | tail -1 || echo "[]")
+if [[ "$names" == "[]" ]] || [[ -z "$names" ]]; then
+  echo "[]"
+  exit 0
+fi
+
+bots='[]'
+for name in $(echo "$names" | node -e "
+  try {
+    const arr = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf8'));
+    (Array.isArray(arr) ? arr : []).forEach(n => console.log(n));
+  } catch {}
+"); do
+  [[ -z "$name" ]] && continue
+
+  path="$name"
+  if root=$(npx nx show project "$name" --json 2>/dev/null | tail -1 | node -e "try { const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); process.stdout.write(d.root||''); } catch {}"); then
+    [[ -n "$root" ]] && path="$root"
+  else
+    path="apps/$name"
+  fi
+
+  version="unknown"
+  pkg="$ROOT/$path/package.json"
+  if [[ -f "$pkg" ]]; then
+    version=$(node -e "
+      try {
+        const p = require('$pkg');
+        const v = p.dependencies?.['@botonic/core']
+              || p.dependencies?.['@botonic/webchat-react']
+              || 'unknown';
+        console.log(String(v).replace(/^[\^~]/, ''));
+      } catch { console.log('unknown'); }
+    " 2>/dev/null || echo "unknown")
+  fi
+
+  bots=$(echo "$bots" | node -e "
+    const b = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf8'));
+    b.push({ name: process.argv[1], path: process.argv[2], version: process.argv[3] });
+    console.log(JSON.stringify(b, null, 2));
+  " "$name" "$path" "$version")
+done
+
+echo "$bots"

package/src/generators/preset/files/.cursor/scripts/update-bot/find-migration-guides.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# Finds <name>.migration.md files for migrations between two versions.
+# Reads node_modules/@botonic/nx-plugin/migrations.json (published, real semver).
+# Usage: find-migration-guides.sh <from-version> <to-version>
+# Output: JSON array of { version, migrations: [{ name, migrationGuide }] } grouped by unique version
+
+set -euo pipefail
+
+FROM_VERSION="${1:?Usage: find-migration-guides.sh <from> <to>}"
+TO_VERSION="${2:?Usage: find-migration-guides.sh <from> <to>}"
+
+# Run from workspace root
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+GIT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+REL_ROOT="$(cd "$SCRIPT_DIR/../../../" && pwd)"
+if [[ -n "$GIT_ROOT" ]] && [[ -f "$GIT_ROOT/nx.json" ]]; then
+  ROOT="$GIT_ROOT"
+elif [[ -f "$REL_ROOT/nx.json" ]] || [[ -f "$REL_ROOT/node_modules/@botonic/nx-plugin/migrations.json" ]]; then
+  ROOT="$REL_ROOT"
+else
+  ROOT="${GIT_ROOT:-$REL_ROOT}"
+fi
+cd "$ROOT"
+
+MIGRATIONS_JSON="node_modules/@botonic/nx-plugin/migrations.json"
+MIGRATIONS_DIR="node_modules/@botonic/nx-plugin/src/migrations"
+
+if [ ! -f "$MIGRATIONS_JSON" ]; then
+  echo '{"error": "migrations.json not found. Run pnpm install first."}' >&2
+  exit 1
+fi
+
+node -e "
+  const fs = require('fs');
+  const path = require('path');
+  let semver;
+  try { semver = require('semver'); } catch { semver = null; }
+
+  const mj = JSON.parse(fs.readFileSync('$MIGRATIONS_JSON', 'utf8'));
+  const generators = mj.generators || {};
+  const from = '$FROM_VERSION';
+  const to = '$TO_VERSION';
+  const migrationsDir = path.resolve('$MIGRATIONS_DIR');
+
+  const valid = (v) => semver ? semver.valid(v) : /^\\d+\\.\\d+\\.\\d+$/.test(v);
+  const gt = (a, b) => semver ? semver.gt(a, b) : a !== b;
+  const lte = (a, b) => semver ? semver.lte(a, b) : true;
+  const compare = (a, b) => semver ? semver.compare(a, b) : 0;
+
+  const entries = Object.entries(generators)
+    .filter(([, cfg]) => valid(cfg.version) && gt(cfg.version, from) && lte(cfg.version, to))
+    .sort(([, a], [, b]) => compare(a.version, b.version));
+
+  const byVersion = new Map();
+  for (const [name, cfg] of entries) {
+    const guideFile = path.join(migrationsDir, name, \`\${name}.migration.md\`);
+    const migrationGuide = fs.existsSync(guideFile) ? guideFile : null;
+    if (!byVersion.has(cfg.version)) {
+      byVersion.set(cfg.version, []);
+    }
+    byVersion.get(cfg.version).push({ name, migrationGuide });
+  }
+
+  const results = Array.from(byVersion.entries()).map(([version, migrations]) => ({
+    version,
+    migrations
+  }));
+
+  console.log(JSON.stringify(results, null, 2));
+"

package/src/generators/preset/files/.cursor/skills/botonic-action/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: botonic-action
+description: Scaffold and implement a Botonic bot action using the Nx generator, then guide implementation. Use when the user says "create action", "add action", "new action", "generate action", or wants to handle a specific message, intent, or conversation route in a Botonic bot project.
+---
+
+# Botonic Action
+
+Scaffold a server-side action, wire its route, and help implement its logic.
+
+## Workflow
+
+### Step 1 — Gather inputs
+
+Collect from context or ask:
+
+- **`name`** (required): kebab-case name, e.g. `order-status`, `greet-user`
+- **`project`** (required): Nx project name of the bot app, e.g. `my-bot`
+- **`routeMatcher`** (required unless skipping route): the text pattern that triggers this action. Ask the user explicitly — e.g. _"What message or phrase should trigger this action?"_. Defaults to the kebab-case name if omitted.
+- **`skipRoute`** (optional): `true` only if the action should not be wired into `routes.ts` (e.g. internal helper, called by another action)
+- **`skipTests`** (optional): `true` to skip spec file generation
+
+### Step 2 — Run the generator
+
+```bash
+pnpm nx g @botonic/nx-plugin:action --name=<name> --project=<project>
+```
+
+With route matcher:
+
+```bash
+pnpm nx g @botonic/nx-plugin:action order-status --project my-bot --routeMatcher "order status"
+```
+
+Without route wiring (internal helpers):
+
+```bash
+pnpm nx g @botonic/nx-plugin:action send-confirmation --project my-bot --skipRoute
+```
+
+### Step 3 — Review the generated route
+
+Open `src/server/bot/routes.ts` and show the user the entry that was inserted:
+
+```typescript
+{
+  text: 'order-status',
+  action: async () => await OrderStatus(botContext),
+},
+```
+
+Confirm with the user:
+
+- Is the `text` matcher correct? Does it match what the bot will receive?
+- Should it be a regex? e.g. `/^order.*/i`
+- Should it match on `payload` or `type` instead of `text`?
+
+If the matcher needs changing, edit `routes.ts` directly:
+
+```typescript
+// Regex matcher
+{ text: /^order.*/i, action: async () => await OrderStatus(botContext) },
+
+// Payload matcher
+{ payload: 'ORDER_STATUS', action: async () => await OrderStatus(botContext) },
+
+// Message type matcher
+{ type: 'postback', payload: 'ORDER_STATUS', action: async () => await OrderStatus(botContext) },
+```
+
+### Step 4 — Ask what to implement
+
+If not already clear from context, ask: "What should this action do?"
+
+### Step 5 — Implement the action
+
+#### Building blocks: `sendMessage` and `BotServerMessageFactory`
+
+Every action receives `BotContext` as its argument. The two key pieces for sending responses are:
+
+- **`sendMessage`** — async function from `BotContext`. Call it once per message you want to send. You can call it multiple times to send a sequence of messages.
+- **`BotServerMessageFactory`** — imported from `@botonic/shared`. Use its factory methods to build every message; never construct raw message objects by hand.
+
+```typescript
+import { BotContext, BotServerMessageFactory } from '@botonic/shared'
+
+export async function MyAction({ sendMessage }: BotContext) {
+  await sendMessage(BotServerMessageFactory.createText({ text: 'Hello!' }))
+  return { status: 200, response: 'OK' }
+}
+```
+
+#### Expected return value
+
+Every action **must** return `{ status: number, response: string }`. Use `200 / 'OK'` for success and a meaningful status code + message for errors.
+
+```typescript
+return { status: 200, response: 'OK' } // success
+return { status: 400, response: 'Bad Request' } // validation error
+```
+
+#### Factory methods
+
+**Text message**
+
+```typescript
+await sendMessage(BotServerMessageFactory.createText({ text: 'Your order is on the way!' }))
+```
+
+**Button message** — build each button with the appropriate factory method; never pass raw button objects
+
+```typescript
+await sendMessage(
+  BotServerMessageFactory.createButtonMessage({
+    text: 'Need help with your order?',
+    buttons: [BotServerMessageFactory.createPostbackButton({ title: 'Order status', payload: 'ORDER_STATUS' }), BotServerMessageFactory.createUrlButton({ title: 'Visit website', url: 'https://example.com' }), BotServerMessageFactory.createWebviewButton({ title: 'Open form', webview: WEBVIEWS.ORDER_FORM }, session)],
+  })
+)
+```
+
+**Custom message**
+
+```typescript
+await sendMessage(
+  BotServerMessageFactory.createCustom({
+    name: CUSTOM_MESSAGE_TYPES.ORDER_CARD,
+    props: { orderId, status },
+  })
+)
+```
+
+**Conditional logic with early return**
+
+```typescript
+export async function OrderStatus({ sendMessage, request }: BotContext) {
+  const { payload } = request
+  if (!payload?.orderId) {
+    await sendMessage(BotServerMessageFactory.createText({ text: 'Please provide an order ID.' }))
+    return { status: 400, response: 'Bad Request' }
+  }
+  // fetch order and respond...
+  return { status: 200, response: 'OK' }
+}
+```
+
+**Calling an external API**
+
+Keep HTTP calls in a dedicated service file; import and call it from the action:
+
+```typescript
+import { orderService } from '../../services/order-service'
+
+export async function OrderStatus({ sendMessage, request }: BotContext) {
+  const order = await orderService.getOrder(request.payload?.orderId)
+  await sendMessage(BotServerMessageFactory.createText({ text: order.statusMessage }))
+  return { status: 200, response: 'OK' }
+}
+```
+
+## Options reference
+
+| Option         | Default         | Notes                            |
+| -------------- | --------------- | -------------------------------- |
+| `name`         | —               | Required. kebab-case recommended |
+| `project`      | —               | Required. Nx project name        |
+| `routeMatcher` | kebab-case name | The `text` field in `routes.ts`  |
+| `skipRoute`    | `false`         | Omit route entry in `routes.ts`  |
+| `skipTests`    | `false`         | Omit `<name>.spec.ts`            |