@kaelio/ktx 0.14.0 → 0.15.0

package/dist/commands/setup-commands.js

@@ -43,6 +43,7 @@ function sourceType(value) {
         value === 'looker' ||
         value === 'lookml' ||
         value === 'notion' ||
+        value === 'sigma' ||
         value === 'gdrive') {
         return value;
     }

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

@@ -0,0 +1,6 @@
+import type { ChunkResult, DiffSet } from '../../types.js';
+interface ChunkOptions {
+    diffSet?: DiffSet;
+}
+export declare function chunkSigmaStagedDir(stagedDir: string, opts?: ChunkOptions): Promise<ChunkResult>;
+export {};

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

@@ -0,0 +1,119 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { sigmaManifestSchema, stagedDataModelFileSchema, stagedWorkbookFileSchema, STAGED_FILES, } from './types.js';
+async function walkStagedDir(stagedDir) {
+    let entries;
+    try {
+        entries = await readdir(stagedDir, { withFileTypes: true, recursive: true });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const paths = [];
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const abs = join(entry.parentPath, entry.name);
+        paths.push(relative(stagedDir, abs).replace(/\\/g, '/'));
+    }
+    paths.sort();
+    return paths;
+}
+async function loadBundle(stagedDir) {
+    const allPaths = await walkStagedDir(stagedDir);
+    let manifest = null;
+    try {
+        const body = await readFile(join(stagedDir, STAGED_FILES.manifest), 'utf-8');
+        manifest = sigmaManifestSchema.parse(JSON.parse(body));
+    }
+    catch {
+        manifest = null;
+    }
+    const dataModelsByPath = new Map();
+    const dmPrefix = `${STAGED_FILES.dataModelsDir}/`;
+    for (const path of allPaths) {
+        if (!path.startsWith(dmPrefix) || !path.endsWith('.json'))
+            continue;
+        try {
+            const body = await readFile(join(stagedDir, path), 'utf-8');
+            const parsed = stagedDataModelFileSchema.parse(JSON.parse(body));
+            dataModelsByPath.set(path, parsed);
+        }
+        catch {
+            // Malformed file — skip.
+        }
+    }
+    const workbooksByPath = new Map();
+    const wbPrefix = `${STAGED_FILES.workbooksDir}/`;
+    for (const path of allPaths) {
+        if (!path.startsWith(wbPrefix) || !path.endsWith('.json'))
+            continue;
+        try {
+            const body = await readFile(join(stagedDir, path), 'utf-8');
+            const parsed = stagedWorkbookFileSchema.parse(JSON.parse(body));
+            workbooksByPath.set(path, parsed);
+        }
+        catch {
+            // Malformed file — skip.
+        }
+    }
+    return { manifest, dataModelsByPath, workbooksByPath, allPaths };
+}
+/** Max data models per LLM work unit. Controls parallel processing granularity. */
+const DATA_MODELS_PER_UNIT = 50;
+/** Max workbooks per LLM work unit. Controls incremental re-sync granularity. */
+const WORKBOOKS_PER_UNIT = 2000;
+function emitBatches(paths, perUnit, unitKeyBase, labelBase, noun, allPaths) {
+    const batches = Math.ceil(paths.length / perUnit) || 0;
+    const units = [];
+    for (let i = 0; i < batches; i++) {
+        const batch = paths.slice(i * perUnit, (i + 1) * perUnit);
+        const rawFiles = [...batch].sort();
+        const rawFilesSet = new Set(rawFiles);
+        const suffix = batches > 1 ? `-${i}` : '';
+        units.push({
+            unitKey: `${unitKeyBase}${suffix}`,
+            displayLabel: batches > 1 ? `${labelBase} (${i + 1}/${batches})` : labelBase,
+            rawFiles,
+            peerFileIndex: allPaths.filter((p) => !rawFilesSet.has(p)).sort(),
+            dependencyPaths: [],
+            notes: `${batch.length} ${noun}${batch.length === 1 ? '' : 's'}`,
+        });
+    }
+    return units;
+}
+function emitWorkUnits(bundle) {
+    if (!bundle.manifest)
+        return [];
+    const dmPaths = [...bundle.dataModelsByPath.keys()].sort();
+    const wbPaths = [...bundle.workbooksByPath.keys()].sort();
+    return [
+        ...emitBatches(dmPaths, DATA_MODELS_PER_UNIT, 'sigma-data-models', 'Sigma: data models', 'data model', bundle.allPaths),
+        ...emitBatches(wbPaths, WORKBOOKS_PER_UNIT, 'sigma-workbooks', 'Sigma: workbooks', 'workbook', bundle.allPaths),
+    ];
+}
+export async function chunkSigmaStagedDir(stagedDir, opts = {}) {
+    const bundle = await loadBundle(stagedDir);
+    if (!bundle.manifest) {
+        return { workUnits: [] };
+    }
+    const firstRunUnits = emitWorkUnits(bundle);
+    if (!opts.diffSet) {
+        return { workUnits: firstRunUnits };
+    }
+    const touched = new Set([...opts.diffSet.added, ...opts.diffSet.modified]);
+    const kept = [];
+    for (const wu of firstRunUnits) {
+        const anyTouched = wu.rawFiles.some((p) => touched.has(p));
+        if (!anyTouched)
+            continue;
+        const changedFiles = wu.rawFiles.filter((p) => touched.has(p));
+        const unchangedFiles = wu.rawFiles.filter((p) => !touched.has(p));
+        const deps = new Set([...wu.dependencyPaths, ...unchangedFiles]);
+        kept.push({ ...wu, rawFiles: changedFiles.sort(), dependencyPaths: [...deps].sort() });
+    }
+    const eviction = opts.diffSet.deleted.length > 0 ? { deletedRawPaths: [...opts.diffSet.deleted].sort() } : undefined;
+    return { workUnits: kept, eviction };
+}

