fix: improve ingest runtime readiness

packages/cli/src/runtime-requirements.ts

@@ -0,0 +1,168 @@
+import { MANAGED_SENTENCE_TRANSFORMERS_BASE_URL } from '@ktx/context';
+import type {
+  KtxProjectConfig,
+  KtxProjectConnectionConfig,
+  KtxProjectEmbeddingConfig,
+} from '@ktx/context/project';
+import type { KtxRuntimeFeature } from './managed-python-runtime.js';
+import type { KtxPublicIngestPlan } from './public-ingest.js';
+
+type KtxRuntimeRequirementReason =
+  | 'agent-mcp'
+  | 'query-history'
+  | 'looker-source'
+  | 'database-introspection'
+  | 'local-embeddings';
+
+interface KtxRuntimeRequirement {
+  feature: KtxRuntimeFeature;
+  reason: KtxRuntimeRequirementReason;
+  detail: string;
+}
+
+export interface KtxRuntimeRequirements {
+  features: KtxRuntimeFeature[];
+  requirements: KtxRuntimeRequirement[];
+}
+
+export interface KtxProjectRuntimeRequirementOptions {
+  agents?: boolean;
+  databaseIntrospectionFallback?: boolean;
+  env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+}
+
+export interface KtxPublicIngestRuntimeRequirementOptions {
+  env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+}
+
+function normalizeDriver(driver: unknown): string {
+  return String(driver ?? '').trim().toLowerCase();
+}
+
+function recordValue(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : {};
+}
+
+function hasEnabledQueryHistory(connection: KtxProjectConnectionConfig): boolean {
+  const context = recordValue(recordValue(connection).context);
+  const queryHistory = recordValue(context.queryHistory);
+  return queryHistory.enabled === true;
+}
+
+function hasDaemonOverride(env: NodeJS.ProcessEnv | Record<string, string | undefined>): boolean {
+  return typeof env.KTX_DAEMON_URL === 'string' && env.KTX_DAEMON_URL.trim().length > 0;
+}
+
+function hasSqlAnalysisOverride(env: NodeJS.ProcessEnv | Record<string, string | undefined>): boolean {
+  return (
+    (typeof env.KTX_SQL_ANALYSIS_URL === 'string' && env.KTX_SQL_ANALYSIS_URL.trim().length > 0) ||
+    hasDaemonOverride(env)
+  );
+}
+
+function requiresManagedLocalEmbeddings(embeddings: KtxProjectEmbeddingConfig): boolean {
+  if (embeddings.backend !== 'sentence-transformers') {
+    return false;
+  }
+  const baseUrl = embeddings.sentenceTransformers?.base_url;
+  return baseUrl === undefined || baseUrl === '' || baseUrl === MANAGED_SENTENCE_TRANSFORMERS_BASE_URL;
+}
+
+function uniqueRequirements(requirements: KtxRuntimeRequirement[]): KtxRuntimeRequirements {
+  const seen = new Set<string>();
+  const deduped: KtxRuntimeRequirement[] = [];
+  for (const requirement of requirements) {
+    const key = `${requirement.feature}:${requirement.reason}:${requirement.detail}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    deduped.push(requirement);
+  }
+  const features = [...new Set(deduped.map((requirement) => requirement.feature))].sort((left, right) =>
+    left.localeCompare(right),
+  );
+  return { features, requirements: deduped };
+}
+
+export function resolveProjectRuntimeRequirements(
+  config: KtxProjectConfig,
+  options: KtxProjectRuntimeRequirementOptions = {},
+): KtxRuntimeRequirements {
+  const env = options.env ?? process.env;
+  const requirements: KtxRuntimeRequirement[] = [];
+
+  if (options.agents === true) {
+    requirements.push({
+      feature: 'core',
+      reason: 'agent-mcp',
+      detail: 'Agent MCP setup uses semantic-layer query tools and SQL validation.',
+    });
+  }
+
+  if (options.databaseIntrospectionFallback === true && !hasDaemonOverride(env)) {
+    requirements.push({
+      feature: 'core',
+      reason: 'database-introspection',
+      detail: 'Database introspection fallback uses the Python daemon.',
+    });
+  }
+
+  for (const [connectionId, connection] of Object.entries(config.connections)) {
+    const driver = normalizeDriver(connection.driver);
+    if ((driver === 'looker' || driver === 'local_looker') && !hasDaemonOverride(env)) {
+      requirements.push({
+        feature: 'core',
+        reason: 'looker-source',
+        detail: `${connectionId} uses Looker identifier parsing.`,
+      });
+    }
+
+    if (hasEnabledQueryHistory(connection) && !hasSqlAnalysisOverride(env)) {
+      requirements.push({
+        feature: 'core',
+        reason: 'query-history',
+        detail: `${connectionId} has query history enabled.`,
+      });
+    }
+  }
+
+  if (requiresManagedLocalEmbeddings(config.ingest.embeddings)) {
+    requirements.push({
+      feature: 'local-embeddings',
+      reason: 'local-embeddings',
+      detail: 'Local sentence-transformers embeddings use the managed Python runtime.',
+    });
+  }
+
+  return uniqueRequirements(requirements);
+}
+
+export function resolvePublicIngestRuntimeRequirements(
+  plan: KtxPublicIngestPlan,
+  options: KtxPublicIngestRuntimeRequirementOptions = {},
+): KtxRuntimeRequirements {
+  const env = options.env ?? process.env;
+  const requirements: KtxRuntimeRequirement[] = [];
+
+  for (const target of plan.targets) {
+    const driver = normalizeDriver(target.driver);
+    const adapter = normalizeDriver(target.adapter);
+    if (target.queryHistory?.enabled === true && !hasSqlAnalysisOverride(env)) {
+      requirements.push({
+        feature: 'core',
+        reason: 'query-history',
+        detail: `${target.connectionId} query-history ingest uses SQL analysis.`,
+      });
+    }
+    if ((driver === 'looker' || driver === 'local_looker' || adapter === 'looker') && !hasDaemonOverride(env)) {
+      requirements.push({
+        feature: 'core',
+        reason: 'looker-source',
+        detail: `${target.connectionId} uses Looker identifier parsing.`,
+      });
+    }
+  }
+
+  return uniqueRequirements(requirements);
+}