@kaelio/ktx 0.14.0 → 0.16.0

package/dist/context/ingest/adapters/sigma/fetch.js

@@ -0,0 +1,191 @@
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseSigmaPullConfig, stagedDataModelFileSchema, stagedWorkbookFileSchema, STAGED_FILES, } from './types.js';
+const noopLogger = { log: () => undefined, warn: () => undefined };
+async function loadExistingStagedFiles(stagedDir) {
+    const existing = new Map();
+    const dmDir = join(stagedDir, STAGED_FILES.dataModelsDir);
+    let entries;
+    try {
+        entries = await readdir(dmDir);
+    }
+    catch {
+        return existing;
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith('.json'))
+            continue;
+        try {
+            const body = await readFile(join(dmDir, entry), 'utf-8');
+            const parsed = stagedDataModelFileSchema.parse(JSON.parse(body));
+            existing.set(parsed.sigmaId, parsed);
+        }
+        catch {
+            // Skip malformed files.
+        }
+    }
+    return existing;
+}
+async function loadExistingWorkbookFiles(stagedDir) {
+    const existing = new Map();
+    const wbDir = join(stagedDir, STAGED_FILES.workbooksDir);
+    let entries;
+    try {
+        entries = await readdir(wbDir);
+    }
+    catch {
+        return existing;
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith('.json'))
+            continue;
+        try {
+            const body = await readFile(join(wbDir, entry), 'utf-8');
+            const parsed = stagedWorkbookFileSchema.parse(JSON.parse(body));
+            existing.set(parsed.sigmaId, parsed);
+        }
+        catch {
+            // Skip malformed files.
+        }
+    }
+    return existing;
+}
+export async function fetchSigmaBundle({ pullConfig, stagedDir, ctx, clientFactory, logger = noopLogger, }) {
+    const config = parseSigmaPullConfig(pullConfig);
+    const client = await clientFactory.createClient(config, ctx);
+    try {
+        await mkdir(join(stagedDir, STAGED_FILES.dataModelsDir), { recursive: true });
+        await mkdir(join(stagedDir, STAGED_FILES.workbooksDir), { recursive: true });
+        // Load existing staged files to enable incremental sync.
+        const existingByModelId = await loadExistingStagedFiles(stagedDir);
+        const existingByWorkbookId = await loadExistingWorkbookFiles(stagedDir);
+        logger.log('Listing Sigma data models...');
+        const summaries = await client.listDataModels();
+        const nonArchived = summaries.filter((dm) => !dm.isArchived);
+        const nonArchivedIds = new Set(nonArchived.map((dm) => dm.dataModelId));
+        let active = nonArchived;
+        if (config.dataModelFilter?.updatedSince) {
+            const since = new Date(config.dataModelFilter.updatedSince).getTime();
+            active = active.filter((dm) => new Date(dm.updatedAt).getTime() >= since);
+        }
+        logger.log(`Found ${active.length} active data model(s) (${summaries.length} total).`);
+        let fetched = 0;
+        let skipped = 0;
+        const SPEC_CONCURRENCY = 10;
+        const queue = [...active];
+        await Promise.all(Array.from({ length: Math.min(SPEC_CONCURRENCY, queue.length) }, async () => {
+            let summary;
+            while ((summary = queue.shift()) !== undefined) {
+                const existing = existingByModelId.get(summary.dataModelId);
+                // Only skip when the cached spec was successfully fetched. spec: null means
+                // the previous attempt failed transiently — retry regardless of updatedAt.
+                if (existing && existing.updatedAt === summary.updatedAt && existing.spec !== null) {
+                    logger.log(`Unchanged: ${summary.name}`);
+                    skipped++;
+                    continue;
+                }
+                let spec = null;
+                try {
+                    spec = await client.getDataModelSpec(summary.dataModelId);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    if (msg.includes('dataSource subtype not supported')) {
+                        logger.warn(`Skipping spec for "${summary.name}" (${summary.dataModelId}): data source type not supported by Sigma spec export API.`);
+                    }
+                    else {
+                        logger.warn(`Failed to fetch spec for "${summary.name}" (${summary.dataModelId}): ${msg}`);
+                    }
+                }
+                const staged = {
+                    sigmaId: summary.dataModelId,
+                    name: summary.name,
+                    path: summary.path,
+                    latestVersion: summary.latestVersion,
+                    updatedAt: summary.updatedAt,
+                    isArchived: summary.isArchived ?? false,
+                    dataModelUrlId: summary.dataModelUrlId,
+                    spec,
+                };
+                const filePath = join(stagedDir, STAGED_FILES.dataModelsDir, `${summary.dataModelId}.json`);
+                await writeFile(filePath, JSON.stringify(staged, null, 2), 'utf-8');
+                logger.log(`Staged data model: ${summary.name}`);
+                fetched++;
+            }
+        }));
+        // Remove staged files for models that are archived or deleted — but not those merely outside the filter window.
+        for (const [modelId] of existingByModelId) {
+            if (nonArchivedIds.has(modelId))
+                continue;
+            try {
+                await rm(join(stagedDir, STAGED_FILES.dataModelsDir, `${modelId}.json`));
+                logger.log(`Removed stale staged file for model ${modelId}.`);
+            }
+            catch {
+                // Best-effort removal.
+            }
+        }
+        // Fetch workbooks (summary metadata only — no separate spec endpoint).
+        // Fetch the full non-archived/non-exploration universe first so eviction is based on
+        // all known workbooks, not just the updatedSince slice. Mirrors the data-model path.
+        logger.log('Listing Sigma workbooks...');
+        const { updatedSince, ...filterWithoutSince } = config.workbookFilter ?? {};
+        const allWorkbooks = await client.listWorkbooks(filterWithoutSince);
+        const nonArchivedWorkbookIds = new Set(allWorkbooks.map((wb) => wb.workbookId));
+        const activeWorkbooks = updatedSince
+            ? allWorkbooks.filter((wb) => new Date(wb.updatedAt).getTime() >= new Date(updatedSince).getTime())
+            : allWorkbooks;
+        logger.log(`Found ${activeWorkbooks.length} workbook(s) to process (${allWorkbooks.length} total).`);
+        let workbooksFetched = 0;
+        let workbooksSkipped = 0;
+        for (const wb of activeWorkbooks) {
+            const existing = existingByWorkbookId.get(wb.workbookId);
+            if (existing && existing.updatedAt === wb.updatedAt) {
+                workbooksSkipped++;
+                continue;
+            }
+            const staged = {
+                sigmaId: wb.workbookId,
+                name: wb.name,
+                path: wb.path,
+                latestVersion: wb.latestVersion,
+                updatedAt: wb.updatedAt,
+                isArchived: wb.isArchived ?? false,
+                workbookUrlId: wb.workbookUrlId,
+                description: wb.description,
+            };
+            const filePath = join(stagedDir, STAGED_FILES.workbooksDir, `${wb.workbookId}.json`);
+            await writeFile(filePath, JSON.stringify(staged, null, 2), 'utf-8');
+            logger.log(`Staged workbook: ${wb.name}`);
+            workbooksFetched++;
+        }
+        // Evict only workbooks that are archived or deleted — not those outside the updatedSince window.
+        for (const [workbookId] of existingByWorkbookId) {
+            if (nonArchivedWorkbookIds.has(workbookId))
+                continue;
+            try {
+                await rm(join(stagedDir, STAGED_FILES.workbooksDir, `${workbookId}.json`));
+                logger.log(`Removed stale staged file for workbook ${workbookId}.`);
+            }
+            catch {
+                // Best-effort removal.
+            }
+        }
+        const projectionConfig = {
+            connectionMappings: config.connectionMappings ?? {},
+            workbookFilter: config.workbookFilter ?? { includeArchived: false, includeExplorations: false },
+        };
+        await writeFile(join(stagedDir, STAGED_FILES.projectionConfig), JSON.stringify(projectionConfig, null, 2), 'utf-8');
+        const manifest = {
+            sigmaConnectionId: config.sigmaConnectionId,
+            fetchedAt: new Date().toISOString(),
+            dataModelCount: active.length,
+            workbookCount: activeWorkbooks.length,
+        };
+        await writeFile(join(stagedDir, STAGED_FILES.manifest), JSON.stringify(manifest, null, 2), 'utf-8');
+        logger.log(`Sigma fetch complete. Data models: ${fetched} fetched, ${skipped} unchanged. Workbooks: ${workbooksFetched} fetched, ${workbooksSkipped} unchanged.`);
+    }
+    finally {
+        await client.cleanup();
+    }
+}