package/dist/context/ingest/adapters/sigma/client-port.d.ts

@@ -0,0 +1,45 @@
+import type { FetchContext } from '../../types.js';
+import type { SigmaPullConfig, WorkbookFilterInput } from './types.js';
+export interface SigmaTestConnectionResult {
+    success: boolean;
+    message?: string;
+    error?: string;
+}
+/** Data model summary shape from GET /v2/dataModels list response. */
+export interface SigmaDataModelSummary {
+    dataModelId: string;
+    dataModelUrlId: string;
+    name: string;
+    path: string;
+    latestVersion: number;
+    ownerId: string;
+    createdAt: string;
+    updatedAt: string;
+    isArchived?: boolean;
+}
+/** Workbook summary shape from GET /v2/workbooks list response. */
+export interface SigmaWorkbookSummary {
+    workbookId: string;
+    workbookUrlId: string;
+    name: string;
+    path: string;
+    latestVersion: number;
+    ownerId: string;
+    createdAt: string;
+    updatedAt: string;
+    isArchived?: boolean;
+    description?: string;
+}
+/** Re-exported so callers can reference the type without importing from types.ts directly. */
+export type { WorkbookFilterInput as ListWorkbooksOptions } from './types.js';
+export interface SigmaRuntimeClient {
+    testConnection(): Promise<SigmaTestConnectionResult>;
+    listDataModels(): Promise<SigmaDataModelSummary[]>;
+    listWorkbooks(opts?: WorkbookFilterInput): Promise<SigmaWorkbookSummary[]>;
+    /** Returns the raw spec object from GET /v2/dataModels/{id}/spec. */
+    getDataModelSpec(dataModelId: string): Promise<unknown>;
+    cleanup(): Promise<void>;
+}
+export interface SigmaClientFactory {
+    createClient(config: SigmaPullConfig, ctx: FetchContext): Promise<SigmaRuntimeClient> | SigmaRuntimeClient;
+}

