sap-ai-dev-toolkit 0.9.9922 → 0.9.9923

package/src/datasphere-command.mjs

@@ -0,0 +1,236 @@
+// Direct SAP CLI access with a tenant URL and a short-lived browser passcode.
+// Only the tenant URL and discovery catalog are remembered; authentication is temporary.
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { copyFile, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { datasphereCliEnvironment } from './datasphere-cli.mjs';
+import { loadDatasphereCommands } from './datasphere-discovery.mjs';
+import { readStoredDatasphereCredentials } from './datasphere-credentials.mjs';
+import { userConfigFilePath, writeUserOnlyJson } from './integration-credentials.mjs';
+import { openInBrowser } from './datasphere-auth.mjs';
+import { textPrompt } from './terminal-ui.mjs';
+
+const require = createRequire(import.meta.url);
+const CAPTURE_LIMIT = 1024 * 1024;
+const MANAGED_AUTH = /^(?:--(?:options-file|secrets-file|client-id|client-secret|access-token|refresh-token|authorization-url|token-url|authorization-flow|code|login-id)(?:=|$)|-[OscCatAr](?:[^-]|$))/;
+
+export function datasphereCommandUsage() {
+  return [
+    'Usage: sap-ai-dev --datasphere [--host <tenant URL>] <command> [options]',
+    '',
+    'Run the bundled SAP Datasphere CLI using your user and a browser temporary code.',
+    'The tenant URL and command catalog are remembered. Each command opens the SAP code page.',
+    'The first run needs two fresh codes: one for the catalog, then one for the command.',
+    '',
+    '  sap-ai-dev --datasphere objects views list --space MY_SPACE',
+    '  sap-ai-dev --datasphere --host https://<tenant>.eu20.hcs.cloud.sap objects views list --space MY_SPACE',
+    '  sap-ai-dev --datasphere --version',
+    '',
+    '  --passcode-stdin  Read a temporary code from standard input instead of opening the browser',
+    '',
+    'Native SAP command options and confirmations apply. Temporary code files are removed after the command.',
+    'For persistent OAuth-based MCP access, use sap-ai-dev --setup-datasphere.',
+    ''
+  ].join('\n');
+}
+
+function tenantUrl(value) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error('Datasphere tenant URL is invalid');
+  value = value.trim();
+  let url;
+  try { url = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(value) ? value : `https://${value}`); }
+  catch { throw new Error('Datasphere tenant URL is invalid'); }
+  if (url.username || url.password) throw new Error('Datasphere tenant URL must not contain credentials');
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) {
+    throw new Error('Datasphere tenant URL must use https');
+  }
+  return url.origin;
+}
+
+function parseArguments(argv) {
+  const command = [];
+  let host;
+  let passcode;
+  let fromStdin = false;
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === '--passcode-stdin') { fromStdin = true; continue; }
+    const option = /^(--host|-H|--passcode|-p)(?:=(.*))?$/.exec(arg);
+    const attached = /^(-H|-p)([^=].+)$/.exec(arg);
+    if (option || attached) {
+      const name = (option || attached)[1];
+      const value = attached?.[2] ?? option[2] ?? argv[++index];
+      if (!value || (name === '--host' || name === '-H') && value.startsWith('-')) throw new Error(`Missing value for ${name}`);
+      if (name === '--host' || name === '-H') host = value;
+      else passcode = value;
+    } else {
+      if (MANAGED_AUTH.test(arg)) throw new Error('This command uses browser-code authentication; configure OAuth with sap-ai-dev --setup-datasphere.');
+      command.push(arg);
+    }
+  }
+  if (passcode && fromStdin) throw new Error('Use either --passcode or --passcode-stdin');
+  return { command, host, passcode, fromStdin };
+}
+
+async function rememberedTenant(env) {
+  const path = userConfigFilePath(env, 'datasphere-cli.json');
+  try { return JSON.parse(await readFile(path, 'utf8'))?.url; }
+  catch (error) {
+    if (error.code === 'ENOENT') return readStoredDatasphereCredentials(env)?.url;
+    throw new Error('Stored Datasphere CLI tenant could not be read; supply --host <tenant URL> to replace it.');
+  }
+}
+
+async function readPasscode(input) {
+  let value = '';
+  for await (const chunk of input) {
+    value += chunk.toString();
+    if (value.length > 4096) throw new Error('Temporary authentication code is too long');
+  }
+  return value.trim();
+}
+
+// Copy only SAP's discovery files; OAuth secrets and authentication files never persist.
+async function copyDiscoveryCache(from, to) {
+  const relative = join('.@sap', 'datasphere-cli', '.cache');
+  let names;
+  try { names = await readdir(join(from, relative)); }
+  catch (error) { if (error.code === 'ENOENT') return; throw error; }
+  const files = names.filter(name => /^discovery-.*\.json$/.test(name));
+  if (!files.length) return;
+  await mkdir(join(to, relative), { recursive: true, mode: 0o700 });
+  await Promise.all(files.map(name => copyFile(join(from, relative, name), join(to, relative, name))));
+}
+
+/** Run a native SAP command. Prompt text goes to stderr, leaving stdout for the command result. */
+export async function runDatasphereCommand(argv, {
+  env = process.env,
+  input = process.stdin,
+  output = process.stdout,
+  errorOutput = process.stderr,
+  cwd = process.cwd(),
+  spawnImpl = spawn,
+  openUrl = openInBrowser,
+  prompt = textPrompt
+} = {}) {
+  if (!argv.length || argv.length === 1 && ['--help', '-h'].includes(argv[0])) {
+    output.write(datasphereCommandUsage());
+    return 0;
+  }
+  const parsed = parseArguments(argv);
+  const versionOnly = parsed.command.length === 1 && ['--version', '-v'].includes(parsed.command[0]);
+  let host;
+  if (!versionOnly) {
+    host = parsed.host || env.DATASPHERE_URL || await rememberedTenant(env);
+    if (!host) {
+      if (!input.isTTY) throw new Error('Supply --host <tenant URL> on the first Datasphere command.');
+      host = await prompt({ message: 'Datasphere tenant URL', validate: value => { try { tenantUrl(value); return true; } catch (error) { return error.message; } } }, { input, output: errorOutput });
+    }
+    host = tenantUrl(host);
+    if (!parsed.passcode && !parsed.fromStdin && !input.isTTY) throw new Error('Browser sign-in needs a terminal; use --passcode-stdin to supply a temporary code through standard input.');
+    await writeUserOnlyJson(userConfigFilePath(env, 'datasphere-cli.json'), { url: host });
+  }
+  const entry = require.resolve('@sap/datasphere-cli/terminal.js');
+  const version = JSON.parse(await readFile(require.resolve('@sap/datasphere-cli/package.json'), 'utf8')).version;
+  const cacheHome = host ? userConfigFilePath(env, join('datasphere-cli-cache', `${createHash('sha256').update(host).digest('hex').slice(0, 24)}-${version}`)) : null;
+  const dir = await mkdtemp(join(tmpdir(), 'sap-ai-datasphere-command-'));
+  const childEnv = datasphereCliEnvironment(env, dir);
+  const optionsPath = join(dir, 'options.json');
+  let passcode = parsed.passcode || '';
+  let activeChild;
+  let interrupted;
+  const interrupt = signal => {
+    interrupted = signal;
+    if (activeChild) activeChild.kill(signal);
+    else if (parsed.fromStdin) input.destroy(new Error('Datasphere command interrupted'));
+  };
+  const onInterrupt = () => interrupt('SIGINT');
+  const onTerminate = () => interrupt('SIGTERM');
+  const exitCode = (code, signal) => code ?? (signal === 'SIGINT' ? 130 : signal === 'SIGTERM' ? 143 : 1);
+  const run = (args, capture = false) => new Promise((resolve, reject) => {
+    if (interrupted) { resolve({ code: exitCode(null, interrupted), stdout: '', stderr: '' }); return; }
+    let stdout = '';
+    let stderr = '';
+    let bytes = 0;
+    let oversized = false;
+    const child = spawnImpl(process.execPath, [entry, ...args], {
+      cwd, env: childEnv, stdio: capture ? ['ignore', 'pipe', 'pipe'] : [input, output, errorOutput],
+      ...(capture ? { timeout: 180_000, windowsHide: true } : {})
+    });
+    activeChild = child;
+    if (capture) for (const stream of ['stdout', 'stderr']) {
+      child[stream].setEncoding('utf8');
+      child[stream].on('data', chunk => {
+        bytes += Buffer.byteLength(chunk);
+        if (bytes > CAPTURE_LIMIT) { oversized = true; child.kill(); return; }
+        if (stream === 'stdout') stdout += chunk;
+        else stderr += chunk;
+      });
+    }
+    child.once('error', error => reject(new Error(`Could not start the SAP Datasphere CLI (${error.code || 'process error'})`)));
+    child.once('close', (code, signal) => {
+      activeChild = null;
+      if (oversized) reject(new Error('SAP Datasphere CLI initialization output exceeded its size limit'));
+      else resolve({ code: exitCode(code, signal), stdout, stderr });
+    });
+  });
+  process.once('SIGINT', onInterrupt);
+  process.once('SIGTERM', onTerminate);
+  try {
+    if (versionOnly) return (await run(parsed.command)).code;
+    await copyDiscoveryCache(cacheHome, dir);
+    const cached = await loadDatasphereCommands({ cli: { init: async () => {}, stateDir: () => dir } }).then(() => true, () => false);
+    const initializeOnly = parsed.command.slice(0, 3).join(' ') === 'config cache init';
+    if (!cached && !initializeOnly && (parsed.fromStdin || parsed.passcode && !input.isTTY)) {
+      throw new Error('The CLI catalog needs one-time initialization. Run sap-ai-dev --datasphere config cache init --host <tenant URL> first, using a fresh browser code.');
+    }
+    let codeUrl;
+    const browserCode = async () => {
+      if (!codeUrl) {
+        const result = await run(['config', 'passcode-url', '--host', host], true);
+        if (result.code) throw new Error('Could not resolve the SAP browser login URL. Check the tenant URL.');
+        codeUrl = result.stdout.split(/\r?\n/).map(line => line.trim()).find(line => /^https:\/\//.test(line));
+        if (!codeUrl) throw new Error('SAP Datasphere CLI returned no browser login URL.');
+      }
+      errorOutput.write(`Sign in at ${codeUrl}, then copy the temporary authentication code.\n`);
+      try { await openUrl(codeUrl); } catch { /* The printed URL also works on remote terminals. */ }
+      return prompt({ message: 'Temporary authentication code', secret: true }, { input, output: errorOutput });
+    };
+    const writePasscode = async () => {
+      if (!passcode || /\s/.test(passcode) || passcode.length > 4096) throw new Error('Supply one non-empty temporary authentication code.');
+      await writeFile(optionsPath, JSON.stringify({ host, passcode }), { mode: 0o600 });
+    };
+    if (parsed.fromStdin) passcode = await readPasscode(input);
+    else if (!passcode) passcode = await browserCode();
+    await writePasscode();
+    if (!cached && !initializeOnly) {
+      const initialized = await run(['config', 'cache', 'init', '--host', host, '--options-file', optionsPath], true);
+      if (interrupted) return exitCode(null, interrupted);
+      if (initialized.code) {
+        const detail = (initialized.stderr || initialized.stdout).split(passcode).join('[redacted]').trim().slice(0, 1200);
+        throw new Error(`Datasphere CLI initialization failed${detail ? `: ${detail}` : ''}`);
+      }
+      await copyDiscoveryCache(dir, cacheHome);
+      errorOutput.write('Catalog initialized. A fresh browser code is needed for the requested command.\n');
+      passcode = await browserCode();
+      await writePasscode();
+    }
+    const result = await run([...(parsed.command.length ? parsed.command : ['--help']), '--host', host, '--options-file', optionsPath]);
+    if (result.code === 0) {
+      if (parsed.command.slice(0, 3).join(' ') === 'config cache clean') await rm(cacheHome, { recursive: true, force: true });
+      else await copyDiscoveryCache(dir, cacheHome);
+    }
+    return result.code;
+  } catch (error) {
+    if (interrupted) return exitCode(null, interrupted);
+    throw error;
+  } finally {
+    passcode = '';
+    process.removeListener('SIGINT', onInterrupt);
+    process.removeListener('SIGTERM', onTerminate);
+    await rm(dir, { recursive: true, force: true });
+  }
+}

package/src/datasphere-config.mjs

@@ -0,0 +1,154 @@
+// SAP Datasphere tenant/OAuth client configuration and optional Open SQL credentials.
+// Pure: no I/O, no network. Two auth modes: 'technical' (client credentials,
+// Technical User purpose) and 'interactive' (authorization code + refresh token,
+// Interactive Usage purpose).
+import { finalizeClientCredentials } from './integration-config.mjs';
+
+const BASE_KEYS = ['DATASPHERE_URL', 'DATASPHERE_TOKEN_URL', 'DATASPHERE_CLIENT_ID', 'DATASPHERE_CLIENT_SECRET'];
+const SQL_KEYS = ['DATASPHERE_SQL_HOST', 'DATASPHERE_SQL_USER', 'DATASPHERE_SQL_PASSWORD'];
+const ALL_SQL_KEYS = [...SQL_KEYS, 'DATASPHERE_SQL_PORT', 'DATASPHERE_SQL_SCHEMA'];
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]']);
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function text(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+/** Users paste tenant page URLs with paths and #/hash routes; only the origin matters. */
+function tenantOrigin(value) {
+  try {
+    return new URL(value).origin;
+  } catch {
+    return value; // finalize reports the invalid URL with the env-key prefix.
+  }
+}
+
+function validateHttpsUrl(value, prefix, label) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    fail(`${prefix}_${label} is not a valid URL`);
+  }
+  if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+    fail(`${prefix}_${label} must not contain credentials, a query, or a fragment`);
+  }
+  const loopback = LOOPBACK_HOSTS.has(parsed.hostname);
+  if (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && loopback)) {
+    fail(`${prefix}_${label} must use https`);
+  }
+  return parsed;
+}
+
+function parseSql(raw) {
+  if (!raw) return null;
+  const sql = {
+    host: text(raw.host),
+    port: raw.port === undefined || raw.port === '' || raw.port === null ? 443 : Number(raw.port),
+    user: text(raw.user),
+    password: typeof raw.password === 'string' ? raw.password.trim() : '',
+    schema: text(raw.schema)
+  };
+  if (!sql.host || !sql.user || !sql.password) {
+    fail('DATASPHERE_SQL configuration is incomplete: DATASPHERE_SQL_HOST, DATASPHERE_SQL_USER, DATASPHERE_SQL_PASSWORD');
+  }
+  if (!Number.isInteger(sql.port) || sql.port < 1 || sql.port > 65535) {
+    fail('DATASPHERE_SQL_PORT must be an integer between 1 and 65535');
+  }
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(sql.host)) {
+    fail('DATASPHERE_SQL_HOST must be a host name, not a URL');
+  }
+  if (!sql.schema) sql.schema = sql.user;
+  return Object.freeze({ ...sql, password: sql.password });
+}
+
+/**
+ * Validate raw Datasphere credentials into a frozen config.
+ * `raw = { auth, url, tokenUrl, clientId, clientSecret, authorizationUrl?, refreshToken?, sql? }`.
+ */
+export function parseDatasphereCredentials(raw, source) {
+  const auth = text(raw?.auth) || 'technical';
+  if (auth !== 'technical' && auth !== 'interactive') {
+    fail('DATASPHERE_AUTH must be technical or interactive');
+  }
+  const base = finalizeClientCredentials('DATASPHERE', source, {
+    url: tenantOrigin(text(raw?.url)),
+    tokenUrl: text(raw?.tokenUrl),
+    clientId: text(raw?.clientId),
+    clientSecret: text(raw?.clientSecret)
+  });
+  let authorizationUrl = null;
+  let refreshToken = null;
+  if (auth === 'interactive') {
+    authorizationUrl = validateHttpsUrl(text(raw?.authorizationUrl), 'DATASPHERE', 'AUTHORIZATION_URL').href;
+    refreshToken = text(raw?.refreshToken);
+    if (!refreshToken) {
+      fail('DATASPHERE_REFRESH_TOKEN is required for interactive sign-in; run sap-ai-dev --setup-datasphere');
+    }
+  }
+  return Object.freeze({
+    source,
+    auth,
+    url: base.url,
+    tokenUrl: base.tokenUrl,
+    clientId: base.clientId,
+    clientSecret: base.clientSecret,
+    authorizationUrl,
+    refreshToken,
+    sql: parseSql(raw?.sql)
+  });
+}
+
+function sqlFromEnv(env) {
+  if (!ALL_SQL_KEYS.some(key => env[key] !== undefined && env[key] !== '')) return undefined;
+  const missing = SQL_KEYS.filter(key => !text(env[key]));
+  if (missing.length) fail(`Explicit DATASPHERE_SQL configuration is incomplete: ${missing.join(', ')}`);
+  return parseSql({
+    host: env.DATASPHERE_SQL_HOST,
+    port: env.DATASPHERE_SQL_PORT,
+    user: env.DATASPHERE_SQL_USER,
+    password: env.DATASPHERE_SQL_PASSWORD,
+    schema: env.DATASPHERE_SQL_SCHEMA
+  });
+}
+
+/**
+ * Resolve Datasphere credentials. Base group: environment, then the record stored by
+ * `sap-ai-dev --setup-datasphere`. The Open SQL group is resolved independently.
+ */
+export function resolveDatasphereConfig(env = process.env, { stored } = {}) {
+  let config;
+  if (BASE_KEYS.some(key => env[key] !== undefined && env[key] !== '')) {
+    const missing = BASE_KEYS.filter(key => !text(env[key]));
+    if (missing.length) fail(`Explicit DATASPHERE configuration is incomplete: ${missing.join(', ')}`);
+    config = parseDatasphereCredentials({
+      auth: env.DATASPHERE_AUTH,
+      url: env.DATASPHERE_URL,
+      tokenUrl: env.DATASPHERE_TOKEN_URL,
+      clientId: env.DATASPHERE_CLIENT_ID,
+      clientSecret: env.DATASPHERE_CLIENT_SECRET,
+      authorizationUrl: env.DATASPHERE_AUTHORIZATION_URL,
+      refreshToken: env.DATASPHERE_REFRESH_TOKEN,
+      sql: sqlFromEnv(env)
+    }, 'environment');
+  } else if (stored) {
+    config = parseDatasphereCredentials({
+      auth: stored.auth,
+      url: stored.url,
+      tokenUrl: stored.tokenurl,
+      clientId: stored.clientid,
+      clientSecret: stored.clientsecret,
+      authorizationUrl: stored.authorizationurl,
+      refreshToken: stored.refreshtoken,
+      sql: stored.sql
+    }, 'stored-key');
+    const sql = sqlFromEnv(env);
+    if (sql) config = Object.freeze({ ...config, sql });
+  } else {
+    fail('Configure Datasphere (DATASPHERE_URL/DATASPHERE_TOKEN_URL/DATASPHERE_CLIENT_ID/DATASPHERE_CLIENT_SECRET) in the MCP host environment, or run sap-ai-dev --setup-datasphere.');
+  }
+  return config;
+}

