@kb-labs/core-config 1.2.0 → 1.4.0

package/dist/index.d.ts

@@ -1,25 +1,1016 @@
-export * from './types/index';
-export * from './runtime';
-export * from './utils';
-export * from './utils/paths';
-export * from './errors/kb-error';
-export * from './cache/fs-cache';
-export * from './hash/config-hash';
-export * from './api/read-config';
-export * from './api/read-kb-config';
-export * from './merge/layered-merge';
-export * from './api/product-config';
-export * from './preset/resolve-preset';
-export * from './lockfile/lockfile';
-export * from './types/preset';
-export * from './profiles/types';
-export * from './profiles/loader';
-export * from './profiles/scope-selector';
-export * from './profiles/resolver';
-export * from './types/init';
-export * from './api/init-workspace';
-export * from './api/upsert-lockfile';
-export * from './utils/fs-atomic';
-export { clearCaches } from './cache/fs-cache';
-export { validateProductConfig } from './validation/validate-config';
-//# sourceMappingURL=index.d.ts.map
+import { z } from 'zod';
+
+type Diagnostic = {
+    level: "warn" | "error";
+    code: string;
+    message: string;
+    detail?: unknown;
+} | {
+    level: "info";
+    code: string;
+    message: string;
+};
+type JsonReadResult<T = unknown> = {
+    ok: true;
+    data: T;
+    diagnostics: Diagnostic[];
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+interface FindNearestConfigOpts {
+    startDir?: string;
+    stopDir?: string;
+    filenames: string[];
+}
+interface ProfilesConfig {
+    rootDir?: string;
+    defaultName?: string;
+    strict?: boolean;
+}
+interface KBConfig {
+    profiles?: ProfilesConfig;
+}
+interface MergeTrace {
+    path: string;
+    source: string;
+    type: 'set' | 'overwriteArray';
+    layer: string;
+    profileRef?: string;
+    presetRef?: string;
+    version?: string;
+}
+interface ProfileLayerInput {
+    profileId: string;
+    source: string;
+    products?: Record<string, unknown>;
+    scope?: {
+        id: string;
+        source: string;
+        products?: Record<string, unknown>;
+    };
+}
+interface ResolveOptions {
+    cwd: string;
+    /**
+     * Product identifier (e.g., 'mind', 'aiReview', 'workflow')
+     */
+    product: string;
+    cli?: Record<string, unknown>;
+    writeFinal?: boolean;
+    profileLayer?: ProfileLayerInput;
+}
+interface ConfigLayer {
+    label: string;
+    value: any;
+    source: string;
+}
+interface ProductConfigResult<T = Record<string, any>> {
+    config: T;
+    trace: MergeTrace[];
+}
+
+/**
+ * @module @kb-labs/core/config/runtime
+ * Infrastructure-only config pipeline (no domain keys).
+ * Provides: nearest config discovery, safe JSON read with diagnostics,
+ * deep merge that ignores `undefined`, and a generic resolver (defaults→file→env→cli).
+ */
+
+/** Find nearest config file walking up from startDir until stopDir or FS root. */
+declare function findNearestConfig(opts: FindNearestConfigOpts): Promise<{
+    path: string | null;
+    tried: string[];
+}>;
+/** Read JSON with explicit diagnostics (no silent nulls). */
+declare function readJsonWithDiagnostics<T = unknown>(p: string): Promise<JsonReadResult<T>>;
+/** Shallow pick of defined fields only. */
+declare function pickDefined<T extends Record<string, any>>(obj: T | undefined): Partial<T>;
+/** Deep merge (objects/arrays), ignoring `undefined` on the overlay. */
+declare function mergeDefined<T>(base: T, over?: Partial<T>): T;
+declare const SYSTEM_DEFAULTS: {
+    readonly profiles: {
+        readonly rootDir: ".kb/profiles";
+        readonly defaultName: "default";
+        readonly strict: true;
+    };
+};
+interface ResolveConfigArgs<TConfig, _TEnvMap = unknown> {
+    defaults: TConfig;
+    fileConfig?: Partial<TConfig>;
+    envMapper?: (env: NodeJS.ProcessEnv) => Partial<TConfig> | undefined;
+    cliOverrides?: Partial<TConfig>;
+    validate?: (cfg: TConfig) => {
+        ok: boolean;
+        diagnostics?: Diagnostic[];
+    };
+}
+/**
+ * Generic resolver: defaults → fileConfig → envMapper(process.env) → cliOverrides.
+ * No domain keys inside; mapping/validation provided by the product/shared layer.
+ */
+declare function resolveConfig<TConfig>(args: ResolveConfigArgs<TConfig>): {
+    value: TConfig;
+    diagnostics: Diagnostic[];
+};
+
+/**
+ * @module @kb-labs/core/utils/env
+ * Small helpers to convert ENV strings to typed values.
+ */
+declare function toBool(v: string | undefined): boolean | undefined;
+declare function toInt(v: string | undefined): number | undefined;
+
+/**
+ * @module @kb-labs/core/config/utils/product-normalize
+ * Product ID normalization between code (camelCase) and filesystem (kebab-case)
+ */
+/**
+ * Convert product ID to filesystem kebab-case format
+ * @param id Product ID (e.g., 'aiReview', 'mind', 'workflow')
+ * @returns kebab-case string for filesystem paths
+ */
+declare function toFsProduct(id: string): string;
+/**
+ * Convert filesystem kebab-case key to product ID
+ * @param fsKey kebab-case string from filesystem
+ * @returns Product ID (camelCase if mapped, original otherwise)
+ */
+declare function toConfigProduct(fsKey: string): string;
+/**
+ * Check if a string is a known product ID
+ */
+declare function isValidProductId(value: string): boolean;
+/**
+ * Get all known product IDs
+ */
+declare function getAllProductIds(): string[];
+
+/**
+ * Get profiles root directory
+ */
+declare function getProfilesRootDir(cwd: string): string;
+/**
+ * Get product configuration directory
+ */
+declare function getProductConfigDir(cwd: string, fsProduct: string): string;
+/**
+ * Get product configuration file path
+ */
+declare function getProductConfigPath(cwd: string, fsProduct: string): string;
+/**
+ * Get .kb root directory
+ */
+declare function getKbRootDir(cwd: string): string;
+/**
+ * Get lockfile path
+ */
+declare function getLockfilePath(cwd: string): string;
+
+/**
+ * @module @kb-labs/core/config/errors
+ * Standardized error class for KB Labs with exit code mapping
+ */
+declare class KbError extends Error {
+    code: string;
+    hint?: string | undefined;
+    meta?: any | undefined;
+    constructor(code: string, message: string, hint?: string | undefined, meta?: any | undefined);
+}
+/**
+ * Maps KbError codes to CLI exit codes
+ */
+declare function getExitCode(err: KbError): number;
+/**
+ * Error codes with their standard hints
+ */
+declare const ERROR_HINTS: {
+    readonly ERR_CONFIG_NOT_FOUND: "Create .kb/kb-labs.config.yaml or run: kb init";
+    readonly ERR_CONFIG_INVALID: "Check configuration syntax and required fields";
+    readonly ERR_CONFIG_EXISTS_CONFLICT: "Use --force to overwrite existing configuration";
+    readonly ERR_PATH_OUTSIDE_WORKSPACE: "Check cwd or use a relative path within the workspace";
+    readonly ERR_PRESET_NOT_RESOLVED: "Install the required preset package or check network connectivity";
+    readonly ERR_PROFILE_INCOMPATIBLE: "Profile version is incompatible with current system";
+    readonly ERR_PROFILE_NOT_DEFINED: "Add profiles[] to kb.config.json or pass --profile=<id>";
+    readonly ERR_PROFILE_RESOLVE_FAILED: "Profile registry unavailable. Define profiles[] inside kb.config.json or use workspace presets.";
+    readonly ERR_PROFILE_EXTENDS_FAILED: "Profile extends failed. Check extends reference or install required preset/package.";
+    readonly ERR_PROFILE_SCOPE_NOT_FOUND: "Scope not found. Use --scope=<id> with one of the configured scopes.";
+    readonly ERR_PROFILE_SCOPE_CONFLICT: "Multiple scopes matched. Specify --scope=<id> explicitly.";
+    readonly ERR_PROFILE_INVALID_FORMAT: "Update profiles[] in kb.config.json (Profiles v2) or rerun your plugin setup command.";
+    readonly ERR_ARTIFACT_LIMIT_EXCEEDED: "Remove or split large artifacts, or reduce artifact count";
+    readonly ERR_FORBIDDEN: "Add role in policy.overrides or use preset...";
+};
+type ErrorCode = keyof typeof ERROR_HINTS;
+
+/**
+ * @module @kb-labs/core/config/cache/fs-cache
+ * LRU cache for filesystem reads with clearCaches() support
+ */
+declare class FSCache {
+    private cache;
+    private keyCache;
+    /**
+     * Generate cache key from file path, mtime, and size
+     */
+    private getCacheKey;
+    /**
+     * Get cached file data if available and not stale
+     */
+    get(absPath: string): Promise<any | null>;
+    /**
+     * Cache file data
+     */
+    set(absPath: string, data: any): Promise<void>;
+    /**
+     * Clear all caches
+     */
+    clearCaches(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        keySize: number;
+    };
+}
+declare const fsCache: FSCache;
+
+/**
+ * Clear all filesystem caches
+ */
+declare function clearCaches(): void;
+
+/**
+ * @module @kb-labs/core/config/hash/config-hash
+ * SHA256 hash computation for configuration objects (lockfile generation)
+ */
+/**
+ * Compute SHA256 hash of a configuration object
+ * @param obj Configuration object to hash
+ * @returns SHA256 hash as hex string
+ */
+declare function computeConfigHash(obj: any): string;
+/**
+ * Compute hash for multiple config objects
+ * @param configs Array of config objects
+ * @returns Combined SHA256 hash
+ */
+declare function computeConfigsHash(configs: any[]): string;
+
+/**
+ * @module @kb-labs/core/config/api/read-config
+ * Enhanced config file reading with YAML support and find-up
+ */
+interface ConfigFileResult {
+    data: unknown;
+    format: 'json' | 'yaml';
+    path: string;
+}
+/**
+ * Read config file with format detection and caching
+ */
+declare function readConfigFile(filePath: string): Promise<ConfigFileResult>;
+/**
+ * Find git root directory
+ */
+declare function findGitRoot(startDir: string): Promise<string | null>;
+/**
+ * Read workspace config with find-up to git root
+ */
+declare function readWorkspaceConfig(cwd: string): Promise<ConfigFileResult | null>;
+
+/**
+ * @module @kb-labs/core-config/api/read-kb-config
+ * Find + read kb.config.* files (product-level workspace config).
+ */
+
+type KbConfigResult = ConfigFileResult;
+declare function findKbConfig(cwd: string, filenames?: string[]): Promise<{
+    path: string | null;
+    tried: string[];
+}>;
+declare function readKbConfig(cwd: string): Promise<KbConfigResult | null>;
+
+/**
+ * @module @kb-labs/core/config/merge/layered-merge
+ * Layered merge with trace for configuration layers
+ */
+
+interface LayeredMergeResult {
+    merged: any;
+    trace: MergeTrace[];
+}
+/**
+ * Merge configuration layers with detailed trace
+ * Arrays are overwritten (not merged)
+ * Objects are deeply merged
+ */
+declare function layeredMergeWithTrace(layers: ConfigLayer[]): LayeredMergeResult;
+
+/**
+ * @module @kb-labs/core/config/api/product-config
+ * High-level product configuration resolver with layered merge
+ */
+
+/**
+ * Get product configuration with layered merge and trace
+ */
+declare function getProductConfig<T = Record<string, any>>(opts: ResolveOptions, schema: any): Promise<ProductConfigResult<T>>;
+/**
+ * Explain product configuration (trace only)
+ */
+declare function explainProductConfig(opts: Omit<ResolveOptions, 'writeFinal'>, schema: any): Promise<{
+    trace: any[];
+}>;
+/**
+ * Get configuration hash for lockfile
+ */
+declare function getConfigHash(config: any): string;
+
+/**
+ * @module @kb-labs/core/config/preset/resolve-preset
+ * Org preset resolution with offline-first npm package loading
+ */
+interface PresetInfo {
+    name: string;
+    version: string;
+    path: string;
+    config: any;
+}
+/**
+ * Resolve org preset package (offline-first)
+ */
+declare function resolvePreset(presetRef: string, cwd: string): Promise<PresetInfo>;
+/**
+ * Get preset config for a specific product
+ */
+declare function getPresetConfigForProduct(preset: PresetInfo, product: string): any;
+/**
+ * Get preset metadata
+ */
+declare function getPresetMetadata(preset: PresetInfo): {
+    name: string;
+    version: string;
+    path: string;
+    products: string[];
+};
+
+/**
+ * @module @kb-labs/core/config/lockfile/lockfile
+ * Lockfile generation and management
+ */
+interface LockfileData {
+    $schema?: string;
+    schemaVersion: '1.0';
+    orgPreset?: string;
+    profile?: string;
+    policyBundle?: string;
+    hashes: Record<string, string>;
+    generatedAt: string;
+}
+/**
+ * Read lockfile from workspace
+ */
+declare function readLockfile(cwd: string): Promise<LockfileData | null>;
+/**
+ * Write lockfile to workspace
+ */
+declare function writeLockfile(cwd: string, lockfileData: LockfileData): Promise<void>;
+/**
+ * Update lockfile with new hashes
+ */
+declare function updateLockfile(cwd: string, updates: {
+    orgPreset?: string;
+    profile?: string;
+    policyBundle?: string;
+    configHashes?: Record<string, any>;
+}): Promise<LockfileData>;
+/**
+ * Get config hash for a product
+ */
+declare function getLockfileConfigHash(product: string, config: any): string;
+/**
+ * Check if lockfile is up to date
+ */
+declare function isLockfileUpToDate(cwd: string, configs: Record<string, any>): Promise<boolean>;
+/**
+ * Validate lockfile schema
+ */
+declare function validateLockfile(lockfileData: any): lockfileData is LockfileData;
+/**
+ * Get lockfile statistics
+ */
+declare function getLockfileStats(lockfileData: LockfileData): {
+    productCount: number;
+    hasOrgPreset: boolean;
+    hasProfile: boolean;
+    hasPolicyBundle: boolean;
+    generatedAt: Date;
+};
+
+/**
+ * @module @kb-labs/core/config/types/preset
+ * Preset-related types
+ */
+interface PresetConfig {
+    products: Record<string, any>;
+    metadata?: {
+        name: string;
+        version: string;
+        description?: string;
+    };
+}
+interface PresetResolutionOptions {
+    cwd: string;
+    presetRef: string;
+    offline?: boolean;
+}
+interface PresetResolutionResult {
+    preset: {
+        name: string;
+        version: string;
+        path: string;
+        config: PresetConfig;
+    };
+    resolvedAt: string;
+}
+
+/**
+ * @module @kb-labs/core-config/profiles/types
+ * Shared ProfileV2 + BundleProfile types and Zod schemas.
+ */
+
+declare const ScopeV2Schema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    include: z.ZodArray<z.ZodString, "many">;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    products: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    default: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    include: string[];
+    default?: boolean | undefined;
+    products?: Record<string, Record<string, unknown>> | undefined;
+    label?: string | undefined;
+    description?: string | undefined;
+    exclude?: string[] | undefined;
+}, {
+    id: string;
+    include: string[];
+    default?: boolean | undefined;
+    products?: Record<string, Record<string, unknown>> | undefined;
+    label?: string | undefined;
+    description?: string | undefined;
+    exclude?: string[] | undefined;
+}>;
+type ScopeV2 = z.infer<typeof ScopeV2Schema>;
+declare const ProfileMetaSchema: z.ZodObject<{
+    version: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    deprecated: z.ZodOptional<z.ZodBoolean>;
+    owner: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    version?: string | undefined;
+    tags?: string[] | undefined;
+    deprecated?: boolean | undefined;
+    owner?: string | undefined;
+}, {
+    version?: string | undefined;
+    tags?: string[] | undefined;
+    deprecated?: boolean | undefined;
+    owner?: string | undefined;
+}>;
+type ProfileMeta = z.infer<typeof ProfileMetaSchema>;
+declare const ProfileV2Schema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    extends: z.ZodOptional<z.ZodString>;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        include: z.ZodArray<z.ZodString, "many">;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        products: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        default: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        include: string[];
+        default?: boolean | undefined;
+        products?: Record<string, Record<string, unknown>> | undefined;
+        label?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+    }, {
+        id: string;
+        include: string[];
+        default?: boolean | undefined;
+        products?: Record<string, Record<string, unknown>> | undefined;
+        label?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+    }>, "many">>;
+    products: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    meta: z.ZodOptional<z.ZodObject<{
+        version: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        deprecated: z.ZodOptional<z.ZodBoolean>;
+        owner: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        version?: string | undefined;
+        tags?: string[] | undefined;
+        deprecated?: boolean | undefined;
+        owner?: string | undefined;
+    }, {
+        version?: string | undefined;
+        tags?: string[] | undefined;
+        deprecated?: boolean | undefined;
+        owner?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    products?: Record<string, Record<string, unknown>> | undefined;
+    label?: string | undefined;
+    description?: string | undefined;
+    extends?: string | undefined;
+    scopes?: {
+        id: string;
+        include: string[];
+        default?: boolean | undefined;
+        products?: Record<string, Record<string, unknown>> | undefined;
+        label?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+    }[] | undefined;
+    meta?: {
+        version?: string | undefined;
+        tags?: string[] | undefined;
+        deprecated?: boolean | undefined;
+        owner?: string | undefined;
+    } | undefined;
+}, {
+    id: string;
+    products?: Record<string, Record<string, unknown>> | undefined;
+    label?: string | undefined;
+    description?: string | undefined;
+    extends?: string | undefined;
+    scopes?: {
+        id: string;
+        include: string[];
+        default?: boolean | undefined;
+        products?: Record<string, Record<string, unknown>> | undefined;
+        label?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+    }[] | undefined;
+    meta?: {
+        version?: string | undefined;
+        tags?: string[] | undefined;
+        deprecated?: boolean | undefined;
+        owner?: string | undefined;
+    } | undefined;
+}>;
+type ProfileV2 = z.infer<typeof ProfileV2Schema>;
+declare const ProfilesV2Schema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    extends: z.ZodOptional<z.ZodString>;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        include: z.ZodArray<z.ZodString, "many">;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        products: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        default: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        include: string[];
+        default?: boolean | undefined;
+        products?: Record<string, Record<string, unknown>> | undefined;
+        label?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+    }, {
+        id: string;
+        include: string[];
+        default?: boolean | undefined;
+        products?: Record<string, Record<string, unknown>> | undefined;
+        label?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+    }>, "many">>;
+    products: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    meta: z.ZodOptional<z.ZodObject<{
+        version: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        deprecated: z.ZodOptional<z.ZodBoolean>;
+        owner: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        version?: string | undefined;
+        tags?: string[] | undefined;
+        deprecated?: boolean | undefined;
+        owner?: string | undefined;
+    }, {
+        version?: string | undefined;
+        tags?: string[] | undefined;
+        deprecated?: boolean | undefined;
+        owner?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    products?: Record<string, Record<string, unknown>> | undefined;
+    label?: string | undefined;
+    description?: string | undefined;
+    extends?: string | undefined;
+    scopes?: {
+        id: string;
+        include: string[];
+        default?: boolean | undefined;
+        products?: Record<string, Record<string, unknown>> | undefined;
+        label?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+    }[] | undefined;
+    meta?: {
+        version?: string | undefined;
+        tags?: string[] | undefined;
+        deprecated?: boolean | undefined;
+        owner?: string | undefined;
+    } | undefined;
+}, {
+    id: string;
+    products?: Record<string, Record<string, unknown>> | undefined;
+    label?: string | undefined;
+    description?: string | undefined;
+    extends?: string | undefined;
+    scopes?: {
+        id: string;
+        include: string[];
+        default?: boolean | undefined;
+        products?: Record<string, Record<string, unknown>> | undefined;
+        label?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+    }[] | undefined;
+    meta?: {
+        version?: string | undefined;
+        tags?: string[] | undefined;
+        deprecated?: boolean | undefined;
+        owner?: string | undefined;
+    } | undefined;
+}>, "many">;
+declare const ResolvedScopeSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    include: z.ZodArray<z.ZodString, "many">;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    isDefault: z.ZodBoolean;
+    products: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    include: string[];
+    isDefault: boolean;
+    products?: Record<string, Record<string, unknown>> | undefined;
+    label?: string | undefined;
+    description?: string | undefined;
+    exclude?: string[] | undefined;
+}, {
+    id: string;
+    include: string[];
+    isDefault: boolean;
+    products?: Record<string, Record<string, unknown>> | undefined;
+    label?: string | undefined;
+    description?: string | undefined;
+    exclude?: string[] | undefined;
+}>;
+type ResolvedScope = z.infer<typeof ResolvedScopeSchema>;
+declare const BundleProfileSourceSchema: z.ZodEnum<["workspace", "preset", "npm", "implicit"]>;
+type BundleProfileSource = z.infer<typeof BundleProfileSourceSchema>;
+declare const ProfileTraceSchema: z.ZodObject<{
+    extends: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    overrides: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    extends?: string[] | undefined;
+    overrides?: string[] | undefined;
+}, {
+    extends?: string[] | undefined;
+    overrides?: string[] | undefined;
+}>;
+type ProfileTrace = z.infer<typeof ProfileTraceSchema>;
+declare const ScopeSelectionSchema: z.ZodObject<{
+    strategy: z.ZodEnum<["explicit", "default", "auto", "none"]>;
+    path: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    strategy: "default" | "auto" | "explicit" | "none";
+    path?: string | undefined;
+}, {
+    strategy: "default" | "auto" | "explicit" | "none";
+    path?: string | undefined;
+}>;
+type ScopeSelection = z.infer<typeof ScopeSelectionSchema>;
+declare const BundleProfileSchema: z.ZodObject<{
+    id: z.ZodString;
+    key: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    source: z.ZodEnum<["workspace", "preset", "npm", "implicit"]>;
+    scopes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        include: z.ZodArray<z.ZodString, "many">;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        isDefault: z.ZodBoolean;
+        products: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        include: string[];
+        isDefault: boolean;
+        products?: Record<string, Record<string, unknown>> | undefined;
+        label?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+    }, {
+        id: string;
+        include: string[];
+        isDefault: boolean;
+        products?: Record<string, Record<string, unknown>> | undefined;
+        label?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+    }>, "many">;
+    products: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    trace: z.ZodOptional<z.ZodObject<{
+        extends: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        overrides: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        extends?: string[] | undefined;
+        overrides?: string[] | undefined;
+    }, {
+        extends?: string[] | undefined;
+        overrides?: string[] | undefined;
+    }>>;
+    meta: z.ZodOptional<z.ZodObject<{
+        version: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        deprecated: z.ZodOptional<z.ZodBoolean>;
+        owner: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        version?: string | undefined;
+        tags?: string[] | undefined;
+        deprecated?: boolean | undefined;
+        owner?: string | undefined;
+    }, {
+        version?: string | undefined;
+        tags?: string[] | undefined;
+        deprecated?: boolean | undefined;
+        owner?: string | undefined;
+    }>>;
+    productsByScope: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
+    activeScopeId: z.ZodOptional<z.ZodString>;
+    activeScope: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        include: z.ZodArray<z.ZodString, "many">;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        isDefault: z.ZodBoolean;
+        products: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        include: string[];
+        isDefault: boolean;
+        products?: Record<string, Record<string, unknown>> | undefined;
+        label?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+    }, {
+        id: string;
+        include: string[];
+        isDefault: boolean;
+        products?: Record<string, Record<string, unknown>> | undefined;
+        label?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+    }>>;
+    scopeSelection: z.ZodOptional<z.ZodObject<{
+        strategy: z.ZodEnum<["explicit", "default", "auto", "none"]>;
+        path: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        strategy: "default" | "auto" | "explicit" | "none";
+        path?: string | undefined;
+    }, {
+        strategy: "default" | "auto" | "explicit" | "none";
+        path?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    scopes: {
+        id: string;
+        include: string[];
+        isDefault: boolean;
+        products?: Record<string, Record<string, unknown>> | undefined;
+        label?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+    }[];
+    source: "preset" | "workspace" | "npm" | "implicit";
+    key?: string | undefined;
+    name?: string | undefined;
+    version?: string | undefined;
+    products?: Record<string, Record<string, unknown>> | undefined;
+    trace?: {
+        extends?: string[] | undefined;
+        overrides?: string[] | undefined;
+    } | undefined;
+    label?: string | undefined;
+    meta?: {
+        version?: string | undefined;
+        tags?: string[] | undefined;
+        deprecated?: boolean | undefined;
+        owner?: string | undefined;
+    } | undefined;
+    productsByScope?: Record<string, Record<string, Record<string, unknown>>> | undefined;
+    activeScopeId?: string | undefined;
+    activeScope?: {
+        id: string;
+        include: string[];
+        isDefault: boolean;
+        products?: Record<string, Record<string, unknown>> | undefined;
+        label?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+    } | undefined;
+    scopeSelection?: {
+        strategy: "default" | "auto" | "explicit" | "none";
+        path?: string | undefined;
+    } | undefined;
+}, {
+    id: string;
+    scopes: {
+        id: string;
+        include: string[];
+        isDefault: boolean;
+        products?: Record<string, Record<string, unknown>> | undefined;
+        label?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+    }[];
+    source: "preset" | "workspace" | "npm" | "implicit";
+    key?: string | undefined;
+    name?: string | undefined;
+    version?: string | undefined;
+    products?: Record<string, Record<string, unknown>> | undefined;
+    trace?: {
+        extends?: string[] | undefined;
+        overrides?: string[] | undefined;
+    } | undefined;
+    label?: string | undefined;
+    meta?: {
+        version?: string | undefined;
+        tags?: string[] | undefined;
+        deprecated?: boolean | undefined;
+        owner?: string | undefined;
+    } | undefined;
+    productsByScope?: Record<string, Record<string, Record<string, unknown>>> | undefined;
+    activeScopeId?: string | undefined;
+    activeScope?: {
+        id: string;
+        include: string[];
+        isDefault: boolean;
+        products?: Record<string, Record<string, unknown>> | undefined;
+        label?: string | undefined;
+        description?: string | undefined;
+        exclude?: string[] | undefined;
+    } | undefined;
+    scopeSelection?: {
+        strategy: "default" | "auto" | "explicit" | "none";
+        path?: string | undefined;
+    } | undefined;
+}>;
+type BundleProfile = z.infer<typeof BundleProfileSchema>;
+
+/**
+ * @module @kb-labs/core-config/profiles/loader
+ * Load + validate profiles[] section from kb.config.*
+ */
+
+interface ProfilesSectionResult {
+    profiles: ProfileV2[];
+    sourcePath?: string;
+    format?: 'json' | 'yaml';
+}
+declare function readProfilesSection(cwd: string): Promise<ProfilesSectionResult>;
+
+/**
+ * @module @kb-labs/core-config/profiles/scope-selector
+ * Resolve active scope based on include/exclude globs and CLI flags.
+ */
+
+type ScopeSelectionStrategy = 'explicit' | 'default' | 'auto' | 'none';
+interface ScopeSelectionOptions {
+    bundleProfile: BundleProfile;
+    cwd: string;
+    executionPath: string;
+    scopeId?: string;
+}
+interface ScopeSelectionResult {
+    scope?: ResolvedScope;
+    strategy: ScopeSelectionStrategy;
+    matchedPath?: string;
+}
+declare function selectProfileScope(opts: ScopeSelectionOptions): ScopeSelectionResult;
+
+/**
+ * @module @kb-labs/core-config/profiles/resolver
+ * Resolve ProfileV2 definitions with extends/merge semantics.
+ */
+
+interface ResolveProfileOptions {
+    cwd: string;
+    profileId: string;
+}
+declare function resolveProfile(opts: ResolveProfileOptions): Promise<BundleProfile>;
+
+/**
+ * @module @kb-labs/core/config/types/init
+ * Types for init operations
+ */
+interface InitWorkspaceOptions {
+    cwd: string;
+    format?: 'yaml' | 'json';
+    presetRef?: string | null;
+    profiles?: Record<string, string>;
+    products?: string[];
+    dryRun?: boolean;
+    force?: boolean;
+}
+interface InitAction {
+    kind: 'write' | 'append' | 'update' | 'skip' | 'conflict';
+    path: string;
+    previewDiff?: string;
+}
+interface InitResult {
+    actions: InitAction[];
+    created: string[];
+    updated: string[];
+    skipped: string[];
+    warnings: string[];
+}
+interface UpsertLockfileOptions {
+    cwd: string;
+    presetRef?: string | null;
+    profileRef?: string | null;
+    policyBundle?: string | null;
+    dryRun?: boolean;
+}
+
+/**
+ * @module @kb-labs/core/config/api/init-workspace
+ * Initialize workspace configuration with idempotent operations
+ */
+
+/**
+ * Initialize or update workspace configuration
+ */
+declare function initWorkspaceConfig(opts: InitWorkspaceOptions): Promise<InitResult>;
+
+/**
+ * @module @kb-labs/core/config/api/upsert-lockfile
+ * Upsert lockfile operations
+ */
+
+/**
+ * Upsert lockfile with new references
+ */
+declare function upsertLockfile(opts: UpsertLockfileOptions): Promise<InitResult>;
+
+/**
+ * @module @kb-labs/core/config/utils/fs-atomic
+ * Atomic file write operations using tmp+rename pattern
+ */
+/**
+ * Write file atomically using tmp+rename pattern
+ * This ensures that the file is never partially written in case of crashes
+ */
+declare function writeFileAtomic(path: string, data: string | Uint8Array): Promise<void>;
+/**
+ * Ensure a path is within the workspace root
+ * Throws ERR_PATH_OUTSIDE_WORKSPACE if the path escapes the workspace
+ */
+declare function ensureWithinWorkspace(targetPath: string, workspaceRoot: string): void;
+
+type ValidationResult = {
+    ok: boolean;
+    errors: any[] | null;
+};
+declare function validateProductConfig(product: string, config: unknown): ValidationResult;
+
+export { type BundleProfile, BundleProfileSchema, type BundleProfileSource, BundleProfileSourceSchema, type ConfigFileResult, type ConfigLayer, type Diagnostic, ERROR_HINTS, type ErrorCode, FSCache, type FindNearestConfigOpts, type InitAction, type InitResult, type InitWorkspaceOptions, type JsonReadResult, type KBConfig, type KbConfigResult, KbError, type LayeredMergeResult, type LockfileData, type MergeTrace, type PresetConfig, type PresetInfo, type PresetResolutionOptions, type PresetResolutionResult, type ProductConfigResult, type ProfileLayerInput, type ProfileMeta, ProfileMetaSchema, type ProfileTrace, ProfileTraceSchema, type ProfileV2, ProfileV2Schema, type ProfilesConfig, type ProfilesSectionResult, ProfilesV2Schema, type ResolveConfigArgs, type ResolveOptions, type ResolveProfileOptions, type ResolvedScope, ResolvedScopeSchema, SYSTEM_DEFAULTS, type ScopeSelection, type ScopeSelectionOptions, type ScopeSelectionResult, ScopeSelectionSchema, type ScopeSelectionStrategy, type ScopeV2, ScopeV2Schema, type UpsertLockfileOptions, clearCaches, computeConfigHash, computeConfigsHash, ensureWithinWorkspace, explainProductConfig, findGitRoot, findKbConfig, findNearestConfig, fsCache, getAllProductIds, getConfigHash, getExitCode, getKbRootDir, getLockfileConfigHash, getLockfilePath, getLockfileStats, getPresetConfigForProduct, getPresetMetadata, getProductConfig, getProductConfigDir, getProductConfigPath, getProfilesRootDir, initWorkspaceConfig, isLockfileUpToDate, isValidProductId, layeredMergeWithTrace, mergeDefined, pickDefined, readConfigFile, readJsonWithDiagnostics, readKbConfig, readLockfile, readProfilesSection, readWorkspaceConfig, resolveConfig, resolvePreset, resolveProfile, selectProfileScope, toBool, toConfigProduct, toFsProduct, toInt, updateLockfile, upsertLockfile, validateLockfile, validateProductConfig, writeFileAtomic, writeLockfile };