package/dist/context/ingest/adapters/sigma/client-port.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,33 @@
+import type { ListWorkbooksOptions, SigmaDataModelSummary, SigmaRuntimeClient, SigmaTestConnectionResult, SigmaWorkbookSummary } from './client-port.js';
+export interface SigmaClientRuntimeConfig {
+    apiUrl: string;
+    clientId: string;
+    clientSecret: string;
+}
+export interface SigmaClientConfig {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    timeoutMs: number;
+}
+export declare const DEFAULT_SIGMA_CLIENT_CONFIG: SigmaClientConfig;
+export declare class DefaultSigmaClient implements SigmaRuntimeClient {
+    private readonly runtimeConfig;
+    private readonly clientConfig;
+    private accessToken;
+    private refreshToken;
+    private tokenExpiresAt;
+    private tokenInflight;
+    constructor(runtimeConfig: SigmaClientRuntimeConfig, clientConfig?: SigmaClientConfig);
+    private get apiUrl();
+    private basicAuthHeader;
+    private fetchToken;
+    private ensureToken;
+    private request;
+    private paginateAll;
+    testConnection(): Promise<SigmaTestConnectionResult>;
+    listDataModels(): Promise<SigmaDataModelSummary[]>;
+    listWorkbooks(opts?: ListWorkbooksOptions): Promise<SigmaWorkbookSummary[]>;
+    getDataModelSpec(dataModelId: string): Promise<unknown>;
+    cleanup(): Promise<void>;
+}

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

