npm - @useatlas/create - Versions diffs - 0.0.1 - Mend

@useatlas/create 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (515) hide show

package/templates/docker/src/lib/scheduler/format-email.ts ADDED Viewed

@@ -0,0 +1,109 @@
+/**
+ * Email formatter for scheduled task results.
+ *
+ * Produces inline-styled HTML suitable for email clients (no external CSS).
+ */
+import type { ScheduledTask } from "@atlas/api/lib/scheduled-tasks";
+import type { AgentQueryResult } from "@atlas/api/lib/agent-query";
+const MAX_DATA_ROWS = 50;
+export function formatEmailReport(
+  task: ScheduledTask,
+  result: AgentQueryResult,
+): { subject: string; body: string } {
+  const subject = `Atlas Report: ${task.name}`;
+  const sections: string[] = [];
+  // Header
+  sections.push(`
+    <div style="background:#f8f9fa;padding:16px 24px;border-bottom:2px solid #e9ecef;">
+      <h2 style="margin:0;color:#212529;font-size:20px;">${escapeHtml(task.name)}</h2>
+      <p style="margin:4px 0 0;color:#6c757d;font-size:14px;">Question: ${escapeHtml(task.question)}</p>
+    </div>
+  `);
+  // Answer
+  const answer = result.answer || "No answer generated.";
+  sections.push(`
+    <div style="padding:16px 24px;">
+      <h3 style="margin:0 0 8px;color:#495057;font-size:16px;">Answer</h3>
+      <p style="margin:0;color:#212529;font-size:14px;line-height:1.6;white-space:pre-wrap;">${escapeHtml(answer)}</p>
+    </div>
+  `);
+  // Data tables
+  for (const dataset of result.data) {
+    if (!dataset.columns.length || !dataset.rows.length) continue;
+    const displayRows = dataset.rows.slice(0, MAX_DATA_ROWS);
+    const truncated = dataset.rows.length > MAX_DATA_ROWS;
+    const headerCells = dataset.columns
+      .map((col) => `<th style="padding:8px 12px;text-align:left;border-bottom:2px solid #dee2e6;background:#f8f9fa;font-size:12px;color:#495057;">${escapeHtml(col)}</th>`)
+      .join("");
+    const bodyRows = displayRows
+      .map((row) => {
+        const cells = dataset.columns
+          .map((col) => `<td style="padding:6px 12px;border-bottom:1px solid #e9ecef;font-size:13px;color:#212529;">${escapeHtml(String(row[col] ?? ""))}</td>`)
+          .join("");
+        return `<tr>${cells}</tr>`;
+      })
+      .join("");
+    let tableHtml = `
+      <div style="padding:0 24px 16px;">
+        <table style="border-collapse:collapse;width:100%;font-family:monospace;">
+          <thead><tr>${headerCells}</tr></thead>
+          <tbody>${bodyRows}</tbody>
+        </table>
+    `;
+    if (truncated) {
+      tableHtml += `<p style="margin:4px 0 0;color:#6c757d;font-size:12px;">Showing first ${MAX_DATA_ROWS} of ${dataset.rows.length} rows</p>`;
+    }
+    tableHtml += `</div>`;
+    sections.push(tableHtml);
+  }
+  // SQL
+  if (result.sql.length > 0) {
+    const sqlText = result.sql.join("\n\n");
+    sections.push(`
+      <div style="padding:0 24px 16px;">
+        <h3 style="margin:0 0 8px;color:#495057;font-size:14px;">SQL</h3>
+        <pre style="background:#f1f3f5;padding:12px;border-radius:4px;overflow-x:auto;font-size:12px;color:#495057;margin:0;">${escapeHtml(sqlText)}</pre>
+      </div>
+    `);
+  }
+  // Footer
+  sections.push(`
+    <div style="border-top:1px solid #e9ecef;padding:12px 24px;color:#adb5bd;font-size:12px;">
+      ${result.steps} steps &middot; ${result.usage.totalTokens.toLocaleString()} tokens &middot; ${new Date().toISOString()}
+    </div>
+  `);
+  const body = `
+    <!DOCTYPE html>
+    <html>
+    <body style="margin:0;padding:0;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;background:#ffffff;">
+      <div style="max-width:700px;margin:0 auto;border:1px solid #e9ecef;border-radius:8px;overflow:hidden;">
+        ${sections.join("")}
+      </div>
+    </body>
+    </html>
+  `;
+  return { subject, body };
+}
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}

