typekro 0.4.0 → 0.5.0

package/dist/core/metadata/resource-metadata.js

@@ -0,0 +1,217 @@
+/**
+ * Resource Metadata Store
+ *
+ * Central WeakMap-based metadata store for resource objects. Replaces the
+ * non-enumerable `Object.defineProperty` pattern that was prone to silent
+ * data loss during spread, `JSON.parse(JSON.stringify())`, and `structuredClone`.
+ *
+ * WeakMap is invisible to serialization by design — no data can leak into
+ * YAML, JSON, or `Object.keys()` output. Metadata is automatically garbage
+ * collected when the resource object is no longer referenced.
+ *
+ * @module
+ * @see ROADMAP.md Phase 2.6
+ */
+// ---------------------------------------------------------------------------
+// Store
+// ---------------------------------------------------------------------------
+/**
+ * The single global WeakMap that holds all resource metadata.
+ *
+ * Using `WeakRef`-compatible keys means metadata is garbage-collected
+ * when the resource object is no longer reachable.
+ */
+const store = new WeakMap();
+// ---------------------------------------------------------------------------
+// Core accessors
+// ---------------------------------------------------------------------------
+/**
+ * Get the full metadata record for a resource, or `undefined` if none is set.
+ */
+export function getResourceMetadata(resource) {
+    return store.get(resource);
+}
+/**
+ * Get a single metadata field for a resource.
+ */
+export function getMetadataField(resource, key) {
+    return store.get(resource)?.[key];
+}
+/**
+ * Set (merge) metadata fields on a resource. Creates the metadata record if
+ * it doesn't exist yet; otherwise merges the new fields into the existing record.
+ *
+ * @returns The merged metadata record.
+ */
+export function setResourceMetadata(resource, metadata) {
+    const existing = store.get(resource) ?? {};
+    const merged = { ...existing, ...metadata };
+    store.set(resource, merged);
+    return merged;
+}
+/**
+ * Set a single metadata field on a resource.
+ */
+export function setMetadataField(resource, key, value) {
+    const existing = store.get(resource) ?? {};
+    existing[key] = value;
+    store.set(resource, existing);
+}
+/**
+ * Legacy non-enumerable property names that may still exist on objects
+ * during the migration period. These are checked and migrated to the
+ * WeakMap store when encountered.
+ */
+const LEGACY_NONENUM_PROPS = [
+    'readinessEvaluator',
+    '__resourceId',
+    'includeWhen',
+    'readyWhen',
+    'forEach',
+    '__templateOverrides',
+];
+/** Map legacy property names to their ResourceMetadata field names */
+const LEGACY_TO_METADATA = {
+    readinessEvaluator: 'readinessEvaluator',
+    __resourceId: 'resourceId',
+    includeWhen: 'includeWhen',
+    readyWhen: 'readyWhen',
+    forEach: 'forEach',
+    __templateOverrides: 'templateOverrides',
+};
+/**
+ * Copy ALL metadata from one resource to another. This replaces the old
+ * `preserveNonEnumerableProperties` helper for resource-to-resource copies
+ * (e.g., after a `{...spread}` operation).
+ *
+ * Also migrates any legacy non-enumerable properties found on the source
+ * into the WeakMap store on the target.
+ *
+ * @returns `true` if metadata was copied, `false` if source had no metadata
+ *          and no legacy properties were found.
+ */
+export function copyResourceMetadata(source, target) {
+    let copied = false;
+    // Copy existing WeakMap metadata
+    const metadata = store.get(source);
+    if (metadata) {
+        store.set(target, { ...metadata });
+        copied = true;
+    }
+    // Also migrate legacy non-enumerable properties from source to target's WeakMap
+    if (typeof source === 'object' && source !== null) {
+        for (const prop of LEGACY_NONENUM_PROPS) {
+            const desc = Object.getOwnPropertyDescriptor(source, prop);
+            if (desc && desc.value !== undefined) {
+                // Validate type before storing: readinessEvaluator must be a function
+                if (prop === 'readinessEvaluator' && typeof desc.value !== 'function')
+                    continue;
+                const metaKey = LEGACY_TO_METADATA[prop];
+                if (metaKey) {
+                    setMetadataField(target, metaKey, desc.value);
+                    copied = true;
+                }
+            }
+        }
+    }
+    return copied;
+}
+/**
+ * Check if a resource has any metadata at all.
+ */
+export function hasResourceMetadata(resource) {
+    return store.has(resource);
+}
+/**
+ * Delete all metadata for a resource. Rarely needed since WeakMap handles
+ * garbage collection automatically, but useful in tests.
+ */
+export function clearResourceMetadata(resource) {
+    return store.delete(resource);
+}
+// ---------------------------------------------------------------------------
+// Convenience: resourceId
+// ---------------------------------------------------------------------------
+/** Get the resource ID (previously `__resourceId`). */
+export function getResourceId(resource) {
+    // Check WeakMap store first
+    const fromStore = store.get(resource)?.resourceId;
+    if (fromStore)
+        return fromStore;
+    // Fallback: check for legacy `__resourceId` property on the object itself.
+    // This handles plain objects that haven't been migrated to WeakMap metadata,
+    // or objects created externally with `__resourceId` set as a property.
+    // IMPORTANT: Use Object.getOwnPropertyDescriptor to avoid triggering proxy get traps,
+    // which would cause infinite recursion when called from within a proxy get handler.
+    if (typeof resource === 'object' && resource !== null) {
+        const desc = Object.getOwnPropertyDescriptor(resource, '__resourceId');
+        if (desc && typeof desc.value === 'string')
+            return desc.value;
+    }
+    return undefined;
+}
+/** Set the resource ID (previously `__resourceId`). */
+export function setResourceId(resource, id) {
+    setMetadataField(resource, 'resourceId', id);
+}
+// ---------------------------------------------------------------------------
+// Convenience: readinessEvaluator
+// ---------------------------------------------------------------------------
+/** Get the readiness evaluator function. */
+export function getReadinessEvaluator(resource) {
+    // Check WeakMap store first
+    const fromStore = store.get(resource)?.readinessEvaluator;
+    if (fromStore)
+        return fromStore;
+    // Fallback: check for legacy `readinessEvaluator` property on the object itself.
+    // This handles plain objects with readinessEvaluator set via Object.defineProperty
+    // that haven't been migrated to WeakMap metadata.
+    // IMPORTANT: Use Object.getOwnPropertyDescriptor to avoid triggering proxy get traps,
+    // which would cause infinite recursion when called from within a proxy get handler.
+    if (typeof resource === 'object' && resource !== null) {
+        const desc = Object.getOwnPropertyDescriptor(resource, 'readinessEvaluator');
+        if (desc && typeof desc.value === 'function')
+            return desc.value;
+    }
+    return undefined;
+}
+/** Set the readiness evaluator function. */
+export function setReadinessEvaluator(resource, evaluator) {
+    setMetadataField(resource, 'readinessEvaluator', evaluator);
+}
+// ---------------------------------------------------------------------------
+// Convenience: conditional metadata
+// ---------------------------------------------------------------------------
+/** Get the includeWhen conditions. */
+export function getIncludeWhen(resource) {
+    return store.get(resource)?.includeWhen;
+}
+/** Set (replace) the includeWhen conditions. */
+export function setIncludeWhen(resource, conditions) {
+    setMetadataField(resource, 'includeWhen', conditions);
+}
+/** Get the readyWhen conditions. */
+export function getReadyWhen(resource) {
+    return store.get(resource)?.readyWhen;
+}
+/** Set (replace) the readyWhen conditions. */
+export function setReadyWhen(resource, conditions) {
+    setMetadataField(resource, 'readyWhen', conditions);
+}
+/** Get the forEach dimensions. */
+export function getForEach(resource) {
+    return store.get(resource)?.forEach;
+}
+/** Set (replace) the forEach dimensions. */
+export function setForEach(resource, dimensions) {
+    setMetadataField(resource, 'forEach', dimensions);
+}
+/** Get the template overrides. */
+export function getTemplateOverrides(resource) {
+    return store.get(resource)?.templateOverrides;
+}
+/** Set (replace) the template overrides. */
+export function setTemplateOverrides(resource, overrides) {
+    setMetadataField(resource, 'templateOverrides', overrides);
+}
+//# sourceMappingURL=resource-metadata.js.map