package/src/datasphere-credentials.mjs

@@ -0,0 +1,37 @@
+// User-only store for Datasphere OAuth client credentials (never mcp.json):
+// ~/.config/sap-ai-dev-toolkit/datasphere.json, mode 0600, atomic writes.
+import { readFileSync } from 'node:fs';
+import { userConfigFilePath, writeUserOnlyJson } from './integration-credentials.mjs';
+
+export function datasphereCredentialsPath(env = process.env) {
+  return userConfigFilePath(env, 'datasphere.json');
+}
+
+/** Stored record ({ auth, url, tokenurl, clientid, clientsecret, authorizationurl?, refreshtoken?, sql? }); undefined when absent. */
+export function readStoredDatasphereCredentials(env = process.env) {
+  const path = datasphereCredentialsPath(env);
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return undefined;
+    throw new Error(`Stored Datasphere credentials at ${path} could not be read`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`Stored Datasphere credentials at ${path} are not valid JSON; rerun sap-ai-dev --setup-datasphere`);
+  }
+}
+
+export async function storeDatasphereCredentials(record, env = process.env) {
+  return writeUserOnlyJson(datasphereCredentialsPath(env), record);
+}
+
+/** Persist a rotated refresh token without touching the rest of the record. */
+export async function updateStoredRefreshToken(refreshToken, env = process.env) {
+  const path = datasphereCredentialsPath(env);
+  const stored = readStoredDatasphereCredentials(env);
+  if (!stored) throw new Error(`Stored Datasphere credentials at ${path} could not be read`);
+  return writeUserOnlyJson(path, { ...stored, refreshtoken: refreshToken });
+}