package/dist/context/ingest/adapters/sigma/local-sigma.adapter.d.ts

@@ -0,0 +1,17 @@
+import type { KtxProjectConnectionConfig } from '../../../../context/project/config.js';
+import type { KtxLocalProject } from '../../../../context/project/project.js';
+import { type SigmaClientConfig } from './client.js';
+import type { SigmaFetchLogger } from './fetch.js';
+import { SigmaSourceAdapter } from './sigma.adapter.js';
+export declare function sigmaRuntimeConfigFromLocalConnection(connectionId: string, connection: KtxProjectConnectionConfig | undefined, env?: NodeJS.ProcessEnv): {
+    apiUrl: string;
+    clientId: string;
+    clientSecret: string;
+};
+interface CreateLocalSigmaSourceAdapterOptions {
+    env?: NodeJS.ProcessEnv;
+    defaultClientConfig?: SigmaClientConfig;
+    logger?: SigmaFetchLogger;
+}
+export declare function createLocalSigmaSourceAdapter(project: KtxLocalProject, options?: CreateLocalSigmaSourceAdapterOptions): SigmaSourceAdapter;
+export {};

package/dist/context/ingest/adapters/sigma/local-sigma.adapter.js

@@ -0,0 +1,41 @@
+import { resolveKtxConfigReference } from '../../../core/config-reference.js';
+import { DEFAULT_SIGMA_CLIENT_CONFIG, DefaultSigmaClient } from './client.js';
+import { SigmaSourceAdapter } from './sigma.adapter.js';
+function stringField(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+export function sigmaRuntimeConfigFromLocalConnection(connectionId, connection, env = process.env) {
+    if (!connection || String(connection.driver).toLowerCase() !== 'sigma') {
+        throw new Error(`Connection "${connectionId}" is not a Sigma connection`);
+    }
+    const apiUrl = stringField(connection.api_url) ?? 'https://api.sigmacomputing.com';
+    const clientId = stringField(connection.client_id);
+    const literalSecret = stringField(connection.client_secret);
+    const secretRef = stringField(connection.client_secret_ref);
+    const clientSecret = literalSecret ?? (secretRef ? (resolveKtxConfigReference(secretRef, env) ?? null) : null);
+    if (!clientId) {
+        throw new Error(`Connection "${connectionId}" is missing Sigma client_id`);
+    }
+    if (!clientSecret) {
+        throw new Error(`Connection "${connectionId}" is missing Sigma client_secret or client_secret_ref`);
+    }
+    return { apiUrl, clientId, clientSecret };
+}
+class LocalSigmaClientFactory {
+    project;
+    options;
+    constructor(project, options) {
+        this.project = project;
+        this.options = options;
+    }
+    createClient(config, _ctx) {
+        const runtimeConfig = sigmaRuntimeConfigFromLocalConnection(config.sigmaConnectionId, this.project.config.connections[config.sigmaConnectionId], this.options.env);
+        return new DefaultSigmaClient(runtimeConfig, this.options.defaultClientConfig ?? DEFAULT_SIGMA_CLIENT_CONFIG);
+    }
+}
+export function createLocalSigmaSourceAdapter(project, options = {}) {
+    return new SigmaSourceAdapter({
+        clientFactory: new LocalSigmaClientFactory(project, options),
+        ...(options.logger ? { logger: options.logger } : {}),
+    });
+}

package/dist/context/ingest/adapters/sigma/project.d.ts

@@ -0,0 +1,8 @@
+import type { SemanticLayerService } from '../../../../context/sl/semantic-layer.service.js';
+import type { DeterministicProjectionContext, ProjectionResult } from '../../types.js';
+type SlService = Pick<SemanticLayerService, 'writeSource'> & {
+    forWorktree(workdir: string): Pick<SemanticLayerService, 'writeSource'>;
+};
+/** @internal */
+export declare function projectSigmaDataModels(ctx: DeterministicProjectionContext, slService: SlService): Promise<ProjectionResult>;
+export {};

package/dist/context/ingest/adapters/sigma/project.js

@@ -0,0 +1,186 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { sigmaProjectionConfigSchema, stagedDataModelFileSchema, STAGED_FILES } from './types.js';
+async function readProjectionConfig(stagedDir) {
+    try {
+        const body = await readFile(join(stagedDir, STAGED_FILES.projectionConfig), 'utf-8');
+        return sigmaProjectionConfigSchema.parse(JSON.parse(body)).connectionMappings;
+    }
+    catch {
+        return {};
+    }
+}
+const SIGMA_AUTHOR = { name: 'Sigma', email: 'system@kaelio.dev' };
+// Best-effort schema for the raw spec blob stored in staged data model files.
+const warehouseTableSourceSchema = z.object({
+    kind: z.literal('warehouse-table'),
+    connectionId: z.string(),
+    path: z.array(z.string()),
+});
+const specColumnSchema = z
+    .object({
+    id: z.string(),
+    formula: z.string().optional(),
+    name: z.string().optional(),
+    hidden: z.boolean().optional(),
+    description: z.string().optional(),
+    format: z.object({ kind: z.string() }).passthrough().optional(),
+})
+    .passthrough();
+const specElementSchema = z
+    .object({
+    id: z.string(),
+    kind: z.string().optional(),
+    name: z.string().optional(),
+    hidden: z.boolean().optional(),
+    source: z.object({ kind: z.string() }).passthrough().optional(),
+    columns: z.array(specColumnSchema).optional(),
+})
+    .passthrough();
+const specPageSchema = z
+    .object({
+    id: z.string(),
+    name: z.string().optional(),
+    elements: z.array(specElementSchema).optional(),
+})
+    .passthrough();
+const sigmaSpecSchema = z
+    .object({
+    name: z.string().optional(),
+    pages: z.array(specPageSchema).optional(),
+})
+    .passthrough();
+/** Extract the column name from a bracket formula like `[TABLE/Column Name]` or `[Column]`. */
+function extractColumnName(formula) {
+    const match = /\[(?:[^\]/]+\/)?([^\]]+)\]/.exec(formula.trim());
+    return match?.[1] ?? null;
+}
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+function inferColumnType(col) {
+    const kind = col.format?.kind;
+    if (kind === 'datetime' || kind === 'date')
+        return 'time';
+    if (kind === 'number' || kind === 'currency' || kind === 'percent')
+        return 'number';
+    return 'string';
+}
+function buildSourceFromElement(dataModelName, elementName, elementId, warehousePath, columns) {
+    const table = warehousePath.join('.');
+    if (!table)
+        return null;
+    const modelSlug = slugify(dataModelName || elementId);
+    const elemSlug = elementName ? slugify(elementName) : '';
+    const sourceName = elemSlug && elemSlug !== modelSlug ? `${modelSlug}_${elemSlug}` : modelSlug;
+    if (!sourceName)
+        return null;
+    const slColumns = [];
+    for (const col of columns) {
+        if (col.hidden)
+            continue;
+        if (!col.formula)
+            continue;
+        // Aggregation formulas (Sum, Count, etc.) are Sigma-specific expressions that don't map to
+        // warehouse columns — skip them silently. The sigma_ingest skill surfaces them as wiki candidates.
+        if (/^[A-Za-z]+\(/.test(col.formula.trim()))
+            continue;
+        const displayName = col.name ?? extractColumnName(col.formula);
+        if (!displayName)
+            continue;
+        const colSlug = slugify(displayName);
+        if (!colSlug)
+            continue;
+        slColumns.push({
+            name: colSlug,
+            type: inferColumnType(col),
+            ...(col.description ? { descriptions: { user: col.description } } : {}),
+        });
+    }
+    const source = {
+        name: sourceName,
+        table,
+        grain: [],
+        columns: slColumns,
+        joins: [],
+        measures: [],
+    };
+    if (dataModelName) {
+        source.descriptions = { user: dataModelName };
+    }
+    return source;
+}
+/** @internal */
+export async function projectSigmaDataModels(ctx, slService) {
+    const svc = ctx.workdir ? slService.forWorktree(ctx.workdir) : slService;
+    const warnings = [];
+    const errors = [];
+    const touchedSources = [];
+    const connectionMappings = await readProjectionConfig(ctx.stagedDir);
+    const dmDir = join(ctx.stagedDir, STAGED_FILES.dataModelsDir);
+    let entries;
+    try {
+        entries = await readdir(dmDir);
+    }
+    catch {
+        return { warnings, errors, touchedSources, changedWikiPageKeys: [] };
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith('.json'))
+            continue;
+        let stagedFile;
+        try {
+            const body = await readFile(join(dmDir, entry), 'utf-8');
+            stagedFile = stagedDataModelFileSchema.parse(JSON.parse(body));
+        }
+        catch {
+            warnings.push(`Skipping malformed staged file: ${entry}`);
+            continue;
+        }
+        if (!stagedFile.spec)
+            continue;
+        let spec;
+        try {
+            spec = sigmaSpecSchema.parse(stagedFile.spec);
+        }
+        catch {
+            warnings.push(`Skipping unparseable spec for data model "${stagedFile.name}"`);
+            continue;
+        }
+        for (const page of spec.pages ?? []) {
+            for (const element of page.elements ?? []) {
+                if (element.hidden)
+                    continue;
+                const warehouseSource = warehouseTableSourceSchema.safeParse(element.source);
+                if (!warehouseSource.success)
+                    continue;
+                const source = buildSourceFromElement(stagedFile.name, element.name, element.id, warehouseSource.data.path, element.columns ?? []);
+                if (!source)
+                    continue;
+                // Only write SL sources for elements whose Sigma connection is mapped to a warehouse connection.
+                // Writing under an unmapped connection produces gate failures because the Sigma connection
+                // is not a warehouse connection and cannot be validated.
+                const targetConnectionId = connectionMappings[warehouseSource.data.connectionId];
+                if (!targetConnectionId) {
+                    warnings.push(`Skipping SL source for "${stagedFile.name}" / "${element.name ?? element.id}": ` +
+                        `no connectionMappings entry for Sigma connection ${warehouseSource.data.connectionId}. ` +
+                        `Add a connectionMappings entry in ktx.yaml to enable SL projection for this element.`);
+                    continue;
+                }
+                try {
+                    const result = await svc.writeSource(targetConnectionId, source, SIGMA_AUTHOR.name, SIGMA_AUTHOR.email, `Sigma: import data model "${stagedFile.name}"`);
+                    touchedSources.push({ connectionId: targetConnectionId, sourceName: source.name });
+                    warnings.push(...result.warnings);
+                }
+                catch (err) {
+                    errors.push(`Failed to write source "${source.name}": ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+    }
+    return { warnings, errors, touchedSources, changedWikiPageKeys: [] };
+}

package/dist/context/ingest/adapters/sigma/sigma.adapter.d.ts

@@ -0,0 +1,18 @@
+import type { ChunkResult, DeterministicProjectionContext, DiffSet, FetchContext, ProjectionResult, SourceAdapter } from '../../types.js';
+import type { SigmaClientFactory } from './client-port.js';
+import { type SigmaFetchLogger } from './fetch.js';
+export interface SigmaSourceAdapterDeps {
+    clientFactory: SigmaClientFactory;
+    logger?: SigmaFetchLogger;
+}
+export declare class SigmaSourceAdapter implements SourceAdapter {
+    private readonly deps;
+    readonly source = "sigma";
+    readonly skillNames: string[];
+    constructor(deps: SigmaSourceAdapterDeps);
+    detect(stagedDir: string): Promise<boolean>;
+    fetch(pullConfig: unknown, stagedDir: string, ctx: FetchContext): Promise<void>;
+    chunk(stagedDir: string, diffSet?: DiffSet): Promise<ChunkResult>;
+    listTargetConnectionIds(stagedDir: string): Promise<string[]>;
+    project(ctx: DeterministicProjectionContext): Promise<ProjectionResult>;
+}

package/dist/context/ingest/adapters/sigma/sigma.adapter.js

@@ -0,0 +1,43 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { chunkSigmaStagedDir } from './chunk.js';
+import { detectSigmaStagedDir } from './detect.js';
+import { fetchSigmaBundle } from './fetch.js';
+import { projectSigmaDataModels } from './project.js';
+import { sigmaProjectionConfigSchema, STAGED_FILES } from './types.js';
+export class SigmaSourceAdapter {
+    deps;
+    source = 'sigma';
+    skillNames = ['sigma_ingest'];
+    constructor(deps) {
+        this.deps = deps;
+    }
+    detect(stagedDir) {
+        return detectSigmaStagedDir(stagedDir);
+    }
+    async fetch(pullConfig, stagedDir, ctx) {
+        await fetchSigmaBundle({
+            pullConfig,
+            stagedDir,
+            ctx,
+            clientFactory: this.deps.clientFactory,
+            ...(this.deps.logger ? { logger: this.deps.logger } : {}),
+        });
+    }
+    chunk(stagedDir, diffSet) {
+        return chunkSigmaStagedDir(stagedDir, { diffSet });
+    }
+    async listTargetConnectionIds(stagedDir) {
+        try {
+            const body = await readFile(join(stagedDir, STAGED_FILES.projectionConfig), 'utf-8');
+            const config = sigmaProjectionConfigSchema.parse(JSON.parse(body));
+            return [...new Set(Object.values(config.connectionMappings))].sort();
+        }
+        catch {
+            return [];
+        }
+    }
+    project(ctx) {
+        return projectSigmaDataModels(ctx, ctx.semanticLayerService);
+    }
+}

package/dist/context/ingest/adapters/sigma/types.d.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+/** Filters applied when listing workbooks. Shared with ListWorkbooksOptions in client-port.ts. */
+declare const workbookFilterSchema: z.ZodObject<{
+    includeArchived: z.ZodDefault<z.ZodBoolean>;
+    includeExplorations: z.ZodDefault<z.ZodBoolean>;
+    updatedSince: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Input shape for listWorkbooks — all fields optional since the client applies its own defaults. */
+export type WorkbookFilterInput = z.input<typeof workbookFilterSchema>;
+/** The lean config the adapter needs at `fetch()` time, stored in the ingest job's `bundleRef.config`. */
+declare const sigmaPullConfigSchema: z.ZodObject<{
+    sigmaConnectionId: z.ZodString;
+    connectionMappings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    workbookFilter: z.ZodDefault<z.ZodObject<{
+        includeArchived: z.ZodDefault<z.ZodBoolean>;
+        includeExplorations: z.ZodDefault<z.ZodBoolean>;
+        updatedSince: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    dataModelFilter: z.ZodOptional<z.ZodObject<{
+        updatedSince: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SigmaPullConfig = z.infer<typeof sigmaPullConfigSchema>;
+export declare function parseSigmaPullConfig(raw: unknown): SigmaPullConfig;
+/** Written to stagedDir during fetch() and read back by project(), listTargetConnectionIds(), and the sigma_ingest skill. */
+export declare const sigmaProjectionConfigSchema: z.ZodObject<{
+    connectionMappings: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    workbookFilter: z.ZodDefault<z.ZodObject<{
+        includeArchived: z.ZodDefault<z.ZodBoolean>;
+        includeExplorations: z.ZodDefault<z.ZodBoolean>;
+        updatedSince: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SigmaProjectionConfig = z.infer<typeof sigmaProjectionConfigSchema>;
+/**
+ * A staged data model file, one per `data-models/<id>.json`.
+ * Stores the summary metadata plus the raw spec blob from GET /v2/dataModels/{id}/spec.
+ */
+export declare const stagedDataModelFileSchema: z.ZodObject<{
+    sigmaId: z.ZodString;
+    name: z.ZodString;
+    path: z.ZodString;
+    latestVersion: z.ZodNumber;
+    updatedAt: z.ZodString;
+    isArchived: z.ZodDefault<z.ZodBoolean>;
+    dataModelUrlId: z.ZodOptional<z.ZodString>;
+    spec: z.ZodUnknown;
+}, z.core.$strip>;
+export type StagedDataModelFile = z.infer<typeof stagedDataModelFileSchema>;
+/** The manifest written once per `fetch()`. Presence acts as the detect() sentinel. */
+export declare const sigmaManifestSchema: z.ZodObject<{
+    sigmaConnectionId: z.ZodString;
+    fetchedAt: z.ZodString;
+    dataModelCount: z.ZodNumber;
+    workbookCount: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type SigmaManifest = z.infer<typeof sigmaManifestSchema>;
+/**
+ * A staged workbook file, one per `workbooks/<id>.json`.
+ * Stores the summary metadata from GET /v2/workbooks (no separate spec endpoint).
+ */
+export declare const stagedWorkbookFileSchema: z.ZodObject<{
+    sigmaId: z.ZodString;
+    name: z.ZodString;
+    path: z.ZodString;
+    latestVersion: z.ZodNumber;
+    updatedAt: z.ZodString;
+    isArchived: z.ZodDefault<z.ZodBoolean>;
+    workbookUrlId: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type StagedWorkbookFile = z.infer<typeof stagedWorkbookFileSchema>;
+/** Filenames inside stagedDir. Centralized so chunk() + fetch() + detect() all agree. */
+export declare const STAGED_FILES: {
+    readonly manifest: "sigma-manifest.json";
+    readonly projectionConfig: "sigma-projection-config.json";
+    readonly dataModelsDir: "data-models";
+    readonly workbooksDir: "workbooks";
+};
+export {};

package/dist/context/ingest/adapters/sigma/types.js

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+const sigmaLocalConnectionIdSchema = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/);
+/** Filters applied when listing workbooks. Shared with ListWorkbooksOptions in client-port.ts. */
+const workbookFilterSchema = z.object({
+    includeArchived: z.boolean().default(false),
+    includeExplorations: z.boolean().default(false),
+    /** ISO 8601 date string. Only workbooks updated on or after this date are included. */
+    updatedSince: z.string().optional(),
+});
+const dataModelFilterSchema = z.object({
+    /** ISO 8601 date string. Only data models updated on or after this date are fetched. */
+    updatedSince: z.string().optional(),
+});
+/** The lean config the adapter needs at `fetch()` time, stored in the ingest job's `bundleRef.config`. */
+const sigmaPullConfigSchema = z.object({
+    /** The ktx connection ID for the Sigma instance being swept. */
+    sigmaConnectionId: sigmaLocalConnectionIdSchema,
+    /**
+     * Maps Sigma internal connection UUIDs (source.connectionId in data model specs)
+     * to ktx warehouse connection IDs. When present, projected semantic-layer sources
+     * are written under the mapped warehouse connection rather than the Sigma connection.
+     */
+    connectionMappings: z.record(z.string(), z.string()).optional(),
+    /** Filters applied when listing workbooks. Defaults exclude archived and exploration workbooks. */
+    workbookFilter: workbookFilterSchema.default({ includeArchived: false, includeExplorations: false }),
+    /** Filters applied when listing data models. */
+    dataModelFilter: dataModelFilterSchema.optional(),
+});
+export function parseSigmaPullConfig(raw) {
+    return sigmaPullConfigSchema.parse(raw);
+}
+/** Written to stagedDir during fetch() and read back by project(), listTargetConnectionIds(), and the sigma_ingest skill. */
+export const sigmaProjectionConfigSchema = z.object({
+    connectionMappings: z.record(z.string(), z.string()).default({}),
+    /** Filters that were active when workbooks were last fetched. Tells the skill what the staged set covers. */
+    workbookFilter: workbookFilterSchema.default({ includeArchived: false, includeExplorations: false }),
+});
+/**
+ * A staged data model file, one per `data-models/<id>.json`.
+ * Stores the summary metadata plus the raw spec blob from GET /v2/dataModels/{id}/spec.
+ */
+export const stagedDataModelFileSchema = z.object({
+    sigmaId: z.string(),
+    name: z.string(),
+    /** Full path in Sigma, e.g. "Finance/Revenue Model". */
+    path: z.string(),
+    latestVersion: z.number(),
+    updatedAt: z.string(),
+    isArchived: z.boolean().default(false),
+    /** URL-safe slug Sigma uses in the web UI (dataModelUrlId from the API). */
+    dataModelUrlId: z.string().optional(),
+    /** Raw spec from GET /v2/dataModels/{id}/spec (JSON format). */
+    spec: z.unknown(),
+});
+/** The manifest written once per `fetch()`. Presence acts as the detect() sentinel. */
+export const sigmaManifestSchema = z.object({
+    sigmaConnectionId: sigmaLocalConnectionIdSchema,
+    fetchedAt: z.string(),
+    dataModelCount: z.number().int(),
+    workbookCount: z.number().int().default(0),
+});
+/**
+ * A staged workbook file, one per `workbooks/<id>.json`.
+ * Stores the summary metadata from GET /v2/workbooks (no separate spec endpoint).
+ */
+export const stagedWorkbookFileSchema = z.object({
+    sigmaId: z.string(),
+    name: z.string(),
+    path: z.string(),
+    latestVersion: z.number(),
+    updatedAt: z.string(),
+    isArchived: z.boolean().default(false),
+    workbookUrlId: z.string().optional(),
+    description: z.string().optional(),
+});
+/** Filenames inside stagedDir. Centralized so chunk() + fetch() + detect() all agree. */
+export const STAGED_FILES = {
+    manifest: 'sigma-manifest.json',
+    projectionConfig: 'sigma-projection-config.json',
+    dataModelsDir: 'data-models',
+    workbooksDir: 'workbooks',
+};