package/templates/docker/src/lib/scheduler/format-slack.ts ADDED Viewed

@@ -0,0 +1,35 @@
+/**
+ * Slack formatter for scheduled task results.
+ *
+ * Reuses formatQueryResponse() from the Slack module and prepends a header
+ * block with the task name and question.
+ */
+import type { ScheduledTask } from "@atlas/api/lib/scheduled-tasks";
+import type { AgentQueryResult } from "@atlas/api/lib/agent-query";
+import { formatQueryResponse, type SlackBlock } from "@atlas/api/lib/slack/format";
+export function formatSlackReport(
+  task: ScheduledTask,
+  result: AgentQueryResult,
+): { text: string; blocks: SlackBlock[] } {
+  const headerBlock: SlackBlock = {
+    type: "section",
+    text: {
+      type: "mrkdwn",
+      text: `:chart_with_upwards_trend: *${task.name}*\n_${truncate(task.question, 200)}_`,
+    },
+  };
+  const resultBlocks = formatQueryResponse(result);
+  return {
+    text: `Atlas Report: ${task.name} — ${truncate(result.answer || "No answer", 100)}`,
+    blocks: [headerBlock, ...resultBlocks],
+  };
+}
+function truncate(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text;
+  return text.slice(0, maxLength - 3) + "...";
+}

package/templates/docker/src/lib/scheduler/format-webhook.ts ADDED Viewed

@@ -0,0 +1,37 @@
+/**
+ * Webhook formatter for scheduled task results.
+ *
+ * Produces a structured JSON payload with all query data.
+ */
+import type { ScheduledTask } from "@atlas/api/lib/scheduled-tasks";
+import type { AgentQueryResult } from "@atlas/api/lib/agent-query";
+export interface WebhookPayload {
+  taskId: string;
+  taskName: string;
+  question: string;
+  answer: string;
+  sql: string[];
+  data: { columns: string[]; rows: Record<string, unknown>[] }[];
+  steps: number;
+  usage: { totalTokens: number };
+  timestamp: string;
+}
+export function formatWebhookPayload(
+  task: ScheduledTask,
+  result: AgentQueryResult,
+): WebhookPayload {
+  return {
+    taskId: task.id,
+    taskName: task.name,
+    question: task.question,
+    answer: result.answer || "",
+    sql: result.sql,
+    data: result.data,
+    steps: result.steps,
+    usage: result.usage,
+    timestamp: new Date().toISOString(),
+  };
+}

package/templates/docker/src/lib/scheduler/index.ts ADDED Viewed

@@ -0,0 +1,7 @@
+/**
+ * Scheduler barrel — re-exports for clean imports.
+ */
+export { getScheduler, triggerTask, runTick, _resetScheduler, type TickResult } from "./engine";
+export { executeScheduledTask, type ExecutionResult } from "./executor";
+export { deliverResult, type DeliverySummary } from "./delivery";

package/templates/docker/src/lib/security.ts ADDED Viewed

@@ -0,0 +1,11 @@
+/**
+ * Shared sensitive-pattern regex.
+ *
+ * Used by both the SQL tool (to scrub error messages before returning
+ * them to the agent) and the audit logger (to scrub error strings before
+ * persisting them). Keeping a single source of truth prevents the two
+ * lists from drifting apart.
+ */
+export const SENSITIVE_PATTERNS =
+  /password|secret|credential|connection.?string|pg_hba\.conf|SSL|certificate|Access denied for user|ER_ACCESS_DENIED_ERROR|ER_DBACCESS_DENIED_ERROR|ER_BAD_HOST_ERROR|ER_HOST_NOT_PRIVILEGED|ER_SPECIFIC_ACCESS_DENIED_ERROR|PROTOCOL_CONNECTION_LOST|Can't connect to MySQL server|Authentication failed|DB::Exception.*Authentication|UNKNOWN_USER|WRONG_PASSWORD|REQUIRED_PASSWORD|IP_ADDRESS_NOT_ALLOWED|ALL_CONNECTION_TRIES_FAILED|CLIENT_HAS_CONNECTED_TO_WRONG_PORT|AUTHENTICATION_FAILED|INVALID_SESSION_ID|LOGIN_MUST_USE_SECURITY_TOKEN|INVALID_LOGIN|INVALID_CLIENT_ID/i;

