@sap/cds-dk 10.1.1 → 10.2.0

package/node_modules/@sap/cds/app/index.html

@@ -1,32 +1,56 @@
 <!DOCTYPE html>
-<html>
-    <head>
-        <title>{{package}}</title>
-        <meta name="color-scheme" content="dark light">
-        <style>
-{{style}}
-        </style>
-    </head>
-    <body>
-        <div id="welcome">
-            <h1> Welcome to <i>@sap/cds</i> Server </h1>
-            <p class="subtitle"> Serving {{package}} </p>
-
-            <p> These are the paths currently served:</p>
-
-            <h2> Web Applications: </h2>
-            <ul>
-                {{apps}}
-            </ul>
-
-            <h2> Service Endpoints: </h2>
-            {{services}}
-
-            <footer>
-                This is an automatically generated page. <br>
-                You can replace it with a custom <code>./{{app}}/index.html</code>.
-            </footer>
-        </div>
-
-    </body>
+<html lang="en">
+<head>
+  <title>${app.name}</title>
+  <meta name="color-scheme" content="dark light">
+  <link rel="stylesheet" href="/.cap/index.css">
+  <script src="/.cap/index-client.js" defer></script>
+</head>
+<body>
+
+  <label class="theme-switch" title="Toggle dark mode">
+    <input id="theme-switch" type="checkbox" aria-label="Toggle dark mode">
+    <span class="theme-switch-track" aria-hidden="true"><span class="theme-switch-sun">☀</span><span class="theme-switch-moon">☾</span></span>
+  </label>
+
+  <h1> Welcome to <i>@sap/cds</i> Server </h1>
+  <p id="subtitle"> Serving <i>${app.name}</i> </p>
+
+
+  <section id="webapps">
+    <h2> Web Apps: </h2>
+    <ul>
+      <li><a href="${href}" target="_blank">${label}</a></li>
+    </ul>
+  </section>
+
+
+  <section id="agents">
+    <h2> Agents: </h2>
+    <ul>
+      <li>
+        <a href="${href}" target="_blank" title="Chat Preview"> ${label} </a>
+        <a href="${card}" target="_blank" class="agent-card-link"> Agent Card </a>
+      </li>
+    </ul>
+  </section>
+
+
+  <section id="provided-services" class="services">
+    <h2> Services: </h2> <button class="toggle-button"></button>
+    {{provided}}
+  </section>
+
+  <section id="required-services" class="services">
+    <h2> Required Services: </h2> <button class="toggle-button"></button>
+    {{required}}
+  </section>
+
+
+  <footer>
+    This is an automatically generated page. <br>
+    You can replace it with a custom <code>./${cds.folders.app}/index.html</code>.
+  </footer>
+
+</body>
 </html>

package/node_modules/@sap/cds/app/index.js

@@ -1,101 +1,345 @@
+const PROD = process.env.NODE_ENV === 'production'
 const cds = require('../lib')
 const { find, path, fs } = cds.utils
 