@@ -0,0 +1,176 @@
+export const DEFAULT_SIGMA_CLIENT_CONFIG = {
+    maxRetries: 3,
+    baseDelayMs: 500,
+    maxDelayMs: 10_000,
+    timeoutMs: 30_000,
+};
+function isNonRetryable500(text) {
+    try {
+        const body = JSON.parse(text);
+        // service_error indicates a deterministic Sigma rejection (e.g. unsupported data
+        // source subtype). Retrying will not help, so throw immediately.
+        return body['code'] === 'service_error';
+    }
+    catch {
+        return false;
+    }
+}
+export class DefaultSigmaClient {
+    runtimeConfig;
+    clientConfig;
+    accessToken = null;
+    refreshToken = null;
+    tokenExpiresAt = 0;
+    tokenInflight = null;
+    constructor(runtimeConfig, clientConfig = DEFAULT_SIGMA_CLIENT_CONFIG) {
+        this.runtimeConfig = runtimeConfig;
+        this.clientConfig = clientConfig;
+    }
+    get apiUrl() {
+        return this.runtimeConfig.apiUrl.replace(/\/$/, '');
+    }
+    basicAuthHeader() {
+        const credentials = Buffer.from(`${this.runtimeConfig.clientId}:${this.runtimeConfig.clientSecret}`).toString('base64');
+        return `Basic ${credentials}`;
+    }
+    async fetchToken(body) {
+        const res = await fetch(`${this.apiUrl}/v2/auth/token`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                Authorization: this.basicAuthHeader(),
+            },
+            body: body.toString(),
+            signal: AbortSignal.timeout(this.clientConfig.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`Sigma auth failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    async ensureToken() {
+        const now = Date.now();
+        // Refresh 60 s before expiry so in-flight requests don't get 401.
+        if (this.accessToken && now < this.tokenExpiresAt - 60_000) {
+            return;
+        }
+        if (this.tokenInflight)
+            return this.tokenInflight;
+        const body = new URLSearchParams();
+        if (this.refreshToken) {
+            body.set('grant_type', 'refresh_token');
+            body.set('refresh_token', this.refreshToken);
+        }
+        else {
+            body.set('grant_type', 'client_credentials');
+        }
+        this.tokenInflight = this.fetchToken(body)
+            .then((data) => {
+            this.accessToken = data.access_token;
+            this.refreshToken = data.refresh_token ?? null;
+            this.tokenExpiresAt = Date.now() + data.expires_in * 1000;
+        })
+            .finally(() => {
+            this.tokenInflight = null;
+        });
+        return this.tokenInflight;
+    }
+    async request(path, query) {
+        await this.ensureToken();
+        const url = new URL(`${this.apiUrl}${path}`);
+        if (query) {
+            for (const [k, v] of Object.entries(query)) {
+                url.searchParams.set(k, v);
+            }
+        }
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.clientConfig.maxRetries; attempt++) {
+            if (attempt > 0) {
+                const delay = Math.min(this.clientConfig.baseDelayMs * 2 ** (attempt - 1), this.clientConfig.maxDelayMs);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+            const res = await fetch(url.toString(), {
+                headers: { Authorization: `Bearer ${this.accessToken}` },
+                signal: AbortSignal.timeout(this.clientConfig.timeoutMs),
+            });
+            if (res.status === 401) {
+                // Token rejected — force full re-auth and retry once.
+                this.accessToken = null;
+                this.refreshToken = null;
+                this.tokenExpiresAt = 0;
+                await this.ensureToken();
+                const retried = await fetch(url.toString(), {
+                    headers: { Authorization: `Bearer ${this.accessToken}` },
+                    signal: AbortSignal.timeout(this.clientConfig.timeoutMs),
+                });
+                if (!retried.ok) {
+                    const text = await retried.text().catch(() => '');
+                    throw new Error(`Sigma API error after token refresh (${retried.status}): ${text}`);
+                }
+                return retried.json();
+            }
+            if (res.status === 429 || res.status >= 500) {
+                const text = await res.text().catch(() => '');
+                lastError = new Error(`Sigma API error (${res.status}): ${text}`);
+                if (isNonRetryable500(text))
+                    throw lastError;
+                continue;
+            }
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                throw new Error(`Sigma API error (${res.status}): ${text}`);
+            }
+            return res.json();
+        }
+        throw lastError ?? new Error('Sigma API request failed after retries');
+    }
+    async paginateAll(path, query = {}) {
+        const all = [];
+        let page = null;
+        do {
+            const q = { ...query, limit: '1000' };
+            if (page) {
+                q['page'] = page;
+            }
+            const res = await this.request(path, q);
+            all.push(...res.entries);
+            page = res.nextPage ?? null;
+        } while (page !== null);
+        return all;
+    }
+    async testConnection() {
+        try {
+            await this.ensureToken();
+            return { success: true };
+        }
+        catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    async listDataModels() {
+        return this.paginateAll('/v2/dataModels');
+    }
+    async listWorkbooks(opts = {}) {
+        const query = {};
+        if (!opts.includeExplorations)
+            query['excludeExplorations'] = 'true';
+        let results = await this.paginateAll('/v2/workbooks', query);
+        if (!opts.includeArchived) {
+            results = results.filter((wb) => !wb.isArchived);
+        }
+        if (opts.updatedSince) {
+            const since = new Date(opts.updatedSince).getTime();
+            results = results.filter((wb) => new Date(wb.updatedAt).getTime() >= since);
+        }
+        return results;
+    }
+    async getDataModelSpec(dataModelId) {
+        return this.request(`/v2/dataModels/${encodeURIComponent(dataModelId)}/spec`);
+    }
+    async cleanup() {
+        this.accessToken = null;
+        this.refreshToken = null;
+        this.tokenExpiresAt = 0;
+    }
+}

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

@@ -0,0 +1 @@
+export declare function detectSigmaStagedDir(stagedDir: string): Promise<boolean>;

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

@@ -0,0 +1,23 @@
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { STAGED_FILES } from './types.js';
+export async function detectSigmaStagedDir(stagedDir) {
+    try {
+        await stat(join(stagedDir, STAGED_FILES.manifest));
+    }
+    catch {
+        return false;
+    }
+    for (const subdir of [STAGED_FILES.dataModelsDir, STAGED_FILES.workbooksDir]) {
+        let entries;
+        try {
+            entries = await readdir(join(stagedDir, subdir));
+        }
+        catch {
+            continue;
+        }
+        if (entries.some((name) => name.endsWith('.json')))
+            return true;
+    }
+    return false;
+}

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

@@ -0,0 +1,14 @@
+import type { FetchContext } from '../../types.js';
+import type { SigmaClientFactory } from './client-port.js';
+export interface SigmaFetchLogger {
+    log(message: string): void;
+    warn(message: string): void;
+}
+export interface FetchSigmaBundleParams {
+    pullConfig: unknown;
+    stagedDir: string;
+    ctx: FetchContext;
+    clientFactory: SigmaClientFactory;
+    logger?: SigmaFetchLogger;
+}
+export declare function fetchSigmaBundle({ pullConfig, stagedDir, ctx, clientFactory, logger, }: FetchSigmaBundleParams): Promise<void>;

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 {};