package/templates/docker/src/lib/semantic-index.ts ADDED Viewed

@@ -0,0 +1,503 @@
+/**
+ * Pre-indexed semantic layer summary.
+ *
+ * Reads all entity YAMLs, metrics YAMLs, catalog, and glossary at boot
+ * (or on cache invalidation) and builds a compressed text summary that
+ * the agent can use without calling the explore tool.
+ *
+ * Two modes based on entity count:
+ * - Small (< 20 entities): full column details in prompt
+ * - Large (20+ entities): table-level summaries only
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "js-yaml";
+import { createLogger } from "@atlas/api/lib/logger";
+const log = createLogger("semantic-index");
+/** Threshold: layers with fewer entities get full column detail. */
+const SMALL_LAYER_THRESHOLD = 20;
+/** Approximate characters per token (conservative estimate for English). */
+const CHARS_PER_TOKEN = 4;
+// --- Types for parsed YAML ---
+interface EntityDimension {
+  name?: string;
+  sql?: string;
+  type?: string;
+  description?: string;
+  sample_values?: unknown[];
+  primary_key?: boolean;
+}
+interface EntityMeasure {
+  name?: string;
+  sql?: string;
+  type?: string;
+  description?: string;
+  aggregation?: string;
+}
+interface EntityJoin {
+  target_entity?: string;
+  relationship?: string;
+  description?: string;
+  join_columns?: Record<string, string>;
+}
+interface EntityQueryPattern {
+  name?: string;
+  description?: string;
+  sql?: string;
+}
+interface ParsedEntity {
+  name?: string;
+  table: string;
+  type?: string;
+  connection?: string;
+  grain?: string;
+  description?: string;
+  dimensions?: EntityDimension[];
+  measures?: EntityMeasure[];
+  joins?: EntityJoin[];
+  query_patterns?: EntityQueryPattern[];
+}
+interface ParsedMetric {
+  name?: string;
+  description?: string;
+  sql?: string;
+  type?: string;
+  entity?: string;
+  aggregation?: string;
+  unit?: string;
+}
+interface GlossaryTerm {
+  term?: string;
+  definition?: string;
+  status?: string;
+  disambiguation?: string;
+}
+interface CatalogEntry {
+  name?: string;
+  description?: string;
+  use_for?: string[];
+  common_questions?: string[];
+}
+interface ParsedCatalog {
+  version?: string;
+  entities?: CatalogEntry[];
+}
+// --- Index cache ---
+let _cachedIndex: string | null = null;
+let _cachedEntityCount = 0;
+/**
+ * Build or retrieve the cached semantic index.
+ *
+ * @param semanticRoot - Override for the semantic root directory (DI for tests).
+ */
+export function getSemanticIndex(semanticRoot?: string): string {
+  if (_cachedIndex !== null) return _cachedIndex;
+  const root = semanticRoot ?? path.resolve(process.cwd(), "semantic");
+  _cachedIndex = buildSemanticIndex(root);
+  return _cachedIndex;
+}
+/** Returns the entity count from the last index build. */
+export function getIndexedEntityCount(): number {
+  return _cachedEntityCount;
+}
+/** Clear the cached index (called on semantic layer changes). */
+export function invalidateSemanticIndex(): void {
+  _cachedIndex = null;
+  _cachedEntityCount = 0;
+}
+/**
+ * Build a compressed text summary of the entire semantic layer.
+ */
+export function buildSemanticIndex(semanticRoot: string): string {
+  const entities = loadEntities(semanticRoot);
+  const metrics = loadMetrics(semanticRoot);
+  const glossary = loadGlossary(semanticRoot);
+  const catalog = loadCatalog(semanticRoot);
+  _cachedEntityCount = entities.length;
+  if (entities.length === 0) {
+    log.info("No entities found — semantic index is empty");
+    return "";
+  }
+  const isSmall = entities.length < SMALL_LAYER_THRESHOLD;
+  const mode = isSmall ? "full" : "summary";
+  const sections: string[] = [];
+  // Header
+  sections.push(
+    `## Semantic Layer Reference (${entities.length} entities, mode: ${mode})`,
+  );
+  // Entity summaries
+  sections.push("");
+  sections.push("### Tables & Columns");
+  for (const entity of entities) {
+    sections.push("");
+    sections.push(formatEntity(entity, isSmall, catalog));
+  }
+  // Metrics
+  if (metrics.length > 0) {
+    sections.push("");
+    sections.push("### Metrics");
+    for (const metric of metrics) {
+      sections.push(formatMetric(metric));
+    }
+  }
+  // Glossary (always include — important for disambiguation)
+  if (glossary.length > 0) {
+    sections.push("");
+    sections.push("### Glossary");
+    for (const term of glossary) {
+      sections.push(formatGlossaryTerm(term));
+    }
+  }
+  const index = sections.join("\n");
+  const tokenEstimate = Math.ceil(index.length / CHARS_PER_TOKEN);
+  log.info(
+    {
+      entityCount: entities.length,
+      metricCount: metrics.length,
+      glossaryTermCount: glossary.length,
+      indexChars: index.length,
+      tokenEstimate,
+      mode,
+    },
+    "Semantic index built (%d entities, ~%dk tokens)",
+    entities.length,
+    Math.round(tokenEstimate / 1000),
+  );
+  return index;
+}
+// --- Formatters ---
+function formatEntity(
+  entity: ParsedEntity,
+  full: boolean,
+  catalog: ParsedCatalog | null,
+): string {
+  const lines: string[] = [];
+  const conn = entity.connection ? ` [${entity.connection}]` : "";
+  const entityType = entity.type ? ` (${entity.type})` : "";
+  lines.push(`**${entity.table}**${entityType}${conn}`);
+  if (entity.description) {
+    // Truncate long descriptions
+    const desc =
+      entity.description.length > 200
+        ? entity.description.slice(0, 197) + "..."
+        : entity.description;
+    lines.push(desc);
+  }
+  if (entity.grain) {
+    lines.push(`Grain: ${entity.grain}`);
+  }
+  // Catalog use_for hints
+  const catalogEntry = catalog?.entities?.find(
+    (e) => e.name === entity.name || e.name === entity.table,
+  );
+  if (catalogEntry?.use_for && catalogEntry.use_for.length > 0) {
+    lines.push(`Use for: ${catalogEntry.use_for.join("; ")}`);
+  }
+  if (full) {
+    // Full mode: list all columns with types
+    if (entity.dimensions && entity.dimensions.length > 0) {
+      lines.push("Columns:");
+      for (const dim of entity.dimensions) {
+        const name = dim.name ?? dim.sql ?? "?";
+        const type = dim.type ?? "unknown";
+        const pk = dim.primary_key ? " PK" : "";
+        const desc = dim.description ? ` — ${dim.description}` : "";
+        lines.push(`  - ${name} (${type}${pk})${desc}`);
+      }
+    }
+    // Measures
+    if (entity.measures && entity.measures.length > 0) {
+      lines.push("Measures:");
+      for (const m of entity.measures) {
+        const name = m.name ?? "?";
+        const agg = m.aggregation ?? m.type ?? "";
+        const desc = m.description ? ` — ${m.description}` : "";
+        lines.push(`  - ${name} [${agg}]${desc}`);
+      }
+    }
+    // Joins
+    if (entity.joins && entity.joins.length > 0) {
+      lines.push("Joins:");
+      for (const j of entity.joins) {
+        const target = j.target_entity ?? "?";
+        const rel = j.relationship ?? "?";
+        lines.push(`  - → ${target} (${rel})`);
+      }
+    }
+    // Query patterns (just names — agent can explore for full SQL)
+    if (entity.query_patterns && entity.query_patterns.length > 0) {
+      const patternNames = entity.query_patterns
+        .map((p) => p.name ?? p.description)
+        .filter(Boolean);
+      if (patternNames.length > 0) {
+        lines.push(`Query patterns: ${patternNames.join(", ")}`);
+      }
+    }
+  } else {
+    // Summary mode: column count + key columns only
+    const dims = entity.dimensions ?? [];
+    const pks = dims.filter((d) => d.primary_key);
+    const colCount = dims.length;
+    const measureCount = entity.measures?.length ?? 0;
+    const joinCount = entity.joins?.length ?? 0;
+    const parts: string[] = [`${colCount} columns`];
+    if (pks.length > 0)
+      parts.push(`PK: ${pks.map((p) => p.name ?? p.sql).join(", ")}`);
+    if (measureCount > 0) parts.push(`${measureCount} measures`);
+    if (joinCount > 0)
+      parts.push(
+        `joins: ${entity.joins!.map((j) => j.target_entity).join(", ")}`,
+      );
+    lines.push(parts.join(" | "));
+  }
+  return lines.join("\n");
+}
+function formatMetric(metric: ParsedMetric): string {
+  const name = metric.name ?? "unnamed";
+  const desc = metric.description ? ` — ${metric.description}` : "";
+  const entity = metric.entity ? ` (${metric.entity})` : "";
+  return `- **${name}**${entity}${desc}`;
+}
+function formatGlossaryTerm(term: GlossaryTerm): string {
+  const name = term.term ?? "?";
+  const status = term.status === "ambiguous" ? " **[AMBIGUOUS]**" : "";
+  const def = term.definition ? `: ${term.definition}` : "";
+  const disambig = term.disambiguation
+    ? ` → ${term.disambiguation}`
+    : "";
+  return `- **${name}**${status}${def}${disambig}`;
+}
+// --- Loaders ---
+function loadEntities(semanticRoot: string): ParsedEntity[] {
+  const entities: ParsedEntity[] = [];
+  // Default entities
+  loadEntitiesFromDir(path.join(semanticRoot, "entities"), entities);
+  // Per-source subdirectories
+  if (fs.existsSync(semanticRoot)) {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(semanticRoot, { withFileTypes: true });
+    } catch (err) {
+      log.warn({ semanticRoot, err: err instanceof Error ? err.message : String(err) }, "Failed to scan semantic root for per-source entity directories");
+      return entities;
+    }
+    const reserved = new Set(["entities", "metrics"]);
+    for (const entry of entries) {
+      if (!entry.isDirectory() || reserved.has(entry.name)) continue;
+      const subEntities = path.join(semanticRoot, entry.name, "entities");
+      if (fs.existsSync(subEntities)) {
+        loadEntitiesFromDir(subEntities, entities, entry.name);
+      }
+    }
+  }
+  return entities;
+}
+function loadEntitiesFromDir(
+  dir: string,
+  out: ParsedEntity[],
+  connectionId?: string,
+): void {
+  if (!fs.existsSync(dir)) return;
+  let files: string[];
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith(".yml"));
+  } catch (err) {
+    log.warn({ dir, err: err instanceof Error ? err.message : String(err) }, "Failed to read entities directory for semantic index");
+    return;
+  }
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(path.join(dir, file), "utf-8");
+      const raw = yaml.load(content) as Record<string, unknown> | null;
+      if (!raw || typeof raw !== "object" || !raw.table) continue;
+      const entity: ParsedEntity = {
+        name: raw.name as string | undefined,
+        table: raw.table as string,
+        type: raw.type as string | undefined,
+        connection: (raw.connection as string | undefined) ?? connectionId,
+        grain: raw.grain as string | undefined,
+        description: raw.description as string | undefined,
+        dimensions: Array.isArray(raw.dimensions) ? (raw.dimensions as EntityDimension[]) : undefined,
+        measures: Array.isArray(raw.measures) ? (raw.measures as EntityMeasure[]) : undefined,
+        joins: Array.isArray(raw.joins) ? (raw.joins as EntityJoin[]) : undefined,
+        query_patterns: Array.isArray(raw.query_patterns) ? (raw.query_patterns as EntityQueryPattern[]) : undefined,
+      };
+      out.push(entity);
+    } catch (err) {
+      log.warn({ file, dir, err: err instanceof Error ? err.message : String(err) }, "Skipping entity file in semantic index — failed to read or parse");
+    }
+  }
+}
+function loadMetrics(semanticRoot: string): ParsedMetric[] {
+  const metrics: ParsedMetric[] = [];
+  // Default metrics
+  loadMetricsFromDir(path.join(semanticRoot, "metrics"), metrics);
+  // Per-source subdirectories
+  if (fs.existsSync(semanticRoot)) {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(semanticRoot, { withFileTypes: true });
+    } catch (err) {
+      log.warn({ semanticRoot, err: err instanceof Error ? err.message : String(err) }, "Failed to scan semantic root for per-source metric directories");
+      return metrics;
+    }
+    const reserved = new Set(["entities", "metrics"]);
+    for (const entry of entries) {
+      if (!entry.isDirectory() || reserved.has(entry.name)) continue;
+      const subMetrics = path.join(semanticRoot, entry.name, "metrics");
+      if (fs.existsSync(subMetrics)) {
+        loadMetricsFromDir(subMetrics, metrics);
+      }
+    }
+  }
+  return metrics;
+}
+function loadMetricsFromDir(dir: string, out: ParsedMetric[]): void {
+  if (!fs.existsSync(dir)) return;
+  let files: string[];
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith(".yml"));
+  } catch (err) {
+    log.warn({ dir, err: err instanceof Error ? err.message : String(err) }, "Failed to read metrics directory for semantic index");
+    return;
+  }
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(path.join(dir, file), "utf-8");
+      const raw = yaml.load(content) as Record<string, unknown> | null;
+      if (!raw || typeof raw !== "object") continue;
+      // Metric files may contain a top-level array of metrics or a single metric
+      if (Array.isArray(raw.metrics)) {
+        for (const m of raw.metrics as ParsedMetric[]) {
+          if (m && typeof m === "object") out.push(m);
+        }
+      } else if (raw.name) {
+        out.push(raw as ParsedMetric);
+      }
+    } catch (err) {
+      log.warn({ file, dir, err: err instanceof Error ? err.message : String(err) }, "Skipping metric file in semantic index — failed to read or parse");
+    }
+  }
+}
+function loadGlossary(semanticRoot: string): GlossaryTerm[] {
+  const terms: GlossaryTerm[] = [];
+  // Try root glossary
+  loadGlossaryFile(path.join(semanticRoot, "glossary.yml"), terms);
+  // Per-source glossaries
+  if (fs.existsSync(semanticRoot)) {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(semanticRoot, { withFileTypes: true });
+    } catch (err) {
+      log.warn({ semanticRoot, err: err instanceof Error ? err.message : String(err) }, "Failed to scan semantic root for per-source glossary files");
+      return terms;
+    }
+    const reserved = new Set(["entities", "metrics"]);
+    for (const entry of entries) {
+      if (!entry.isDirectory() || reserved.has(entry.name)) continue;
+      loadGlossaryFile(
+        path.join(semanticRoot, entry.name, "glossary.yml"),
+        terms,
+      );
+    }
+  }
+  return terms;
+}
+function loadGlossaryFile(filePath: string, out: GlossaryTerm[]): void {
+  if (!fs.existsSync(filePath)) return;
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const raw = yaml.load(content) as Record<string, unknown> | null;
+    if (!raw || typeof raw !== "object") return;
+    if (Array.isArray(raw.terms)) {
+      for (const t of raw.terms as GlossaryTerm[]) {
+        if (t && typeof t === "object") out.push(t);
+      }
+    }
+  } catch (err) {
+    log.warn({ filePath, err: err instanceof Error ? err.message : String(err) }, "Failed to load glossary file for semantic index");
+  }
+}
+function loadCatalog(semanticRoot: string): ParsedCatalog | null {
+  const catalogPath = path.join(semanticRoot, "catalog.yml");
+  if (!fs.existsSync(catalogPath)) return null;
+  try {
+    const content = fs.readFileSync(catalogPath, "utf-8");
+    return yaml.load(content) as ParsedCatalog | null;
+  } catch (err) {
+    log.warn({ catalogPath, err: err instanceof Error ? err.message : String(err) }, "Failed to load catalog for semantic index");
+    return null;
+  }
+}