cap-copilot-sdk 0.1.0

package/cds-plugin.js

@@ -0,0 +1,67 @@
+'use strict';
+// Resolve @sap/cds from the project root (process.cwd()) to get the same
+// singleton instance that cds watch uses — not a duplicate from this package's location.
+const cdsPath = require.resolve('@sap/cds', { paths: [process.cwd()] });
+const cds = require(cdsPath);
+const { extract, extractFromServices } = require('./src/SchemaExtractor');
+const { scan } = require('./src/ProjectScanner');
+const { register } = require('./src/Registrar');
+
+const cfg = cds.env.requires?.['btp-copilot'] ?? {};
+const {
+  backendUrl = process.env.BTP_COPILOT_URL,
+  appId     = process.env.BTP_COPILOT_APP_ID,
+  appName,
+  serviceUrl,
+  token             = process.env.BTP_COPILOT_TOKEN,
+  includeProjectFiles = true,
+  includeHandlers     = true,
+  includeViews        = true,
+} = cfg;
+
+const log = (...args) => console.log('\x1b[36m[btp-copilot]\x1b[0m', ...args);
+const warn = (...args) => console.warn('\x1b[33m[btp-copilot]\x1b[0m', ...args);
+const err  = (...args) => console.error('\x1b[31m[btp-copilot]\x1b[0m', ...args);
+
+if (!backendUrl || !appId) {
+  log('No backendUrl/appId in cds.requires["btp-copilot"] — skipping registration.');
+} else if (!/^[a-zA-Z0-9_-]+$/.test(appId)) {
+  warn(`appId "${appId}" contains invalid characters. Use only letters, digits, _ and -.`);
+} else {
+  cds.on('served', async (services) => {
+    try {
+      log(`Collecting context for app "${appId}"…`);
+      const allDocs = [];
+
+      const schemaDocs = extract(cds, { serviceUrl });
+      allDocs.push(...schemaDocs);
+      log(`  + ${schemaDocs.length} schema documents`);
+
+      const serviceList = Array.isArray(services) ? services : Object.values(services ?? {});
+      const runtimeDocs = extractFromServices(serviceList);
+      allDocs.push(...runtimeDocs);
+      if (runtimeDocs.length) log(`  + ${runtimeDocs.length} runtime service documents`);
+
+      if (includeProjectFiles) {
+        const projectRoot = cds.env.root ?? process.cwd();
+        const fileDocs = scan(projectRoot, { includeHandlers, includeViews });
+        allDocs.push(...fileDocs);
+        log(`  + ${fileDocs.length} project file documents`);
+      }
+
+      if (!allDocs.length) { log('No documents to register.'); return; }
+
+      const toSend = Math.min(allDocs.length, 50);
+      log(`Registering ${toSend} of ${allDocs.length} documents with backend…`);
+
+      const ok = await register({ backendUrl, appId, appName: appName ?? appId, serviceUrl, documents: allDocs, token });
+      if (ok) {
+        log(`\x1b[32m✔ App "${appId}" registered — chatbot is now context-aware!\x1b[0m`);
+      } else {
+        warn(`✘ Registration failed. Backend: ${backendUrl} — start your chatbot backend to enable AI answers.`);
+      }
+    } catch (e) {
+      err('Registration error —', e.message);
+    }
+  });
+}

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "cap-copilot-sdk",
+  "version": "0.1.0",
+  "description": "CDS plugin: auto-extracts entity schemas, relationships, project structure and registers with BTP Copilot backend",
+  "main": "cds-plugin.js",
+  "files": ["src", "cds-plugin.js"],
+  "keywords": ["sap", "cap", "cds", "btp", "ai", "chatbot", "plugin"],
+  "license": "MIT",
+  "peerDependencies": {
+    "@sap/cds": ">=7.0.0"
+  }
+}

package/src/ProjectScanner.js