package/dist/core/metadata/resource-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-metadata.js","sourceRoot":"","sources":["../../../src/core/metadata/resource-metadata.ts"],"names":[],"mappings":"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"}

package/dist/core/proxy/create-resource.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Core Proxy Engine & createResource Factory
+ *
+ * This module implements the magic proxy system that enables TypeScript-native
+ * Kubernetes resource composition.  It is the **single source of truth** for:
+ *
+ * - `createRefFactory` — KubernetesRef proxy builder
+ * - `createPropertyProxy` — spec/status property proxy
+ * - `createGenericProxyResource` — top-level Enhanced proxy
+ * - `createResource` — the public factory function
+ *
+ * The module lives in `core/` because it is foundational infrastructure used
+ * by both `core/references/external-refs.ts` and every factory in
+ * `factories/`.  `factories/shared.ts` re-exports `createResource` for
+ * backward compatibility.
+ */
+import type { Enhanced, KubernetesResource } from '../types.js';
+/**
+ * Options for createResource function
+ */
+export interface CreateResourceOptions {
+    /**
+     * Kubernetes scope of the resource
+     * - 'namespaced': Resource must exist within a namespace
+     * - 'cluster': Resource is cluster-scoped and cannot have a namespace
+     */
+    scope?: 'namespaced' | 'cluster';
+}
+/**
+ * Create an Enhanced proxy resource from a plain Kubernetes resource definition.
+ *
+ * This is the foundational factory function used by all TypeKro factories.
+ * It wraps a resource in the magic proxy system that enables:
+ * - Automatic KubernetesRef generation for spec/status property access
+ * - Deterministic resource ID generation for Kro
+ * - Composition context registration
+ * - Readiness evaluator attachment
+ *
+ * @example
+ * ```typescript
+ * const deploy = createResource<V1DeploymentSpec, V1DeploymentStatus>({
+ *   apiVersion: 'apps/v1',
+ *   kind: 'Deployment',
+ *   metadata: { name: 'my-app' },
+ *   spec: { replicas: 3, ... },
+ * });
+ * ```
+ */
+export declare function createResource<TSpec extends object, TStatus extends object>(resource: KubernetesResource<TSpec, TStatus>, options?: CreateResourceOptions): Enhanced<TSpec, TStatus>;
+//# sourceMappingURL=create-resource.d.ts.map