package/src/datasphere-csn.mjs

@@ -0,0 +1,73 @@
+// Pure CSN builder for Datasphere local tables from BW/Data Dictionary field
+// lists (shape from the CLI guide "Create Objects" example). No I/O.
+import { IntegrationError } from './integration-http.mjs';
+
+const STRING_TYPES = new Set(['CHAR', 'NUMC', 'CUKY', 'UNIT', 'LANG', 'CLNT', 'ACCP', 'SSTRING']);
+const DECIMAL_TYPES = new Set(['DEC', 'CURR', 'QUAN']);
+const INTEGER_TYPES = new Set(['INT1', 'INT2', 'INT4']);
+
+function columnName(name) {
+  return String(name)
+    .replace(/^\/(?:BIC|BI0)\//, '')
+    .replace(/[^A-Za-z0-9_]/g, '_');
+}
+
+function positiveLength(field) {
+  const length = Number(field.length);
+  if (!Number.isInteger(length) || length < 1) {
+    throw new IntegrationError(`${field.name} needs length`);
+  }
+  return length;
+}
+
+function elementType(field) {
+  const type = String(field.ddic_type || '').toUpperCase();
+  if (STRING_TYPES.has(type)) return { type: 'cds.String', length: positiveLength(field) };
+  if (type === 'STRING') return { type: 'cds.LargeString' };
+  if (type === 'DATS') return { type: 'cds.Date' };
+  if (type === 'TIMS') return { type: 'cds.Time' };
+  if (DECIMAL_TYPES.has(type)) {
+    const decimals = Number(field.decimals);
+    return { type: 'cds.Decimal', precision: positiveLength(field), scale: Number.isInteger(decimals) && decimals >= 0 ? decimals : 0 };
+  }
+  if (INTEGER_TYPES.has(type)) return { type: 'cds.Integer' };
+  if (type === 'INT8') return { type: 'cds.Integer64' };
+  if (type === 'FLTP') return { type: 'cds.Double' };
+  if (type === 'RAW') return { type: 'cds.Binary', length: positiveLength(field) };
+  throw new IntegrationError(`Unsupported DDIC type ${field.ddic_type} for ${field.name}`);
+}
+
+/**
+ * Build a Datasphere local-table CSN definition:
+ * buildLocalTableCsn({ technicalName, businessName, fields }) where each field is
+ * { name, label?, ddic_type, length?, decimals?, key? }.
+ */
+export function buildLocalTableCsn({ technicalName, businessName, fields }) {
+  if (!technicalName || typeof technicalName !== 'string') throw new IntegrationError('technical_name is required');
+  const elements = {};
+  const byColumn = new Map();
+  for (const field of Array.isArray(fields) ? fields : []) {
+    const column = columnName(field.name);
+    const previous = byColumn.get(column);
+    if (previous) {
+      throw new IntegrationError(`Columns ${previous} and ${field.name} both map to ${column}`);
+    }
+    byColumn.set(column, field.name);
+    elements[column] = {
+      '@EndUserText.label': String(field.label ?? field.name),
+      ...elementType(field),
+      ...(field.key ? { key: true, notNull: true } : {})
+    };
+  }
+  return {
+    definitions: {
+      [technicalName]: {
+        kind: 'entity',
+        '@EndUserText.label': String(businessName ?? technicalName),
+        '@ObjectModel.modelingPattern': { '#': 'DATA_STRUCTURE' },
+        '@ObjectModel.supportedCapabilities': [{ '#': 'DATA_STRUCTURE' }],
+        elements
+      }
+    }
+  };
+}

package/src/datasphere-discovery.mjs

@@ -0,0 +1,151 @@
+// Datasphere command discovery: the tenant OpenAPI discovery document drives the
+// generic CLI tools. Primary source is the REST tenant (same document the CLI
+// itself uses); fallback is the CLI's local discovery cache after `config cache init`.
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { IntegrationError } from './integration-http.mjs';
+
+const DISCOVERY_PATH = '/dwaas-core/api/v1/discovery';
+const METHODS = ['get', 'post', 'put', 'patch', 'delete'];
+const TECHNICAL_USER_PREFIXES = ['configuration certificates', 'marketplace', 'objects', 'spaces connections', 'tasks'];
+const DESCRIPTION_CAP = 300;
+
+const kebab = name => String(name)
+  .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+  .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+  .replace(/[^A-Za-z0-9]+/g, '-')
+  .replace(/^-+|-+$/g, '')
+  .toLowerCase();
+
+function resolveRef(document, ref) {
+  if (!ref || typeof ref !== 'string' || !ref.startsWith('#/')) return null;
+  let node = document;
+  for (const segment of ref.slice(2).split('/')) {
+    node = node?.[segment];
+    if (node === undefined) return null;
+  }
+  return node || null;
+}
+
+function bodyPropertyNames(document, requestBody) {
+  const body = requestBody?.$ref ? (resolveRef(document, requestBody.$ref) || requestBody) : requestBody;
+  const schema = body?.content?.['application/json']?.schema;
+  const resolved = schema?.$ref ? (resolveRef(document, schema.$ref) || schema) : schema;
+  const properties = resolved?.properties;
+  if (!properties || typeof properties !== 'object') return [];
+  return Object.keys(properties);
+}
+
+function catalogEntry(document, op, method, command) {
+  const parameters = [];
+  for (const parameter of Array.isArray(op.parameters) ? op.parameters : []) {
+    const resolved = parameter?.$ref ? (resolveRef(document, parameter.$ref) || parameter) : parameter;
+    if (!resolved?.name || !['path', 'query', 'header'].includes(resolved.in)) continue;
+    parameters.push({
+      name: resolved.name,
+      in: resolved.in,
+      required: Boolean(resolved.required),
+      option: `--${kebab(resolved.name)}`
+    });
+  }
+  const fileBodyOnly = Boolean(op['x-requestbody-fileonly']);
+  const hasBody = Boolean(op.requestBody) || fileBodyOnly;
+  if (hasBody) {
+    for (const name of bodyPropertyNames(document, op.requestBody)) {
+      parameters.push({ name, in: 'body', required: false, option: `--${kebab(name)}` });
+    }
+  }
+  return {
+    command,
+    method,
+    summary: typeof op.summary === 'string' ? op.summary : '',
+    description: String(op.description || op.summary || '').replace(/\s+/g, ' ').trim().slice(0, DESCRIPTION_CAP),
+    deprecated: Boolean(op.deprecated),
+    confirm_required: Boolean(op['x-user-to-confirm']),
+    file_body_only: fileBodyOnly,
+    has_body: hasBody,
+    access: method === 'get' ? 'read' : method === 'delete' ? 'delete' : 'write',
+    technical_user_supported: TECHNICAL_USER_PREFIXES.some(prefix => command.startsWith(prefix)),
+    parameters
+  };
+}
+
+function catalogFromDocument(document) {
+  const entries = [];
+  for (const item of Object.values(document?.paths || {})) {
+    if (!item || typeof item !== 'object') continue;
+    const sharedParameters = Array.isArray(item.parameters) ? item.parameters : [];
+    for (const method of METHODS) {
+      const op = item[method];
+      if (!op || typeof op !== 'object') continue;
+      const withShared = sharedParameters.length ? { ...op, parameters: [...sharedParameters, ...(op.parameters || [])] } : op;
+      const ids = Array.isArray(op.operationId) ? op.operationId : [op.operationId];
+      for (const id of ids) {
+        if (typeof id === 'string') {
+          entries.push(catalogEntry(document, withShared, method, id.split(' ').filter(Boolean).join(' ')));
+        } else if (id && typeof id === 'object' && typeof id.operationId === 'string') {
+          const merged = { ...withShared, ...id };
+          entries.push(catalogEntry(document, merged, method, id.operationId.split(' ').filter(Boolean).join(' ')));
+        }
+      }
+    }
+  }
+  const seen = new Map();
+  for (const entry of entries.filter(entry => entry.command)) seen.set(`${entry.command} ${entry.method}`, entry);
+  return [...seen.values()].sort((a, b) => a.command.localeCompare(b.command));
+}
+
+async function newestCacheFile(stateDir) {
+  const root = join(stateDir, '.@sap');
+  let entries;
+  try {
+    entries = await readdir(root, { recursive: true, withFileTypes: true });
+  } catch {
+    return null;
+  }
+  let newest = null;
+  for (const entry of entries) {
+    if (typeof entry.isDirectory === 'function' ? entry.isDirectory() : true) continue;
+    const base = String(entry.name).split(/[\\/]/).pop();
+    if (!base.startsWith('discovery-') || !base.endsWith('.json') || base === 'discovery-metadata.json') continue;
+    const path = join(entry.parentPath || entry.path, entry.name);
+    const mtime = (await stat(path).catch(() => null))?.mtimeMs;
+    if (mtime !== undefined && (!newest || mtime > newest.mtime)) newest = { path, mtime };
+  }
+  return newest?.path || null;
+}
+
+/**
+ * Load the Datasphere CLI command catalog from the tenant discovery document
+ * (REST), falling back to the CLI's cached discovery JSON.
+ */
+export async function loadDatasphereCommands({ rest, cli } = {}) {
+  const failures = [];
+  if (rest) {
+    try {
+      const document = await rest.request('GET', DISCOVERY_PATH, { accept: 'application/json' });
+      const catalog = catalogFromDocument(document);
+      if (catalog.length) return catalog;
+      failures.push('discovery document contained no commands');
+    } catch (error) {
+      failures.push(error?.message || String(error));
+    }
+  } else {
+    failures.push('no REST client');
+  }
+  if (cli) {
+    try {
+      await cli.init();
+      const path = await newestCacheFile(cli.stateDir());
+      if (!path) throw new Error('no cached discovery document');
+      const catalog = catalogFromDocument(JSON.parse(await readFile(path, 'utf8')));
+      if (catalog.length) return catalog;
+      failures.push('cached discovery document contained no commands');
+    } catch (error) {
+      failures.push(error?.message || String(error));
+    }
+  } else {
+    failures.push('no CLI runtime');
+  }
+  throw new IntegrationError(`Datasphere command discovery is unavailable: ${failures.join('; ')}`);
+}