@@ -0,0 +1,373 @@
+"use strict";
+/**
+ * ProjectScanner — reads the CAP project folder structure and source files,
+ * then produces RAG-ready documents for the BTP Copilot backend.
+ *
+ * What it reads (relative to the project root):
+ *   db/          — CDS schema files (.cds)
+ *   srv/         — CDS service definitions (.cds) and handlers (.js / .ts)
+ *   app/         — Fiori XML views (.xml), manifests (manifest.json),
+ *                  i18n files (i18n.properties), annotations (.cds / .xml)
+ *   package.json — App name, description, version, cds config
+ *   .cdsrc.json  — Additional CDS configuration
+ *
+ * Each file is turned into one plain-text document.
+ * Large files are trimmed to MAX_LINES lines so the backend's 50-doc limit is
+ * respected without losing critical schema information.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const MAX_LINES = 300; // max content lines per document
+const MAX_HANDLER_LINES = 150; // handlers are trimmed more aggressively
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "@types",
+  "gen",
+  "mta_archives",
+]);
+
+/**
+ * @param {string} projectRoot  Absolute path to the CAP project root
+ * @param {object} [opts]
+ * @param {boolean} [opts.includeHandlers=true]  Include srv/*.js/ts handler content
+ * @param {boolean} [opts.includeViews=true]     Include app XML view content
+ * @returns {{ title: string, content: string }[]}
+ */
+function scan(projectRoot, opts = {}) {
+  const { includeHandlers = true, includeViews = true } = opts;
+
+  const docs = [];
+
+  // ── 1. Folder structure overview ───────────────────────────────────────────
+  const tree = _buildTree(projectRoot, 3);
+  if (tree.length > 1) {
+    docs.push({
+      title: "Project folder structure",
+      content: ["Project root: " + projectRoot, ...tree].join("\n"),
+    });
+  }
+
+  // ── 2. package.json ────────────────────────────────────────────────────────
+  const pkgDoc = _readPackageJson(projectRoot);
+  if (pkgDoc) docs.push(pkgDoc);
+
+  // ── 3. db/ — schema CDS files ─────────────────────────────────────────────
+  const dbDir = path.join(projectRoot, "db");
+  if (_isDir(dbDir)) {
+    const cdsFiles = _findFiles(dbDir, [".cds"], 2);
+    for (const filePath of cdsFiles) {
+      const rel = path.relative(projectRoot, filePath).replace(/\\/g, "/");
+      const content = _readTrimmed(filePath, MAX_LINES);
+      if (content) {
+        docs.push({ title: `Schema file: ${rel}`, content });
+      }
+    }
+  }
+
+  // ── 4. srv/ — service definitions and handlers ────────────────────────────
+  const srvDir = path.join(projectRoot, "srv");
+  if (_isDir(srvDir)) {
+    // CDS service definitions
+    const cdsFiles = _findFiles(srvDir, [".cds"], 2);
+    for (const filePath of cdsFiles) {
+      const rel = path.relative(projectRoot, filePath).replace(/\\/g, "/");
+      const content = _readTrimmed(filePath, MAX_LINES);
+      if (content) {
+        docs.push({ title: `Service definition: ${rel}`, content });
+      }
+    }
+
+    // Handlers (JS / TS)
+    if (includeHandlers) {
+      const handlerFiles = _findFiles(srvDir, [".js", ".ts", ".mjs"], 2);
+      for (const filePath of handlerFiles) {
+        const rel = path.relative(projectRoot, filePath).replace(/\\/g, "/");
+        const content = _readTrimmed(filePath, MAX_HANDLER_LINES);
+        if (content) {
+          docs.push({ title: `Service handler: ${rel}`, content });
+        }
+      }
+    }
+  }
+
+  // ── 5. app/ — Fiori UI files ───────────────────────────────────────────────
+  const appDir = path.join(projectRoot, "app");
+  if (_isDir(appDir)) {
+    // manifest.json — Fiori app metadata
+    const manifestFiles = _findFilesByName(appDir, "manifest.json", 3);
+    for (const filePath of manifestFiles) {
+      const rel = path.relative(projectRoot, filePath).replace(/\\/g, "/");
+      const doc = _readManifest(filePath, rel);
+      if (doc) docs.push(doc);
+    }
+
+    // Annotation CDS files
+    const annotationCds = _findFiles(appDir, [".cds"], 3);
+    for (const filePath of annotationCds) {
+      const rel = path.relative(projectRoot, filePath).replace(/\\/g, "/");
+      const content = _readTrimmed(filePath, MAX_LINES);
+      if (content) {
+        docs.push({ title: `UI annotation: ${rel}`, content });
+      }
+    }
+
+    // XML views (abridged — just the first MAX_LINES lines)
+    if (includeViews) {
+      const xmlFiles = _findFiles(appDir, [".xml"], 4).filter(
+        (f) => !f.includes("node_modules"),
+      );
+      for (const filePath of xmlFiles.slice(0, 10)) {
+        // cap at 10 XML files
+        const rel = path.relative(projectRoot, filePath).replace(/\\/g, "/");
+        const content = _readTrimmed(filePath, MAX_LINES);
+        if (content) {
+          docs.push({ title: `UI view: ${rel}`, content });
+        }
+      }
+    }
+
+    // i18n / properties files (list of labels)
+    const i18nFiles = _findFilesByName(appDir, "i18n.properties", 3).concat(
+      _findFilesByName(appDir, "i18n_en.properties", 3),
+    );
+    for (const filePath of i18nFiles.slice(0, 3)) {
+      const rel = path.relative(projectRoot, filePath).replace(/\\/g, "/");
+      const content = _readTrimmed(filePath, 100);
+      if (content) {
+        docs.push({ title: `UI labels (i18n): ${rel}`, content });
+      }
+    }
+  }
+
+  return docs;
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+function _isDir(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function _isFile(p) {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function _readTrimmed(filePath, maxLines) {
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const lines = raw.split("\n");
+    const trimmed = lines.slice(0, maxLines);
+    if (lines.length > maxLines) {
+      trimmed.push(`... (${lines.length - maxLines} more lines omitted)`);
+    }
+    return trimmed.join("\n").trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build a directory tree string up to `depth` levels.
+ */
+function _buildTree(dir, depth, prefix = "") {
+  const lines = [];
+  if (depth < 0) return lines;
+
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return lines;
+  }
+
+  const filtered = entries
+    .filter((e) => !SKIP_DIRS.has(e) && !e.startsWith("."))
+    .sort((a, b) => {
+      // dirs first
+      const aIsDir = _isDir(path.join(dir, a));
+      const bIsDir = _isDir(path.join(dir, b));
+      if (aIsDir && !bIsDir) return -1;
+      if (!aIsDir && bIsDir) return 1;
+      return a.localeCompare(b);
+    });
+
+  for (let i = 0; i < filtered.length; i++) {
+    const entry = filtered[i];
+    const isLast = i === filtered.length - 1;
+    const connector = isLast ? "└── " : "├── ";
+    const fullPath = path.join(dir, entry);
+    const isDir = _isDir(fullPath);
+
+    lines.push(prefix + connector + entry + (isDir ? "/" : ""));
+
+    if (isDir && depth > 0) {
+      const childPrefix = prefix + (isLast ? "    " : "│   ");
+      lines.push(..._buildTree(fullPath, depth - 1, childPrefix));
+    }
+  }
+
+  return lines;
+}
+
+function _findFiles(dir, extensions, maxDepth, _depth = 0) {
+  const results = [];
+  if (_depth > maxDepth) return results;
+
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return results;
+  }
+
+  for (const entry of entries) {
+    if (SKIP_DIRS.has(entry) || entry.startsWith(".")) continue;
+    const fullPath = path.join(dir, entry);
+    try {
+      const stat = fs.statSync(fullPath);
+      if (stat.isDirectory()) {
+        results.push(..._findFiles(fullPath, extensions, maxDepth, _depth + 1));
+      } else if (extensions.some((ext) => entry.endsWith(ext))) {
+        results.push(fullPath);
+      }
+    } catch {
+      /* skip inaccessible */
+    }
+  }
+  return results;
+}
+
+function _findFilesByName(dir, name, maxDepth, _depth = 0) {
+  const results = [];
+  if (_depth > maxDepth) return results;
+
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return results;
+  }
+
+  for (const entry of entries) {
+    if (SKIP_DIRS.has(entry) || entry.startsWith(".")) continue;
+    const fullPath = path.join(dir, entry);
+    try {
+      const stat = fs.statSync(fullPath);
+      if (stat.isDirectory()) {
+        results.push(..._findFilesByName(fullPath, name, maxDepth, _depth + 1));
+      } else if (entry === name) {
+        results.push(fullPath);
+      }
+    } catch {
+      /* skip */
+    }
+  }
+  return results;
+}
+
+function _readPackageJson(projectRoot) {
+  const pkgPath = path.join(projectRoot, "package.json");
+  if (!_isFile(pkgPath)) return null;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    const lines = [
+      `Application: ${pkg.name ?? "unknown"}`,
+      `Version: ${pkg.version ?? "unknown"}`,
+    ];
+    if (pkg.description) lines.push(`Description: ${pkg.description}`);
+
+    // CDS configuration hints
+    const cdsConf = pkg.cds ?? {};
+    if (cdsConf.requires) {
+      const requires = Object.keys(cdsConf.requires).filter(
+        (k) => k !== "btp-copilot",
+      );
+      if (requires.length) lines.push(`CDS requires: ${requires.join(", ")}`);
+    }
+    if (cdsConf.features) {
+      lines.push(`CDS features: ${JSON.stringify(cdsConf.features)}`);
+    }
+
+    // Dependencies hint (just names, no versions — for context)
+    const deps = Object.keys({
+      ...(pkg.dependencies ?? {}),
+      ...(pkg.devDependencies ?? {}),
+    }).filter(
+      (d) =>
+        d.startsWith("@sap") || d.startsWith("hdb") || d.startsWith("@cap"),
+    );
+    if (deps.length) lines.push(`SAP dependencies: ${deps.join(", ")}`);
+
+    return {
+      title: "Application metadata (package.json)",
+      content: lines.join("\n"),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse a Fiori manifest.json into a concise summary document.
+ */
+function _readManifest(filePath, relPath) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    const lines = [`Fiori app manifest: ${relPath}`];
+
+    const sapApp = raw["sap.app"] ?? {};
+    if (sapApp.id) lines.push(`App ID: ${sapApp.id}`);
+    if (sapApp.title) lines.push(`Title: ${sapApp.title}`);
+    if (sapApp.description) lines.push(`Description: ${sapApp.description}`);
+    if (sapApp.type) lines.push(`Type: ${sapApp.type}`);
+
+    // Data sources
+    const dataSources = sapApp.dataSources ?? {};
+    for (const [dsName, ds] of Object.entries(dataSources)) {
+      lines.push(
+        `Data source "${dsName}": type=${ds.type ?? "OData"}, uri=${ds.uri ?? ""}`,
+      );
+    }
+
+    const sapUi5 = raw["sap.ui5"] ?? {};
+
+    // Routing targets
+    const routes = sapUi5.routing?.routes ?? [];
+    if (routes.length) {
+      const routeNames = routes.map((r) => r.name ?? r.pattern).filter(Boolean);
+      lines.push(`Routes: ${routeNames.join(", ")}`);
+    }
+
+    // Models
+    const models = sapUi5.models ?? {};
+    for (const [modelName, model] of Object.entries(models)) {
+      if (model.dataSource) {
+        lines.push(
+          `Model "${modelName}": bound to data source "${model.dataSource}"`,
+        );
+      }
+    }
+
+    return {
+      title: `Fiori app: ${sapApp.id ?? relPath}`,
+      content: lines.join("\n"),
+    };
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { scan };

package/src/Registrar.js

@@ -0,0 +1,74 @@
+"use strict";
+const https = require("https");
+const http = require("http");
+const { URL } = require("url");
+
+/**
+ * Register (or update) the app context documents with the BTP Copilot backend.
+ *
+ * POST /api/apps/register
+ * Body: { app_id, app_name, documents, replace }
+ *
+ * @param {{ backendUrl: string, appId: string, appName: string,
+ *           documents: {title:string, content:string}[],
+ *           token?: string }} opts
+ * @returns {Promise<boolean>}
+ */
+async function register(opts) {
+  const { backendUrl, appId, appName, documents, token } = opts;
+
+  // Backend allows max 50 documents — trim if needed
+  const docs = documents.slice(0, 50);
+
+  const url = new URL("/api/apps/register", backendUrl);
+  const body = JSON.stringify({
+    app_id: appId,
+    app_name: appName ?? appId,
+    documents: docs,
+    replace: true,
+  });
+
+  return new Promise((resolve) => {
+    const lib = url.protocol === "https:" ? https : http;
+    const headers = {
+      "Content-Type": "application/json",
+      "Content-Length": Buffer.byteLength(body),
+    };
+    if (token) headers["Authorization"] = `Bearer ${token}`;
+
+    const req = lib.request(
+      {
+        hostname: url.hostname,
+        port: url.port || (url.protocol === "https:" ? 443 : 80),
+        path: url.pathname + url.search,
+        method: "POST",
+        headers,
+        // Accept self-signed certs in dev environments
+        rejectUnauthorized: process.env.NODE_ENV !== "production",
+      },
+      (res) => {
+        let body = "";
+        res.on("data", (chunk) => (body += chunk));
+        res.on("end", () => {
+          const ok = res.statusCode >= 200 && res.statusCode < 300;
+          if (!ok) {
+            console.warn(
+              `[btp-copilot] Registration HTTP ${res.statusCode}: ${body.slice(0, 200)}`,
+            );
+          }
+          resolve(ok);
+        });
+      },
+    );
+
+    req.on("error", (err) => {
+      console.warn("[btp-copilot] Registration network error:", err.message);
+      resolve(false);
+    });
+
+    req.write(body);
+    req.end();
+  });
+}
+
+module.exports = { register };

package/src/SchemaExtractor.js

@@ -0,0 +1,266 @@
+"use strict";
+/**
+ * SchemaExtractor — reads the CDS compiled model and produces
+ * plain-text documents for RAG ingestion.
+ *
+ * Extracts:
+ *  - Each entity's fields, types, keys, and annotations
+ *  - Association and Composition relationships between entities
+ *  - Service definitions (which entities each service exposes)
+ *  - Application-level summary with OData query examples
+ *  - Runtime entity data via srv.entities (types, cardinalities)
+ */
+
+/**
+ * @param {import('@sap/cds')} cds
+ * @param {{ serviceUrl?: string }} [options]
+ * @returns {{ title: string, content: string }[]}
+ */
+function extract(cds, options = {}) {
+  const model = cds.model;
+  if (!model) return [];
+
+  const docs = [];
+  const serviceUrl = options.serviceUrl ?? "";
+  const defs = model.definitions ?? {};
+
+  // ── Collect entity definitions (skip SAP framework entities, deduplicate by short name) ──
+  const seenShortNames = new Set();
+  const entityDefs = Object.entries(defs).filter(([fqName, d]) => {
+    if (d.kind !== "entity") return false;
+    // Skip SAP common / framework entities
+    if (fqName.startsWith("sap.common.") || fqName.startsWith("cds.")) return false;
+    // Deduplicate: keep only the first occurrence of each short entity name
+    const shortName = fqName.split(".").pop();
+    if (seenShortNames.has(shortName)) return false;
+    seenShortNames.add(shortName);
+    return true;
+  });
+
+  for (const [fqName, def] of entityDefs) {
+    const shortName = fqName.split(".").pop();
+    const elements = def.elements ?? {};
+
+    const keys = [];
+    const fields = [];
+    const associations = [];
+    const compositions = [];
+    const enums = [];
+
+    for (const [elName, el] of Object.entries(elements)) {
+      if (elName.startsWith("_")) continue; // skip internal managed fields
+
+      const typeName = _shortType(el.type ?? el.name ?? "");
+
+      if (el.type === "cds.Composition") {
+        const target = _shortName(el.target ?? "");
+        const card = el.cardinality?.max === "*" ? "many" : "one";
+        compositions.push(`${elName} → ${target} (composition of ${card})`);
+      } else if (el.type === "cds.Association") {
+        const target = _shortName(el.target ?? "");
+        const card = el.cardinality?.max === "*" ? "many" : "one";
+        const fk = el.keys
+          ?.map((k) => k.ref?.join(".") ?? "")
+          .filter(Boolean)
+          .join(", ");
+        const fkStr = fk ? `, FK: ${fk}` : "";
+        associations.push(
+          `${elName} → ${target} (association to ${card}${fkStr})`,
+        );
+      } else if (el.key) {
+        keys.push(`${elName} (${typeName}, key)`);
+      } else {
+        const nullable = el.notNull ? "" : ", optional";
+        const maxLen = el.length ? `, maxLength: ${el.length}` : "";
+        // Detect enum values
+        if (el.enum) {
+          const vals = Object.entries(el.enum)
+            .map(([k, v]) => `${k}=${v?.val ?? k}`)
+            .join("|");
+          enums.push(`${elName}: ${typeName} [${vals}]${nullable}`);
+        } else {
+          fields.push(`${elName} (${typeName}${nullable}${maxLen})`);
+        }
+      }
+    }
+
+    const lines = [`Entity: ${shortName}`, `Fully qualified name: ${fqName}`];
+
+    if (serviceUrl) {
+      lines.push(`OData path: ${serviceUrl}/${shortName}`);
+      lines.push(`Count records: GET ${serviceUrl}/${shortName}/$count`);
+      lines.push(
+        `Filter example: GET ${serviceUrl}/${shortName}?$filter=ID eq 1`,
+      );
+      lines.push(
+        `Expand example: GET ${serviceUrl}/${shortName}?$expand=${associations[0]?.split(" ")[0] ?? "navProp"}`,
+      );
+    }
+
+    if (keys.length) lines.push(`Key fields: ${keys.join(", ")}`);
+    if (fields.length) lines.push(`Fields: ${fields.join(", ")}`);
+    if (enums.length) lines.push(`Enum fields: ${enums.join("; ")}`);
+    if (associations.length)
+      lines.push(`Associations: ${associations.join("; ")}`);
+    if (compositions.length)
+      lines.push(`Compositions (child entities): ${compositions.join("; ")}`);
+
+    if (def["@title"]) lines.push(`UI label: ${def["@title"]}`);
+    if (def["@description"]) lines.push(`Description: ${def["@description"]}`);
+    if (def["@readonly"]) lines.push("Access: read-only");
+    if (def["@insertonly"]) lines.push("Access: insert-only");
+
+    docs.push({
+      title: `${shortName} entity schema`,
+      content: lines.join("\n"),
+    });
+  }
+
+  // ── Entity relationship map ─────────────────────────────────────────────────
+  const relLines = ["Entity relationship overview:"];
+  for (const [fqName, def] of entityDefs) {
+    if (def.kind !== "entity") continue;
+    const shortName = fqName.split(".").pop();
+    const rels = [];
+    for (const [, el] of Object.entries(def.elements ?? {})) {
+      if (el.type === "cds.Association" || el.type === "cds.Composition") {
+        const target = _shortName(el.target ?? "");
+        const card = el.cardinality?.max === "*" ? "1:N" : "1:1";
+        rels.push(`${shortName} -[${card}]-> ${target}`);
+      }
+    }
+    if (rels.length) relLines.push(...rels);
+  }
+  if (relLines.length > 1) {
+    docs.push({
+      title: "Entity relationship map",
+      content: relLines.join("\n"),
+    });
+  }
+
+  // ── Services ────────────────────────────────────────────────────────────────
+  const serviceEntries = [];
+  for (const [fqName, def] of Object.entries(defs)) {
+    if (def.kind !== "service") continue;
+    const svcName = fqName.split(".").pop();
+    const exposed = Object.keys(def.elements ?? {});
+    if (exposed.length) {
+      serviceEntries.push(`${svcName}: ${exposed.join(", ")}`);
+    }
+  }
+  if (serviceEntries.length) {
+    docs.push({
+      title: "Service definitions",
+      content: [
+        "CAP services and the entities/projections they expose:",
+        ...serviceEntries,
+      ].join("\n"),
+    });
+  }
+
+  // ── Application summary ─────────────────────────────────────────────────────
+  const entityNames = entityDefs.map(([n]) => n.split(".").pop());
+  if (entityNames.length) {
+    const summaryLines = [
+      `This CAP application defines ${entityNames.length} entities: ${entityNames.join(", ")}.`,
+    ];
+    if (serviceUrl) {
+      summaryLines.push(`OData service base URL: ${serviceUrl}`);
+      summaryLines.push("Query patterns:");
+      summaryLines.push("  GET {serviceUrl}/{Entity} — list all records");
+      summaryLines.push(
+        "  GET {serviceUrl}/{Entity}/{key} — single record by key",
+      );
+      summaryLines.push("  GET {serviceUrl}/{Entity}/$count — total count");
+      summaryLines.push(
+        "  GET {serviceUrl}/{Entity}?$filter=field eq value — filter",
+      );
+      summaryLines.push(
+        "  GET {serviceUrl}/{Entity}?$select=f1,f2 — specific fields",
+      );
+      summaryLines.push(
+        "  GET {serviceUrl}/{Entity}?$top=10&$skip=0 — pagination",
+      );
+      summaryLines.push(
+        "  GET {serviceUrl}/{Entity}?$orderby=field desc — sorting",
+      );
+      summaryLines.push(
+        "  GET {serviceUrl}/{Entity}?$expand=navProp — related entities",
+      );
+    }
+    docs.push({
+      title: "Application schema summary",
+      content: summaryLines.join("\n"),
+    });
+  }
+
+  return docs;
+}
+
+/**
+ * Extract additional context from running CDS services via srv.entities.
+ * Called after cds.on('served') with the actual service objects.
+ *
+ * @param {import('@sap/cds').Service[]} services
+ * @returns {{ title: string, content: string }[]}
+ */
+function extractFromServices(services) {
+  const docs = [];
+
+  for (const srv of services) {
+    if (!srv || !srv.entities) continue;
+
+    const srvName = srv.name?.split(".").pop() ?? srv.name ?? "Service";
+    const lines = [`Runtime service: ${srvName}`];
+
+    try {
+      const entities = srv.entities;
+      const entityNames = [];
+
+      for (const [name, entity] of Object.entries(entities)) {
+        if (!entity || name.startsWith("_")) continue;
+        entityNames.push(name);
+        lines.push(
+          `  - ${name} (draft: ${entity.drafts ? "yes" : "no"}, keys: ${Object.keys(entity.keys ?? {}).join(", ")})`,
+        );
+      }
+
+      if (entityNames.length) {
+        docs.push({
+          title: `${srvName} runtime entities`,
+          content: lines.join("\n"),
+        });
+      }
+    } catch {
+      // srv.entities not available or failed
+    }
+  }
+
+  return docs;
+}
+
+function _shortType(type) {
+  if (!type) return "String";
+  const map = {
+    "cds.String": "String",
+    "cds.Integer": "Integer",
+    "cds.Integer64": "Integer64",
+    "cds.Decimal": "Decimal",
+    "cds.Double": "Double",
+    "cds.Boolean": "Boolean",
+    "cds.Date": "Date",
+    "cds.Time": "Time",
+    "cds.DateTime": "DateTime",
+    "cds.Timestamp": "Timestamp",
+    "cds.UUID": "UUID",
+    "cds.LargeString": "LargeString",
+    "cds.Binary": "Binary",
+  };
+  return map[type] ?? type.split(".").pop() ?? type;
+}
+
+function _shortName(fqn) {
+  return fqn.split(".").pop() ?? fqn;
+}
+
+module.exports = { extract, extractFromServices };

package/src/index.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * @btp-copilot/cap-plugin — CDS plugin entry point.
+ *
+ * On CAP startup this plugin:
+ *   1. Reads the CDS compiled model (entity schemas, types, relationships)
+ *   2. Reads the project folder structure (srv handlers, db schema files,
+ *      Fiori XML views, manifests, i18n labels, annotations)
+ *   3. Iterates every running CDS service's srv.entities for runtime info
+ *   4. POSTs all collected documents to the BTP Copilot backend so that the
+ *      chatbot can answer context-aware questions about this app
+ *
+ * Minimal configuration in your app's package.json:
+ * {
+ *   "cds": {
+ *     "requires": {
+ *       "btp-copilot": {
+ *         "kind": "btp-copilot",
+ *         "backendUrl": "https://your-copilot.cfapps.eu10.hana.ondemand.com",
+ *         "appId": "my-sales-app",
+ *         "appName": "My Sales Application",
+ *         "serviceUrl": "/odata/v4/SalesService",
+ *         "token": "<bearer-token-or-read-from-env>"
+ *       }
+ *     },
+ *     "plugins": ["@btp-copilot/cap-plugin"]
+ *   }
+ * }
+ *
+ * Or programmatically (in a custom server.js):
+ *   const btpCopilot = require('@btp-copilot/cap-plugin');
+ *   btpCopilot({ backendUrl: '...', appId: '...' });
+ */
+
+const path = require("path");
+const { extract, extractFromServices } = require("./SchemaExtractor");
+const { scan } = require("./ProjectScanner");
+const { register } = require("./Registrar");
+
+module.exports = (options = {}) => {
+  const cds = require("@sap/cds");
+  const log = cds.log("btp-copilot");
+
+  // Merge: explicit options > cds.env.requires config > env vars
+  const cfg = Object.assign(
+    {},
+    cds.env.requires?.["btp-copilot"] ?? {},
+    options,
+  );
+
+  const {
+    backendUrl = process.env.BTP_COPILOT_URL,
+    appId = process.env.BTP_COPILOT_APP_ID,
+    appName,
+    serviceUrl,
+    token = process.env.BTP_COPILOT_TOKEN,
+    includeProjectFiles = true,
+    includeHandlers = true,
+    includeViews = true,
+  } = cfg;
+
+  if (!backendUrl || !appId) {
+    log.warn(
+      "Missing required config (backendUrl, appId). " +
+        "Set them in cds.requires.btp-copilot or via BTP_COPILOT_URL / BTP_COPILOT_APP_ID env vars. " +
+        "Skipping registration.",
+    );
+    return;
+  }
+
+  // Validate appId format (backend requires ^[a-zA-Z0-9_-]+$)
+  if (!/^[a-zA-Z0-9_-]+$/.test(appId)) {
+    log.warn(
+      `appId "${appId}" contains invalid characters. Use only letters, digits, underscores and hyphens.`,
+    );
+    return;
+  }
+
+  cds.on("served", async (services) => {
+    try {
+      log.info(`Collecting context for app "${appId}"…`);
+      const allDocs = [];
+
+      // ── 1. CDS model schema (entities, relationships, services) ─────────────
+      const schemaDocs = extract(cds, { serviceUrl });
+      allDocs.push(...schemaDocs);
+      log.info(`  + ${schemaDocs.length} schema documents`);
+
+      // ── 2. Runtime srv.entities for each running service ────────────────────
+      const serviceList = Array.isArray(services)
+        ? services
+        : Object.values(services ?? {});
+
+      const runtimeDocs = extractFromServices(serviceList);
+      allDocs.push(...runtimeDocs);
+      if (runtimeDocs.length) {
+        log.info(`  + ${runtimeDocs.length} runtime service documents`);
+      }
+
+      // ── 3. Project folder structure, src files, manifests ──────────────────
+      if (includeProjectFiles) {
+        const projectRoot = cds.env.root ?? process.cwd();
+        const fileDocs = scan(projectRoot, { includeHandlers, includeViews });
+        allDocs.push(...fileDocs);
+        log.info(`  + ${fileDocs.length} project file documents`);
+      }
+
+      if (!allDocs.length) {
+        log.info("No documents to register.");
+        return;
+      }
+
+      log.info(
+        `Registering ${Math.min(allDocs.length, 50)} documents (of ${allDocs.length} total) for app "${appId}"…`,
+      );
+
+      const ok = await register({
+        backendUrl,
+        appId,
+        appName: appName ?? appId,
+        serviceUrl,
+        documents: allDocs,
+        token,
+      });
+
+      if (ok) {
+        log.info(
+          `✔ App "${appId}" registered with BTP Copilot. Chatbot is now context-aware.`,
+        );
+      } else {
+        log.warn(
+          `✘ Registration failed for "${appId}". Check backendUrl (${backendUrl}) and token.`,
+        );
+      }
+    } catch (err) {
+      log.error("Registration error —", err.message);
+    }
+  });
+};