-const odata = endpoint => endpoint.kind.startsWith('odata')
-const rel = path => path.replace(/^\//, '')
-const metadata = endpoint => odata(endpoint) ? `<span>/</span> <a href="${rel(endpoint.path)}/$metadata"><span>$metadata</span></a>` : ``
+const protocolOrder = new Map(['agent', 'rest', 'odata', 'mcp', 'hcql'].map((protocol, index) => [protocol, index]))
+const initialProtocolOrder = ['hcql', 'odata', 'rest', 'mcp', 'agent']
+const compareProtocols = (a, b) => (protocolOrder.get(a) ?? Infinity) - (protocolOrder.get(b) ?? Infinity)
+
+// Built-in link provider factory. Covers standard metadata and design-time links
+// unless overridden by a plugin registered on srv.$linkProviders.
+/** @returns {IndexLinkProvider} */
+const defaultLinkProvider = (srv) => {
+  const loc  = !PROD && srv.definition?.$location
+  const declHref = loc?.file  ? _vslink(loc.file, loc.line) : null
+  const srcLinks = [
+    declHref && { href: declHref, name: 'Declaration', title: 'Open declaration', group: 'source' },
+  ].filter(Boolean)
+  return (entity, endpoint) => {
+    if (entity || !endpoint) return
+    if (endpoint.kind === 'hcql')          return [{ href: rel(endpoint.path) + '/?describe=all', name: '/?describe=all', title: 'HCQL service description', group: 'metadata' }, ...srcLinks]
+    if (endpoint.kind.startsWith('odata')) return [{ href: rel(endpoint.path) + '/$metadata', name: '/$metadata', title: 'OData EDMX', group: 'metadata' }, ...srcLinks]
+    return srcLinks.length ? srcLinks : undefined
+  }
+}
+const rel = p => p.replace(/^\//, '')
 const asHtmlId = s => s.replace(/[.:/$&?@]/g, '_').toLowerCase()
 
+const app_info = {
+
+  get name() { try {
+    return require (cds.root+'/package.json').name
+  } catch {
+    return path.basename(cds.root)
+  }},
+
+  get webapps() {
+    const folder = path.resolve (cds.root, cds.env.folders.app)
+    return find (folder, ['*.html', '*/*.html', '*/*/*.html'])
+    .map (file => path.relative(folder,file).replace(/\\/g,'/'))
+    .concat (cds.app._app_links||[]) // concatenate additional app links
+    .map (href => ({ href: '/'+href, label: href.replace('/index.html','') }))
+  },
+
+  get agents() {
+    const links = []
+    // Own agents first, required ones after
+    const providers = [...cds.service.providers].sort(
+      (a, b) => (a.name in cds.requires) - (b.name in cds.requires)
+    )
+    for (const srv of providers) {
+      const ep = srv.endpoints?.find(ep => ep.kind === 'agent'); if (!ep) continue
+      const entry = { label: _display_name(srv) }
+      for (const linkProv of srv.$linkProviders || []) {
+        for (const l of [].concat(linkProv(undefined, ep) ?? [])) {
+          if (l?.href?.match(/preview/i))           entry.href = rel(l.href)
+          if (l?.href?.includes('agent-card.json')) entry.card = rel(l.href)
+        }
+      }
+      if (entry.href || entry.card) links.push(entry)
+    }
+    return links
+  },
+}
+
 module.exports = { get html(){
 
-  let css = fs.readFileSync(path.join(__dirname,'index.css'),'utf-8')
   let html = fs.readFileSync(path.join(__dirname,'index.html'),'utf-8')
-  // .replace ('{{subtitle}}', 'Version ' + cds.version)
-  .replace (/{{package}}/g, _project())
-  .replace (/{{app}}/g, cds.env.folders.app.replace(/*trailing slash*/ /\/$/, ''))
-  .replace ('{{style}}', css)
-  .replace ('{{apps}}', _app_links().map(
-      html => `<li><a href="${html}"><span>/${html.replace(/^\//,'').replace('/index.html','')}</span></a></li>`
-    ).join('\n') || '— none —'
-  )
-  .replace ('{{services}}', cds.service.providers
-  .flatMap(srv => srv.endpoints.map(endpoint => ({srv, endpoint})))
-  .map (({srv, endpoint}) => `
-      <div id="${asHtmlId(srv.name)}-${endpoint.kind}">
-        <h3 class="header">
-          <a href="${rel(endpoint.path)}"><span>${endpoint.path}</span></a>${metadata(endpoint)} ${_moreLinks(srv, endpoint, undefined, false)}
-        </h3>
-        <ul>${_entities_in(srv).map (e => `
-          <li id="${asHtmlId(srv.name)}-${endpoint.kind}-${asHtmlId(e)}">
-            <div>
-              <a href="${rel(endpoint.path)}/${e.replace(/\./g, '_')}"><span>${e}</span></a>
-            </div>
-            ${_moreLinks(srv, endpoint, e)}
-          </li>`).join('')}
-        </ul>
-        <ul>${_operations_in(srv).map (e => `
-          <li id="${asHtmlId(srv.name)}-${endpoint.kind}-${asHtmlId(e.name)}" class="operation">
-            <div>
-              <a href="${rel(endpoint.path)}/${e.name}" title="${endpoint.path}/${e.name}"><span>${e.name} ${e.params}</span></a>
-            </div>
-          </li>`).join('')}
-        </ul>
-      </div>
-  `).join(''))
+  .replaceAll ("${app.name}", app_info.name)
+  .replace ("</head>", "  <script> document.app_info = " + JSON.stringify(app_info) + " </script>\n</head>")
+  .replace ("${cds.folders.app}", cds.env.folders.app.replace(/*trailing slash*/ /\/$/,''))
+
+  // Provided Services
+  const services = cds.model.services
+  const provided = cds.service.providers.filter(srv => !(srv.name in cds.requires))
+  html = html.replace ('{{provided}}', provided.map(_service_block).join(''))
+
+  // Required Services
+  const required = Object.keys(cds.requires) .map (name => {
+    let srv = cds.services[name]; if (srv?.kind === 'app-service') return srv
+    let def = services[name] || services[cds.requires[name].service]
+    if (def) return new RemoteService (name, def)
+  }).filter(Boolean)
+  html = html.replace ('{{required}}', required.map(_service_block).join(''))
 
   Object.defineProperty (this,'html',{value:html})
   return html
 
 }}
 
-function _app_links() {
-  const folder = path.resolve (cds.root, cds.env.folders.app)
-  const files = find (folder, ['*.html', '*/*.html', '*/*/*.html']).map (
-    file => path.relative(folder,file).replace (/\\/g,'/')
-  )
-  return files.concat (cds.app._app_links || [])
+class RemoteService extends cds.Service {
+  constructor (name, def, model = cds.model, options = cds.requires[name]) {
+    super (name, model, options)
+    this.definition = def
+    this.is_remote = true
+    this.mocked = options?.credentials?.url ? false : true
+  }
+  get endpoints() {
+    const url = this.options?.credentials?.url || ''
+    const base = url ? new URL(url).origin : ''
+    return super.endpoints.map (ep => ({ ...ep, path: base + ep.path }))
+  }
 }
 
-function _entities_in (service) {
-  const exposed=[], {entities} = service
-  for (let each in entities) {
-    const e = entities [each]
-    if (e['@cds.autoexposed'] && !e['@cds.autoexpose'])  continue
-    if (/DraftAdministrativeData$/.test(e.name))  continue
+function _display_name (srv) {
+  return srv.name
+    .replace(/^.*\./, '')                        // strip namespace
+    .replace(/([a-z])([A-Z])/g, '$1 $2')         // CamelCase → words
+    .split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ')  // kebab-case → Title Case
+    .trim()
+}
+
+function _service_block (srv) {
+  const entities = _entities_in(srv) .sort ((a,b) => a.autoexposed - b.autoexposed)
+  const operations = _operations_in(srv)
+
+  const eps = [...new Map(srv.endpoints.map(ep => [ep.kind, ep])).values()].sort((a, b) => compareProtocols(a.kind, b.kind))
+  const protocols = eps.map(ep => ep.kind)
+  const initialProtocol = initialProtocolOrder.find(protocol => protocols.includes(protocol)) ?? protocols[0]
+  const initialIdx = protocols.indexOf(initialProtocol)
+  const ep0 = eps[initialIdx]
+  const builtinProv = defaultLinkProvider(srv)
+  /** @type {IndexLinkProvider[]} */
+  const allProviders = [builtinProv, ...(srv.$linkProviders || [])]
+
+  // Collect metadata and source-group links from all providers across all endpoints.
+  const providerMetaByProto = new Map() // proto  -> IndexLink
+  const sourceByHref        = new Map() // href   -> IndexLink
+  for (const ep of eps) {
+    for (const linkProv of allProviders) {
+      for (const l of [].concat(linkProv(undefined, ep) ?? [])) {
+        if (!l?.href || !l?.name) continue
+        if (l.group === 'metadata' && !providerMetaByProto.has(ep.kind))
+          providerMetaByProto.set(ep.kind, { ...l, href: rel(l.href) })
+        else if (l.group === 'source' && !sourceByHref.has(l.href))
+          sourceByHref.set(l.href, l)
+      }
+    }
+  }
+  const sourceLinks = [...sourceByHref.values()]
+
+  // Build per-endpoint describe hrefs/labels from the collected metadata links.
+  const describeHrefs  = eps.map(ep => providerMetaByProto.get(ep.kind)?.href  ?? null)
+  const describeLabels = eps.map(ep => providerMetaByProto.get(ep.kind)?.name  ?? null)
+  const describeTitles = eps.map(ep => providerMetaByProto.get(ep.kind)?.title ?? null)
+  const initialDescribe = describeHrefs[initialIdx]
+  const initialDescribeLabel = describeLabels[initialIdx] ?? 'metadata'
+  const initialDescribeTitle = describeTitles[initialIdx]
+
+  const sourceLinksHtml = sourceLinks.length ? `
+              <span class="source-links">${sourceLinks.map(l =>
+                `<a class="src-link" href="${l.href}" title="${l.title || l.name}">${l.name}</a>`
+              ).join('')}</span>` : ''
+
+  const serviceLevelLinks = _moreLinksServices(srv, eps, undefined, 'extra-link')
+  const baseUrl = srv.is_remote ? (srv.options?.credentials?.url ? new URL(srv.options.credentials.url).origin : '') : ''
+  const describeCenter = baseUrl ? `<span class="describe-center"><a class="src-link base-url" href="${baseUrl}" title="Remote server base URL">${baseUrl}</a></span>` : ''
+  const describeRow = (initialDescribe || serviceLevelLinks || sourceLinksHtml || describeCenter)
+    ? `
+          <li class="describe-row">
+            <div class="entity-row describe-row-layout">
+              <span class="describe-left">${initialDescribe ? `<a class="entity-name describe-link" href="${initialDescribe}"${initialDescribeTitle ? ` title="${initialDescribeTitle}"` : ''} data-describes='${JSON.stringify(describeHrefs)}' data-labels='${JSON.stringify(describeLabels)}' data-titles='${JSON.stringify(describeTitles)}'><span class="kind-pill kind-schema" title="A schema / metadata document">meta</span><span class="label">${initialDescribeLabel}</span></a>` : ''}</span>
+              ${describeCenter}
+              <span class="describe-right">${serviceLevelLinks ? `<span class="extra-links">${serviceLevelLinks}</span>` : ''}${sourceLinksHtml}</span>
+            </div>
+          </li>` : ''
+
+  const entityRows = entities.map(entity => {
+    const { name, autoexposed } = entity
+    const { center, right } = _moreLinks(srv, eps, name, 'extra-link')
+    const extraCenter = center ? `<span class="extra-links">${center}</span>` : ''
+    const extraRight  = right  ? `<span class="source-links">${right}</span>`  : ''
+    const is3col = extraCenter || extraRight
+    const nameHref = ep0 ? `${rel(ep0.path)}/${name}` : null
+    const autoPill = autoexposed ? `<span class="kind-pill kind-auto" title="A secondary / code list entity, auto-exposed by the compiler">entity</span>` : ''
+    const entityPill = autoexposed ? '' : `<span class="kind-pill kind-entity" title="A main entity, explicitly exposed">entity</span>`
+    const nameEl = nameHref
+      ? `<a class="entity-name" href="${nameHref}" data-base="${name}">${entityPill}${autoPill}${name}</a>`
+      : `<span class="entity-name">${entityPill}${autoPill}${name}</span>`
+    return `
+          <li id="${asHtmlId(srv.name)}-${asHtmlId(name)}">
+            <div class="entity-row${is3col ? ' entity-row-3col' : ''}">
+              ${nameEl}${is3col ? `<span class="entity-right">${extraCenter}${extraRight}</span>` : ''}
+            </div>
+          </li>`
+  }).join('')
+
+  const operationRows = operations.map(op => {
+    const nameHref = ep0 ? `${rel(ep0.path)}/${op.name}` : null
+    const nameEl = nameHref
+      ? `<a class="entity-name" href="${nameHref}" data-base="${op.name}"><span class="kind-pill kind-${op.kind}" title="A custom action or function">${op.label}</span>${op.name}</a>`
+      : `<span class="entity-name"><span class="kind-pill kind-${op.kind}" title="A custom action or function">${op.label}</span>${op.name}</span>`
+    return `
+          <li id="${asHtmlId(srv.name)}-${asHtmlId(op.name)}" class="operation">
+            <div class="entity-row">
+              ${nameEl}
+            </div>
+          </li>`
+  }).join('')
+
+  return `
+    <details id="${asHtmlId(srv.name)}" data-protocols="${protocols.join(' ')}" data-paths='${JSON.stringify(eps.map(ep => rel(ep.path)))}' data-selected-protocol="${initialProtocol}">
+      <summary>
+        <span class="srv-name">${_display_name(srv)}</span>${(() => {
+          const status = srv.options?.credentials?.url ? 'remote' : srv.mocked ? 'mocked' : ''
+          return !status ? '' : `<span class="srv-status srv-status-${status}" title="${status === 'remote' ? 'Served by a real remote endpoint' : 'Served locally as a mock'}">${status}</span>`
+        })()}
+        <span class="protocol-badges" role="radiogroup" aria-label="Served protocols">${protocols.map(protocol => `<button type="button" class="badge" role="radio" data-protocol="${protocol}" aria-checked="${protocol === initialProtocol}" tabindex="${protocol === initialProtocol ? '0' : '-1'}">${protocol}</button>`).join('')}</span>
+      </summary>
+      <ul>${describeRow}${entityRows}${operationRows}
+      </ul>
+    </details>`
+}
+
+function _vslink (file, line) {
+  const abs = path.resolve(cds.root, file)
+  return `vscode://file/${abs}${line ? ':' + line : ''}`
+}
+
+function _entities_in (srv) {
+  const entities=[]
+  for (let name in srv.entities) {
+    const e = srv.entities[name]
+    // if (e['@cds.autoexposed'] && !e['@cds.autoexpose'])  continue
     if (/[._]texts$/.test(e.name))  continue
-    if (cds.env.effective.odata.containment && service.definition._containedEntities.has(e.name)) continue
-    exposed.push (each.replace(/\./g,'_'))
+    if (/DraftAdministrativeData$/.test(e.name))  continue
+    if (cds.env.effective.odata.containment && srv.definition._containedEntities.has(e.name)) continue
+    entities.push ({
+      name, kind: 'entity', target: e.name,
+      autoexposed: !!e['@cds.autoexposed']
+    })
   }
-  return exposed
+  return entities
 }
 
 function _operations_in (service) {
   const exposed=[], {operations} = service
   for (let name in operations) {
     const op = cds.model.definitions[service.name + '.' + name]
-    if (op?.kind === 'function') {
+    if (op?.kind === 'function' || op?.kind === 'action') {
       const params = '('+ Object.keys(op.params||[]) + ')'
-      exposed.push ({ name, params })
+      exposed.push ({ name, params, kind: op.kind, label: 'action' })
     }
   }
   return exposed
 }
 
-function _moreLinks (srv, endpoint, entity, div=true) {
-  return (srv.$linkProviders || [])
-    .map (linkProv => linkProv(entity, endpoint))
-    .filter (l => l?.href && l?.name)
-    // .sort ((l1, l2) => l1.name.localeCompare(l2.name))
-    .map (l => `${div?'<div>':'<span>'}<a href="${l.href}"><span class="preview" title="${l.title||l.name}">${l.name}</span></a>${div?'</div>':'</span>'}`)
-    .join (' ')
+function _moreLinks (srv, endpoints, entity, cls='proto-link') {
+  if (!endpoints?.length) return { center: '', right: '' }
+  const centerByHref = new Map(), rightByHref = new Map()
+  /** @type {IndexLinkProvider[]} */
+  const providers = srv.$linkProviders || []
+  for (const endpoint of endpoints) {
+    for (const linkProv of providers) {
+      const result = linkProv(entity, endpoint)
+      for (const l of [].concat(result ?? [])) {
+        if (!l?.href || !l?.name) continue
+        if (l.group === 'source') {
+          if (!rightByHref.has(l.href)) rightByHref.set(l.href, l)
+        } else if (l.group !== 'metadata') {
+          const entry = centerByHref.get(l.href)
+          if (entry) {
+            entry.always ||= endpoint.kind.startsWith('odata')
+            if (entry.protocols && l.protocols) {
+              for (const protocol of [].concat(l.protocols)) entry.protocols.add(protocol)
+            } else {
+              entry.protocols = null
+            }
+          } else {
+            centerByHref.set(l.href, {
+              l,
+              always: endpoint.kind.startsWith('odata'),
+              protocols: l.protocols ? new Set([].concat(l.protocols)) : null,
+            })
+          }
+        }
+      }
+    }
+  }
+  return {
+    center: [...centerByHref.values()].map(({ l, always, protocols }) => {
+      const protos = protocols ? ` data-protocols="${[...protocols].join(' ')}"` : ''
+      return `<a class="${cls}"${protos}${always ? ' data-always' : ''} href="${l.href}" title="${l.title||l.name}">${l.name}</a>`
+    }).join(' '),
+    right: [...rightByHref.values()].map(l =>
+      `<a class="src-link" href="${l.href}" title="${l.title||l.name}">${l.name}</a>`
+    ).join(''),
+  }
 }
 
-function _project(){
-  const cwd = cds.root
-  try {
-    const pj = require(cwd+'/package.json')
-    return `${pj.name} ${pj.version}`
-  } catch {
-    return `${cwd}`
+function _moreLinksServices (srv, endpoints, entity, cls='proto-link') {
+  if (!endpoints?.length) return ''
+  // Collect links per href, merging protocols across endpoints.
+  // If any endpoint produces a link without declaring protocols, the link is unrestricted.
+  const byHref = new Map()
+  /** @type {IndexLinkProvider[]} */
+  const providers = srv.$linkProviders || []
+  for (const ep of endpoints) {
+    if (ep.kind === 'agent') continue  //> agents are shown in the top-level Agents section
+    for (const linkProv of providers) {
+      for (const l of [].concat(linkProv(entity, ep) ?? [])) {
+        if (!l?.href || !l?.name || l.group === 'metadata' || l.group === 'source') continue
+        if (byHref.has(l.href)) {
+          const entry = byHref.get(l.href)
+          if (entry.protocols && l.protocols) {
+            for (const p of [].concat(l.protocols)) entry.protocols.add(p)
+          } else {
+            entry.protocols = null
+          }
+        } else {
+          byHref.set(l.href, { l, protocols: l.protocols ? new Set([].concat(l.protocols)) : null })
+        }
+      }
+    }
   }
+  return [...byHref.values()].map(({ l, protocols }) => {
+    const protos = protocols ? ` data-protocols="${[...protocols].join(' ')}"` : ''
+    return `<a class="${cls}"${protos} href="${l.href}" title="${l.title||l.name}">${l.name}</a>`
+  }).join(' ')
 }
+
+/**
+ * A link provider registered on a service provider, like `srv.$linkProviders`.
+ * Called in two patterns:
+ *   - `(undefined, endpoint)` — service-level per endpoint
+ *   - `(entity,   endpoint)`  — entity-level
+ *
+ * May return a single {@link IndexLink}, an array of {@link IndexLink}, or falsy to skip.
+ *
+ * @callback IndexLinkProvider
+ * @param {string|undefined}                    entity    - Entity name, or undefined for service-level calls
+ * @param {{kind:string,path:string}|undefined} endpoint  - Endpoint descriptor
+ * @returns {IndexLink|IndexLink[]|undefined}
+ */
+
+/**
+ * @typedef {Object} IndexLink
+ * @property {string}   href        - Link URL (relative or absolute; `metadata` group is normalized to relative)
+ * @property {string}   name        - Link text
+ * @property {string}   [title]     - Tooltip; falls back to `name`
+ * @property {string[]} [protocols] - Client-side show/hide: only visible when one of these protocols is selected
+ * @property {'metadata'|'source'|undefined} [group]
+ *   - `'metadata'`  the service's metadata link, per protocol — replaces the built-in $metadata/$csn (first provider wins per protocol)
+ *   - `'source'`    design-time links such as Declaration
+ *   - (omitted)     regular navigation link
+ */