package/dist/core/proxy/create-resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-resource.d.ts","sourceRoot":"","sources":["../../../src/core/proxy/create-resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAiBH,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAkC,MAAM,aAAa,CAAC;AAwUhG;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,KAAK,SAAS,MAAM,EAAE,OAAO,SAAS,MAAM,EACzE,QAAQ,EAAE,kBAAkB,CAAC,KAAK,EAAE,OAAO,CAAC,EAC5C,OAAO,CAAC,EAAE,qBAAqB,GAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,CA2G1B"}

package/dist/core/proxy/create-resource.js

@@ -0,0 +1,393 @@
+/**
+ * Core Proxy Engine & createResource Factory
+ *
+ * This module implements the magic proxy system that enables TypeScript-native
+ * Kubernetes resource composition.  It is the **single source of truth** for:
+ *
+ * - `createRefFactory` — KubernetesRef proxy builder
+ * - `createPropertyProxy` — spec/status property proxy
+ * - `createGenericProxyResource` — top-level Enhanced proxy
+ * - `createResource` — the public factory function
+ *
+ * The module lives in `core/` because it is foundational infrastructure used
+ * by both `core/references/external-refs.ts` and every factory in
+ * `factories/`.  `factories/shared.ts` re-exports `createResource` for
+ * backward compatibility.
+ */
+import { getCurrentCompositionContext, isInStatusBuilderContext } from '../composition/context.js';
+import { isDebugMode } from '../config/index.js';
+import { CEL_EXPRESSION_BRAND, KUBERNETES_REF_BRAND } from '../constants/brands.js';
+import { TypeKroError } from '../errors.js';
+import { conditionalExpressionIntegrator } from '../expressions/conditional/conditional-integration.js';
+import { getComponentLogger } from '../logging/index.js';
+import { getResourceId as getMetadataResourceId, getReadinessEvaluator, setReadinessEvaluator, setResourceId, } from '../metadata/index.js';
+import { ReadinessEvaluatorRegistry } from '../readiness/index.js';
+import { isKnownFactory, registerFactory } from '../resources/factory-registry.js';
+import { generateDeterministicResourceId } from '../resources/id.js';
+import { validateResourceId } from '../validation/cel-validator.js';
+import { detectStatusFieldTypo } from './known-status-fields.js';
+// Check for the debug environment variable
+const IS_DEBUG_MODE = isDebugMode();
+// Track which kinds have been auto-registered to avoid redundant registry lookups.
+const autoRegisteredKinds = new Set();
+const PROXY_ROOT_FIELDS = new Map([
+    ['data', { proxyMode: 'property', defaultValue: {} }],
+    ['stringData', { proxyMode: 'property', defaultValue: {} }],
+    ['rules', { proxyMode: 'property', defaultValue: [] }],
+    ['roleRef', { proxyMode: 'property', defaultValue: {} }],
+    ['subjects', { proxyMode: 'property', defaultValue: [] }],
+    ['provisioner', { proxyMode: 'value-or-ref' }],
+    ['parameters', { proxyMode: 'property', defaultValue: {} }],
+    ['subsets', { proxyMode: 'property', defaultValue: [] }],
+]);
+/**
+ * Deep clone a value, stripping functions (which are non-serializable proxies).
+ * Used by toJSON handlers on proxy objects to produce clean JSON output.
+ */
+function deepCloneValue(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value !== 'object')
+        return value;
+    if (value instanceof Date)
+        return new Date(value);
+    if (value instanceof RegExp)
+        return new RegExp(value);
+    if (Array.isArray(value)) {
+        return value.map((item) => deepCloneValue(item));
+    }
+    const cloned = {};
+    for (const k of Object.keys(value)) {
+        if (typeof value[k] !== 'function') {
+            cloned[k] = deepCloneValue(value[k]);
+        }
+    }
+    return cloned;
+}
+// Logger for debug mode
+const debugLogger = getComponentLogger('factory-proxy');
+// =============================================================================
+// PROXY ENGINE
+// =============================================================================
+function createRefFactory(resourceId, basePath) {
+    const proxyTarget = () => {
+        // Empty function used as proxy target
+    };
+    Object.defineProperty(proxyTarget, KUBERNETES_REF_BRAND, { value: true });
+    Object.defineProperty(proxyTarget, 'resourceId', { value: resourceId });
+    Object.defineProperty(proxyTarget, 'fieldPath', { value: basePath });
+    // Make the proxy compatible with string, number, and boolean types
+    Object.defineProperty(proxyTarget, 'valueOf', {
+        value: () => basePath,
+        enumerable: false,
+    });
+    Object.defineProperty(proxyTarget, 'toString', {
+        value: () => basePath,
+        enumerable: false,
+    });
+    return new Proxy(proxyTarget, {
+        get(target, prop) {
+            // Check for our defined properties first
+            if (prop === KUBERNETES_REF_BRAND || prop === 'resourceId' || prop === 'fieldPath') {
+                return target[prop];
+            }
+            // Check for other properties that exist on the target
+            if (prop in target)
+                return target[prop];
+            // .orValue(defaultValue) — returns a CelExpression with orValue helper
+            // Used for externalRef optional field access with default values
+            if (prop === 'orValue') {
+                return (defaultValue) => {
+                    const celExpr = typeof defaultValue === 'string'
+                        ? `${basePath}.orValue("${defaultValue}")`
+                        : `${basePath}.orValue(${String(defaultValue)})`;
+                    return {
+                        [CEL_EXPRESSION_BRAND]: true,
+                        expression: celExpr,
+                        _type: undefined,
+                    };
+                };
+            }
+            const propStr = String(prop);
+            // $ prefix — Kro optional access (.?field)
+            if (propStr.startsWith('$')) {
+                const actualField = propStr.substring(1);
+                return createRefFactory(resourceId, `${basePath}.?${actualField}`);
+            }
+            // For unknown properties, create nested references
+            return createRefFactory(resourceId, `${basePath}.${propStr}`);
+        },
+        // Proxy-based KubernetesRef factory: returns a dynamically-typed proxy
+    });
+}
+function createPropertyProxy(resourceId, basePath, target, kind) {
+    if (IS_DEBUG_MODE) {
+        debugLogger.debug('Proxy created', { resourceId, basePath });
+    }
+    return new Proxy(target, {
+        /**
+         * Trap for Object.keys, JSON.stringify, etc.
+         */
+        ownKeys(obj) {
+            return Reflect.ownKeys(obj);
+        },
+        /**
+         * Required for Object.keys() to work correctly with ownKeys trap
+         */
+        getOwnPropertyDescriptor(obj, prop) {
+            return Reflect.getOwnPropertyDescriptor(obj, prop);
+        },
+        get: (obj, prop) => {
+            // Handle toJSON specially to ensure proper serialization
+            if (prop === 'toJSON') {
+                return () => {
+                    const result = {};
+                    for (const key of Object.keys(obj)) {
+                        result[key] = deepCloneValue(obj[key]);
+                    }
+                    return result;
+                };
+            }
+            // 1. Immediately handle non-string properties.
+            if (typeof prop !== 'string') {
+                return obj[prop];
+            }
+            // 2. Check if the user is explicitly requesting a reference with the '$' prefix.
+            if (prop.startsWith('$')) {
+                const actualProp = prop.substring(1);
+                return createRefFactory(resourceId, `${basePath}.?${actualProp}`);
+            }
+            // 3. For any other access, default to "eager value" or "implicit ref for unknown" logic.
+            if (isInStatusBuilderContext() && (basePath === 'status' || basePath === 'spec')) {
+                return createRefFactory(resourceId, `${basePath}.${String(prop)}`);
+            }
+            if (prop in obj) {
+                return obj[prop];
+            }
+            else {
+                // Runtime typo detection for status field access (Phase 2.12).
+                // Only fires in debug mode, for known K8s kinds, when accessing status fields.
+                if (IS_DEBUG_MODE && basePath === 'status' && kind) {
+                    const suggestion = detectStatusFieldTypo(kind, prop);
+                    if (suggestion) {
+                        debugLogger.warn(`Possible typo: '${prop}' accessed on ${kind} status but not found in known fields. Did you mean '${suggestion}'?`, { resourceId, kind, accessedField: prop, suggestedField: suggestion });
+                    }
+                }
+                return createRefFactory(resourceId, `${basePath}.${String(prop)}`);
+            }
+        },
+        set: (obj, prop, value) => {
+            if (IS_DEBUG_MODE) {
+                debugLogger.debug('Proxy property set', { basePath, prop: String(prop), value });
+            }
+            return Reflect.set(obj, prop, value);
+        },
+    });
+}
+function createGenericProxyResource(resourceId, resource) {
+    setResourceId(resource, resourceId);
+    // Cache proxies to ensure the same proxy is returned each time
+    let specProxy;
+    let statusProxy;
+    return new Proxy(resource, {
+        ownKeys(target) {
+            return Reflect.ownKeys(target);
+        },
+        get(target, prop, receiver) {
+            // Handle toJSON specially to ensure proper serialization
+            if (prop === 'toJSON') {
+                return () => {
+                    // Clone and filter out internal fields
+                    const result = {};
+                    for (const key of Object.keys(target)) {
+                        if (key !== '__resourceId' &&
+                            key !== 'withReadinessEvaluator' &&
+                            key !== 'readinessEvaluator' &&
+                            key !== 'id') {
+                            result[key] = deepCloneValue(Reflect.get(target, key));
+                        }
+                    }
+                    return result;
+                };
+            }
+            if (prop === 'spec') {
+                if (!specProxy) {
+                    const spec = target.spec ?? {};
+                    specProxy = createPropertyProxy(resourceId, 'spec', spec);
+                }
+                return specProxy;
+            }
+            if (prop === 'status') {
+                if (!statusProxy) {
+                    const status = target.status ?? {};
+                    statusProxy = createPropertyProxy(resourceId, 'status', status, target.kind);
+                }
+                return statusProxy;
+            }
+            if (prop === 'metadata') {
+                const metadata = target.metadata || {};
+                const metadataProxy = createPropertyProxy(resourceId, 'metadata', metadata);
+                if (metadata && typeof metadata === 'object') {
+                    for (const [key, value] of Object.entries(metadata)) {
+                        if (!Object.hasOwn(metadataProxy, key)) {
+                            Object.defineProperty(metadataProxy, key, {
+                                value: value,
+                                enumerable: true,
+                                configurable: true,
+                                writable: true,
+                            });
+                        }
+                    }
+                }
+                return metadataProxy;
+            }
+            if (prop === 'id') {
+                return resourceId;
+            }
+            // Serve metadata from WeakMap store (backward compatibility for .readinessEvaluator / .__resourceId)
+            // Check both proxy (receiver) and target since metadata may be set on either
+            if (prop === 'readinessEvaluator') {
+                return getReadinessEvaluator(receiver) ?? getReadinessEvaluator(target);
+            }
+            if (prop === '__resourceId') {
+                return getMetadataResourceId(receiver) ?? getMetadataResourceId(target);
+            }
+            // Handle common Kubernetes resource fields as magic proxies (data-driven).
+            // See PROXY_ROOT_FIELDS above for the full registry.
+            if (typeof prop === 'string') {
+                const fieldConfig = PROXY_ROOT_FIELDS.get(prop);
+                if (fieldConfig && prop in target) {
+                    if (fieldConfig.proxyMode === 'property') {
+                        const value = Reflect.get(target, prop) ?? fieldConfig.defaultValue;
+                        // All property-mode fields are objects (Record/Array), safe to cast
+                        return createPropertyProxy(resourceId, prop, value);
+                    }
+                    // 'value-or-ref': return raw value when defined, otherwise a reference
+                    const value = Reflect.get(target, prop);
+                    if (value !== undefined) {
+                        return value;
+                    }
+                    return createRefFactory(resourceId, prop);
+                }
+            }
+            if (typeof prop === 'string' && prop.startsWith('$')) {
+                return createRefFactory(resourceId, prop.substring(1));
+            }
+            // For external refs, unknown properties should return reference proxies
+            if (typeof prop === 'string' &&
+                '__externalRef' in target &&
+                !(prop in target) &&
+                !prop.startsWith('__')) {
+                return createRefFactory(resourceId, prop);
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+        set(target, prop, value, receiver) {
+            return Reflect.set(target, prop, value, receiver);
+        },
+    });
+}
+/**
+ * Create an Enhanced proxy resource from a plain Kubernetes resource definition.
+ *
+ * This is the foundational factory function used by all TypeKro factories.
+ * It wraps a resource in the magic proxy system that enables:
+ * - Automatic KubernetesRef generation for spec/status property access
+ * - Deterministic resource ID generation for Kro
+ * - Composition context registration
+ * - Readiness evaluator attachment
+ *
+ * @example
+ * ```typescript
+ * const deploy = createResource<V1DeploymentSpec, V1DeploymentStatus>({
+ *   apiVersion: 'apps/v1',
+ *   kind: 'Deployment',
+ *   metadata: { name: 'my-app' },
+ *   spec: { replicas: 3, ... },
+ * });
+ * ```
+ */
+export function createResource(resource, options) {
+    // Validate namespace scope rules
+    if (options?.scope) {
+        const hasNamespace = !!resource.metadata?.namespace;
+        if (options.scope === 'cluster' && hasNamespace) {
+            throw new TypeKroError(`${resource.kind} is cluster-scoped and cannot have a namespace. ` +
+                `Remove the 'namespace' field from metadata.`, 'INVALID_RESOURCE_SCOPE', { kind: resource.kind, namespace: resource.metadata?.namespace });
+        }
+        if (options.scope === 'namespaced' && !hasNamespace) {
+            debugLogger.warn(`${resource.kind} is namespaced but no namespace specified. Kubernetes will use 'default'.`, {
+                kind: resource.kind,
+                name: resource.metadata?.name,
+            });
+        }
+    }
+    let resourceId;
+    // Check for id field on the resource itself
+    if (resource.id) {
+        resourceId = resource.id;
+        // Validate that the ID follows camelCase convention
+        const validation = validateResourceId(resourceId);
+        if (!validation.isValid) {
+            throw new TypeKroError(`Invalid resource ID: ${validation.error}`, 'INVALID_RESOURCE_ID', {
+                resourceId,
+                error: validation.error,
+            });
+        }
+        // Remove the id field from the resource to prevent it from being sent to Kubernetes
+        const { id: _id, ...cleanResource } = resource;
+        resource = cleanResource;
+    }
+    else {
+        // Use deterministic ID generation by default
+        const name = resource.metadata?.name || resource.kind.toLowerCase();
+        const namespace = resource.metadata?.namespace;
+        resourceId = generateDeterministicResourceId(resource.kind, name, namespace);
+    }
+    // Auto-register the factory in the central FactoryRegistry the first time
+    // we see a given kind, but ONLY if the factory doesn't already have an
+    // explicit registration (which may include semantic aliases that we must
+    // not overwrite).
+    if (!autoRegisteredKinds.has(resource.kind)) {
+        autoRegisteredKinds.add(resource.kind);
+        if (!isKnownFactory(resource.kind)) {
+            registerFactory({
+                factoryName: resource.kind,
+                kind: resource.kind,
+                apiVersion: resource.apiVersion,
+            });
+        }
+    }
+    const enhanced = createGenericProxyResource(resourceId, resource);
+    // Also store metadata for the PROXY itself (not just the target).
+    // This is critical because downstream code (e.g. getResourceId, getReadinessEvaluator)
+    // receives the proxy but the WeakMap entry was set on the target at line 194.
+    // Without this, WeakMap lookups on the proxy return undefined.
+    setResourceId(enhanced, resourceId);
+    // Auto-register with composition context if active (but not for external references)
+    const context = getCurrentCompositionContext();
+    if (context && !resource.__externalRef) {
+        context.addResource(resourceId, enhanced);
+    }
+    // Add fluent builder method for readiness evaluator
+    Object.defineProperty(enhanced, 'withReadinessEvaluator', {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts evaluators typed for any K8s resource
+        value: function (evaluator) {
+            // Register in global registry by KIND
+            ReadinessEvaluatorRegistry.getInstance().registerForKind(this.kind, evaluator, 'factory-defined');
+            // Attach to individual resource instance via WeakMap
+            setReadinessEvaluator(this, evaluator);
+            return this;
+        },
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    // Add conditional expression support
+    const enhancedWithConditionals = conditionalExpressionIntegrator.addConditionalSupport(enhanced, {
+        autoProcess: false,
+        validateExpressions: true,
+    });
+    return enhancedWithConditionals;
+}
+//# sourceMappingURL=create-resource.js.map