@utilarium/overcontext 0.0.4-dev.0

package/dist/index.cjs

@@ -0,0 +1,1763 @@
+'use strict';
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const zod = require('zod');
+const fs = require('node:fs/promises');
+const node_fs = require('node:fs');
+const path = require('node:path');
+const yaml = require('js-yaml');
+
+function _interopNamespaceDefault(e) {
+    const n = Object.create(null, { [Symbol.toStringTag]: { value: 'Module' } });
+    if (e) {
+        for (const k in e) {
+            if (k !== 'default') {
+                const d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: () => e[k]
+                });
+            }
+        }
+    }
+    n.default = e;
+    return Object.freeze(n);
+}
+
+const fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
+const path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
+const yaml__namespace = /*#__PURE__*/_interopNamespaceDefault(yaml);
+
+/**
+ * Metadata that overcontext manages automatically.
+ * Consumers don't need to define these.
+ */ const EntityMetadataSchema = zod.z.object({
+    createdAt: zod.z.date().optional(),
+    updatedAt: zod.z.date().optional(),
+    createdBy: zod.z.string().optional(),
+    namespace: zod.z.string().optional(),
+    source: zod.z.string().optional()
+});
+/**
+ * The minimal contract every entity must satisfy.
+ * Consuming libraries extend this with their own fields.
+ */ const BaseEntitySchema = zod.z.object({
+    /** Unique identifier within the entity type (used as filename) */ id: zod.z.string().min(1),
+    /** Human-readable name (used for display and search) */ name: zod.z.string().min(1),
+    /** Entity type discriminator (must be a string literal in extensions) */ type: zod.z.string().min(1),
+    /** Optional notes - common enough to include in base */ notes: zod.z.string().optional()
+}).merge(EntityMetadataSchema);
+
+/**
+ * Helper to create a properly typed entity schema.
+ * Ensures the schema extends BaseEntitySchema.
+ */ const createEntitySchema = (typeName, extension)=>{
+    return BaseEntitySchema.extend({
+        type: zod.z.literal(typeName),
+        ...extension
+    });
+};
+
+/**
+ * Validate that an object satisfies at least the base entity contract.
+ */ const validateBaseEntity = (data)=>{
+    const result = BaseEntitySchema.safeParse(data);
+    if (result.success) {
+        return {
+            success: true,
+            data: result.data
+        };
+    }
+    return {
+        success: false,
+        errors: result.error.issues.map((e)=>({
+                path: e.path.join('.'),
+                message: e.message
+            }))
+    };
+};
+/**
+ * Validate data against a specific schema.
+ */ const validateEntity = (schema, data)=>{
+    const result = schema.safeParse(data);
+    if (result.success) {
+        return {
+            success: true,
+            data: result.data
+        };
+    }
+    return {
+        success: false,
+        errors: result.error.issues.map((e)=>({
+                path: e.path.join('.'),
+                message: e.message
+            }))
+    };
+};
+/**
+ * Check if data extends the base entity (has id, name, type).
+ */ const isBaseEntity = (data)=>{
+    return validateBaseEntity(data).success;
+};
+/**
+ * Format Zod errors into a readable message.
+ */ const formatValidationErrors = (errors)=>{
+    return errors.issues.map((e)=>`${e.path.join('.')}: ${e.message}`).join('; ');
+};
+
+/**
+ * Default plural name derivation.
+ */ const derivePluralName = (type)=>{
+    // Simple pluralization rules
+    if (type.endsWith('y')) {
+        return type.slice(0, -1) + 'ies';
+    }
+    if (type.endsWith('s') || type.endsWith('x') || type.endsWith('ch') || type.endsWith('sh')) {
+        return type + 'es';
+    }
+    return type + 's';
+};
+/**
+ * Create a new schema registry.
+ */ const createSchemaRegistry = ()=>{
+    const schemas = new Map();
+    const directoryToType = new Map();
+    const register = (options)=>{
+        const { type, schema, pluralName, customValidator } = options;
+        const plural = pluralName || derivePluralName(type);
+        const registered = {
+            type,
+            schema,
+            pluralName: plural,
+            customValidator
+        };
+        schemas.set(type, registered);
+        directoryToType.set(plural, type);
+    };
+    const registerAll = (schemaMap)=>{
+        for (const [type, schema] of Object.entries(schemaMap)){
+            register({
+                type,
+                schema
+            });
+        }
+    };
+    const get = (type)=>{
+        return schemas.get(type);
+    };
+    const has = (type)=>{
+        return schemas.has(type);
+    };
+    const types = ()=>{
+        return Array.from(schemas.keys());
+    };
+    const getDirectoryName = (type)=>{
+        var _schemas_get;
+        return (_schemas_get = schemas.get(type)) === null || _schemas_get === void 0 ? void 0 : _schemas_get.pluralName;
+    };
+    const getTypeFromDirectory = (directory)=>{
+        return directoryToType.get(directory);
+    };
+    const validate = (entity)=>{
+        const registered = schemas.get(entity.type);
+        if (!registered) {
+            return {
+                success: false,
+                errors: [
+                    {
+                        path: 'type',
+                        message: `Unknown entity type: ${entity.type}`
+                    }
+                ]
+            };
+        }
+        // Schema validation
+        const schemaResult = validateEntity(registered.schema, entity);
+        if (!schemaResult.success) {
+            return schemaResult;
+        }
+        // Custom validation
+        if (registered.customValidator) {
+            return registered.customValidator(entity);
+        }
+        return {
+            success: true,
+            data: entity
+        };
+    };
+    const validateAs = (type, data)=>{
+        const registered = schemas.get(type);
+        if (!registered) {
+            return {
+                success: false,
+                errors: [
+                    {
+                        path: 'type',
+                        message: `Unknown entity type: ${type}`
+                    }
+                ]
+            };
+        }
+        // Add type to data if missing (for convenience when loading from files)
+        const withType = typeof data === 'object' && data !== null ? {
+            ...data,
+            type
+        } : data;
+        return validateEntity(registered.schema, withType);
+    };
+    return {
+        register,
+        registerAll,
+        get,
+        has,
+        types,
+        getDirectoryName,
+        getTypeFromDirectory,
+        validate,
+        validateAs
+    };
+};
+
+/**
+ * Create a schema map with proper type inference.
+ * 
+ * @example
+ * const { schemas, types } = defineSchemas({
+ *   person: PersonSchema,
+ *   project: ProjectSchema,
+ * });
+ * 
+ * type Person = typeof types.person;  // Inferred from PersonSchema
+ */ const defineSchemas = (schemas)=>{
+    return {
+        schemas,
+        types: {}
+    };
+};
+/**
+ * Helper to check if a schema extends BaseEntity properly.
+ */ const isValidEntitySchema = (schema)=>{
+    try {
+        // BaseEntitySchema allows extra fields, so we just need id, name, type
+        const result = schema.safeParse({
+            id: 'test',
+            name: 'Test',
+            type: 'test'
+        });
+        // If it fails, it might be because type is a literal
+        // Try without type and check if it has the base structure
+        if (!result.success) {
+            return false;
+        }
+        return true;
+    } catch  {
+        return false;
+    }
+};
+
+function _define_property$1(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+class StorageError extends Error {
+    constructor(message, code, cause){
+        super(message), _define_property$1(this, "code", void 0), _define_property$1(this, "cause", void 0), this.code = code, this.cause = cause;
+        this.name = 'StorageError';
+    }
+}
+class EntityNotFoundError extends StorageError {
+    constructor(entityType, entityId, namespace){
+        super(`Entity not found: ${entityType}/${entityId}${namespace ? ` in ${namespace}` : ''}`, 'ENTITY_NOT_FOUND'), _define_property$1(this, "entityType", void 0), _define_property$1(this, "entityId", void 0), _define_property$1(this, "namespace", void 0), this.entityType = entityType, this.entityId = entityId, this.namespace = namespace;
+        this.name = 'EntityNotFoundError';
+    }
+}
+class SchemaNotRegisteredError extends StorageError {
+    constructor(entityType){
+        super(`Schema not registered for type: ${entityType}`, 'SCHEMA_NOT_REGISTERED'), _define_property$1(this, "entityType", void 0), this.entityType = entityType;
+        this.name = 'SchemaNotRegisteredError';
+    }
+}
+class ValidationError extends StorageError {
+    constructor(message, validationErrors){
+        super(message, 'VALIDATION_ERROR'), _define_property$1(this, "validationErrors", void 0), this.validationErrors = validationErrors;
+        this.name = 'ValidationError';
+    }
+}
+class StorageAccessError extends StorageError {
+    constructor(message, cause){
+        super(message, 'STORAGE_ACCESS_ERROR', cause);
+        this.name = 'StorageAccessError';
+    }
+}
+class ReadonlyStorageError extends StorageError {
+    constructor(){
+        super('Storage is readonly', 'READONLY_STORAGE');
+        this.name = 'ReadonlyStorageError';
+    }
+}
+class NamespaceNotFoundError extends StorageError {
+    constructor(namespace){
+        super(`Namespace not found: ${namespace}`, 'NAMESPACE_NOT_FOUND'), _define_property$1(this, "namespace", void 0), this.namespace = namespace;
+        this.name = 'NamespaceNotFoundError';
+    }
+}
+
+/**
+ * Wrap any StorageProvider to make it observable.
+ */ const createObservableProvider = (provider)=>{
+    const handlers = new Set();
+    const emit = (event)=>{
+        handlers.forEach((handler)=>{
+            try {
+                handler(event);
+            } catch (error) {
+                // eslint-disable-next-line no-console
+                console.error('Storage event handler error:', error);
+            }
+        });
+    };
+    return {
+        ...provider,
+        subscribe (handler) {
+            handlers.add(handler);
+            return ()=>handlers.delete(handler);
+        },
+        async initialize () {
+            await provider.initialize();
+            emit({
+                type: 'storage:initialized',
+                timestamp: new Date()
+            });
+        },
+        async dispose () {
+            emit({
+                type: 'storage:disposed',
+                timestamp: new Date()
+            });
+            await provider.dispose();
+        },
+        async save (entity, namespace) {
+            const existing = await provider.get(entity.type, entity.id, namespace);
+            const saved = await provider.save(entity, namespace);
+            if (existing) {
+                emit({
+                    type: 'entity:updated',
+                    timestamp: new Date(),
+                    namespace,
+                    entityType: entity.type,
+                    entityId: entity.id,
+                    entity: saved,
+                    previousEntity: existing
+                });
+            } else {
+                emit({
+                    type: 'entity:created',
+                    timestamp: new Date(),
+                    namespace,
+                    entityType: entity.type,
+                    entityId: entity.id,
+                    entity: saved
+                });
+            }
+            return saved;
+        },
+        async delete (type, id, namespace) {
+            const deleted = await provider.delete(type, id, namespace);
+            if (deleted) {
+                emit({
+                    type: 'entity:deleted',
+                    timestamp: new Date(),
+                    namespace,
+                    entityType: type,
+                    entityId: id
+                });
+            }
+            return deleted;
+        },
+        async saveBatch (entities, namespace) {
+            const saved = await provider.saveBatch(entities, namespace);
+            emit({
+                type: 'batch:saved',
+                timestamp: new Date(),
+                namespace,
+                entities: saved
+            });
+            return saved;
+        },
+        async deleteBatch (refs, namespace) {
+            const count = await provider.deleteBatch(refs, namespace);
+            emit({
+                type: 'batch:deleted',
+                timestamp: new Date(),
+                namespace,
+                refs,
+                deletedCount: count
+            });
+            return count;
+        }
+    };
+};
+
+const createFileSystemProvider = async (options)=>{
+    const { basePath, registry, createIfMissing = true, extension = '.yaml', readonly = false, defaultNamespace } = options;
+    // --- Helper Functions ---
+    const getEntityDir = (type, namespace)=>{
+        const dirName = registry.getDirectoryName(type);
+        if (!dirName) {
+            throw new SchemaNotRegisteredError(type);
+        }
+        if (namespace) {
+            return path__namespace.join(basePath, namespace, dirName);
+        }
+        return path__namespace.join(basePath, dirName);
+    };
+    const getEntityPath = (type, id, namespace)=>{
+        return path__namespace.join(getEntityDir(type, namespace), `${id}${extension}`);
+    };
+    const ensureDir = async (dir)=>{
+        if (!node_fs.existsSync(dir) && createIfMissing && !readonly) {
+            await fs__namespace.mkdir(dir, {
+                recursive: true
+            });
+        }
+    };
+    const readEntity = async (filePath, type)=>{
+        try {
+            const content = await fs__namespace.readFile(filePath, 'utf-8');
+            let parsed;
+            try {
+                parsed = yaml__namespace.load(content);
+            } catch (yamlError) {
+                // eslint-disable-next-line no-console
+                console.warn(`Invalid YAML at ${filePath}:`, yamlError);
+                return undefined;
+            }
+            if (!parsed || typeof parsed !== 'object') {
+                return undefined;
+            }
+            // Validate against registered schema
+            const result = registry.validateAs(type, {
+                ...parsed,
+                source: filePath
+            });
+            if (!result.success) {
+                // eslint-disable-next-line no-console
+                console.warn(`Invalid entity at ${filePath}:`, result.errors);
+                return undefined;
+            }
+            return result.data;
+        } catch (error) {
+            if (error.code === 'ENOENT') {
+                return undefined;
+            }
+            throw new StorageAccessError(`Failed to read ${filePath}`, error);
+        }
+    };
+    const writeEntity = async (entity, namespace)=>{
+        if (readonly) {
+            throw new ReadonlyStorageError();
+        }
+        // Validate against schema
+        const validationResult = registry.validate(entity);
+        if (!validationResult.success) {
+            throw new ValidationError('Entity validation failed', validationResult.errors || []);
+        }
+        const dir = getEntityDir(entity.type, namespace);
+        await ensureDir(dir);
+        const filePath = getEntityPath(entity.type, entity.id, namespace);
+        // Remove framework-managed fields from saved YAML
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { type: _type, source: _source, ...entityToSave } = entity;
+        // Update metadata
+        const now = new Date();
+        const toSave = {
+            ...entityToSave,
+            updatedAt: now,
+            createdAt: entityToSave.createdAt || now
+        };
+        const content = yaml__namespace.dump(toSave, {
+            lineWidth: -1,
+            sortKeys: false
+        });
+        await fs__namespace.writeFile(filePath, content, 'utf-8');
+        return {
+            ...entity,
+            ...toSave,
+            type: entity.type,
+            source: filePath
+        };
+    };
+    const listDirectoryTypes = async (basePath)=>{
+        const types = [];
+        try {
+            const entries = await fs__namespace.readdir(basePath, {
+                withFileTypes: true
+            });
+            for (const entry of entries){
+                if (entry.isDirectory()) {
+                    const type = registry.getTypeFromDirectory(entry.name);
+                    if (type) {
+                        types.push(type);
+                    }
+                }
+            }
+        } catch  {
+        // Directory doesn't exist
+        }
+        return types;
+    };
+    // --- StorageProvider Implementation ---
+    const provider = {
+        name: 'filesystem',
+        location: basePath,
+        registry,
+        async initialize () {
+            if (createIfMissing && !readonly) {
+                await ensureDir(basePath);
+            }
+            if (!node_fs.existsSync(basePath)) {
+                throw new StorageAccessError(`Context path does not exist: ${basePath}`);
+            }
+        },
+        async dispose () {
+        // No cleanup needed for filesystem
+        },
+        async isAvailable () {
+            try {
+                const stat = node_fs.statSync(basePath);
+                return stat.isDirectory();
+            } catch  {
+                return false;
+            }
+        },
+        async get (type, id, namespace) {
+            const ns = namespace !== null && namespace !== void 0 ? namespace : defaultNamespace;
+            const filePath = getEntityPath(type, id, ns);
+            return readEntity(filePath, type);
+        },
+        async getAll (type, namespace) {
+            const ns = namespace !== null && namespace !== void 0 ? namespace : defaultNamespace;
+            let dir;
+            try {
+                dir = getEntityDir(type, ns);
+            } catch (error) {
+                if (error instanceof SchemaNotRegisteredError) {
+                    return [];
+                }
+                throw error;
+            }
+            if (!node_fs.existsSync(dir)) {
+                return [];
+            }
+            const files = await fs__namespace.readdir(dir);
+            const entities = [];
+            for (const file of files){
+                if (!file.endsWith('.yaml') && !file.endsWith('.yml')) {
+                    continue;
+                }
+                const entity = await readEntity(path__namespace.join(dir, file), type);
+                if (entity) {
+                    entities.push(entity);
+                }
+            }
+            return entities;
+        },
+        async find (filter) {
+            var _filter_namespace;
+            var _filter_ids;
+            let results = [];
+            const types = filter.type ? Array.isArray(filter.type) ? filter.type : [
+                filter.type
+            ] : registry.types();
+            const namespace = (_filter_namespace = filter.namespace) !== null && _filter_namespace !== void 0 ? _filter_namespace : defaultNamespace;
+            for (const type of types){
+                const entities = await this.getAll(type, namespace);
+                results = results.concat(entities);
+            }
+            // Apply ID filter
+            if ((_filter_ids = filter.ids) === null || _filter_ids === void 0 ? void 0 : _filter_ids.length) {
+                results = results.filter((e)=>filter.ids.includes(e.id));
+            }
+            // Apply search filter
+            if (filter.search) {
+                const searchLower = filter.search.toLowerCase();
+                results = results.filter((e)=>e.name.toLowerCase().includes(searchLower));
+            }
+            // Apply pagination
+            if (filter.offset) {
+                results = results.slice(filter.offset);
+            }
+            if (filter.limit) {
+                results = results.slice(0, filter.limit);
+            }
+            return results;
+        },
+        async exists (type, id, namespace) {
+            const ns = namespace !== null && namespace !== void 0 ? namespace : defaultNamespace;
+            try {
+                const filePath = getEntityPath(type, id, ns);
+                return node_fs.existsSync(filePath);
+            } catch  {
+                return false;
+            }
+        },
+        async count (filter) {
+            const results = await this.find(filter);
+            return results.length;
+        },
+        async save (entity, namespace) {
+            const ns = namespace !== null && namespace !== void 0 ? namespace : defaultNamespace;
+            return writeEntity(entity, ns);
+        },
+        async delete (type, id, namespace) {
+            if (readonly) {
+                throw new ReadonlyStorageError();
+            }
+            const ns = namespace !== null && namespace !== void 0 ? namespace : defaultNamespace;
+            try {
+                const filePath = getEntityPath(type, id, ns);
+                await fs__namespace.unlink(filePath);
+                return true;
+            } catch (error) {
+                if (error.code === 'ENOENT') {
+                    return false;
+                }
+                throw error;
+            }
+        },
+        async saveBatch (entities, namespace) {
+            const saved = [];
+            for (const entity of entities){
+                saved.push(await this.save(entity, namespace));
+            }
+            return saved;
+        },
+        async deleteBatch (refs, namespace) {
+            let count = 0;
+            for (const ref of refs){
+                if (await this.delete(ref.type, ref.id, namespace)) {
+                    count++;
+                }
+            }
+            return count;
+        },
+        async listNamespaces () {
+            const namespaces = [];
+            if (!node_fs.existsSync(basePath)) {
+                return namespaces;
+            }
+            const entries = await fs__namespace.readdir(basePath, {
+                withFileTypes: true
+            });
+            for (const entry of entries){
+                if (!entry.isDirectory()) continue;
+                // Check if it's a namespace (contains entity type directories)
+                // vs being an entity type directory itself
+                const subPath = path__namespace.join(basePath, entry.name);
+                const subTypes = await listDirectoryTypes(subPath);
+                if (subTypes.length > 0) {
+                    namespaces.push(entry.name);
+                }
+            }
+            return namespaces;
+        },
+        async namespaceExists (namespace) {
+            const namespacePath = path__namespace.join(basePath, namespace);
+            return node_fs.existsSync(namespacePath);
+        },
+        async listTypes (namespace) {
+            const ns = namespace !== null && namespace !== void 0 ? namespace : defaultNamespace;
+            const searchPath = ns ? path__namespace.join(basePath, ns) : basePath;
+            return listDirectoryTypes(searchPath);
+        }
+    };
+    return provider;
+};
+
+const createMemoryProvider = (options)=>{
+    const { registry, readonly = false, defaultNamespace, initialData = [] } = options;
+    // Storage: namespace -> type -> id -> entity
+    const store = new Map();
+    const getNamespaceStore = (namespace)=>{
+        if (!store.has(namespace)) {
+            store.set(namespace, new Map());
+        }
+        return store.get(namespace);
+    };
+    const getTypeStore = (namespace, type)=>{
+        const nsStore = getNamespaceStore(namespace);
+        if (!nsStore.has(type)) {
+            nsStore.set(type, new Map());
+        }
+        return nsStore.get(type);
+    };
+    const resolveNamespace = (ns)=>{
+        var _ref;
+        return (_ref = ns !== null && ns !== void 0 ? ns : defaultNamespace) !== null && _ref !== void 0 ? _ref : '_default';
+    };
+    // Initialize with any provided data
+    for (const entity of initialData){
+        const ns = resolveNamespace(entity.namespace);
+        getTypeStore(ns, entity.type).set(entity.id, entity);
+    }
+    return {
+        name: 'memory',
+        location: 'in-memory',
+        registry,
+        async initialize () {},
+        async dispose () {
+            store.clear();
+        },
+        async isAvailable () {
+            return true;
+        },
+        async get (type, id, namespace) {
+            const ns = resolveNamespace(namespace);
+            return getTypeStore(ns, type).get(id);
+        },
+        async getAll (type, namespace) {
+            const ns = resolveNamespace(namespace);
+            return Array.from(getTypeStore(ns, type).values());
+        },
+        async find (filter) {
+            var _filter_ids;
+            let results = [];
+            const types = filter.type ? Array.isArray(filter.type) ? filter.type : [
+                filter.type
+            ] : registry.types();
+            const ns = resolveNamespace(filter.namespace);
+            for (const type of types){
+                results = results.concat(await this.getAll(type, ns));
+            }
+            if ((_filter_ids = filter.ids) === null || _filter_ids === void 0 ? void 0 : _filter_ids.length) {
+                results = results.filter((e)=>filter.ids.includes(e.id));
+            }
+            if (filter.search) {
+                const s = filter.search.toLowerCase();
+                results = results.filter((e)=>e.name.toLowerCase().includes(s));
+            }
+            if (filter.offset) results = results.slice(filter.offset);
+            if (filter.limit) results = results.slice(0, filter.limit);
+            return results;
+        },
+        async exists (type, id, namespace) {
+            const ns = resolveNamespace(namespace);
+            return getTypeStore(ns, type).has(id);
+        },
+        async count (filter) {
+            return (await this.find(filter)).length;
+        },
+        async save (entity, namespace) {
+            if (readonly) {
+                throw new ReadonlyStorageError();
+            }
+            const validationResult = registry.validate(entity);
+            if (!validationResult.success) {
+                throw new ValidationError('Validation failed', validationResult.errors || []);
+            }
+            const ns = resolveNamespace(namespace);
+            const now = new Date();
+            const existing = getTypeStore(ns, entity.type).get(entity.id);
+            const saved = {
+                ...entity,
+                namespace: ns,
+                createdAt: (existing === null || existing === void 0 ? void 0 : existing.createdAt) || now,
+                updatedAt: now
+            };
+            getTypeStore(ns, entity.type).set(entity.id, saved);
+            return saved;
+        },
+        async delete (type, id, namespace) {
+            if (readonly) {
+                throw new ReadonlyStorageError();
+            }
+            const ns = resolveNamespace(namespace);
+            return getTypeStore(ns, type).delete(id);
+        },
+        async saveBatch (entities, namespace) {
+            return Promise.all(entities.map((e)=>this.save(e, namespace)));
+        },
+        async deleteBatch (refs, namespace) {
+            let count = 0;
+            for (const ref of refs){
+                if (await this.delete(ref.type, ref.id, namespace)) count++;
+            }
+            return count;
+        },
+        async listNamespaces () {
+            return Array.from(store.keys()).filter((ns)=>ns !== '_default');
+        },
+        async namespaceExists (namespace) {
+            return store.has(namespace);
+        },
+        async listTypes (namespace) {
+            const ns = resolveNamespace(namespace);
+            const nsStore = store.get(ns);
+            return nsStore ? Array.from(nsStore.keys()) : [];
+        }
+    };
+};
+
+/**
+ * Generate a slug from a name.
+ * "John Doe" -> "john-doe"
+ * "API Reference" -> "api-reference"
+ */ const slugify = (name)=>{
+    const cleaned = name.toLowerCase().trim().replace(/[^\w\s-]/g, '') // Remove non-word chars
+    .replace(/[\s_]+/g, '-'); // Replace spaces/underscores
+    // Single-pass algorithm to collapse hyphens and trim (avoid ReDoS)
+    const result = [];
+    let prevWasHyphen = false;
+    let startIdx = 0;
+    let endIdx = cleaned.length;
+    // Skip leading hyphens
+    while(startIdx < cleaned.length && cleaned[startIdx] === '-'){
+        startIdx++;
+    }
+    // Skip trailing hyphens
+    while(endIdx > startIdx && cleaned[endIdx - 1] === '-'){
+        endIdx--;
+    }
+    // Build result, collapsing consecutive hyphens
+    for(let i = startIdx; i < endIdx; i++){
+        const char = cleaned[i];
+        if (char === '-') {
+            if (!prevWasHyphen) {
+                result.push('-');
+                prevWasHyphen = true;
+            }
+        } else {
+            result.push(char);
+            prevWasHyphen = false;
+        }
+    }
+    return result.join('');
+};
+/**
+ * Generate a unique ID, appending a number if needed.
+ */ const generateUniqueId = async (baseName, exists)=>{
+    const baseId = slugify(baseName);
+    if (!await exists(baseId)) {
+        return baseId;
+    }
+    // Try appending numbers
+    for(let i = 2; i <= 100; i++){
+        const candidateId = `${baseId}-${i}`;
+        if (!await exists(candidateId)) {
+            return candidateId;
+        }
+    }
+    // Fallback to timestamp
+    return `${baseId}-${Date.now()}`;
+};
+
+const createSearchEngine = (options)=>{
+    const { provider, registry, defaultNamespace } = options;
+    const textMatch = (text, query, caseSensitive)=>{
+        if (!text) return false;
+        const a = caseSensitive ? text : text.toLowerCase();
+        const b = caseSensitive ? query : query.toLowerCase();
+        return a.includes(b);
+    };
+    const matchesSearch = (entity, search, searchFields, caseSensitive)=>{
+        // Always search name
+        if (textMatch(entity.name, search, caseSensitive)) {
+            return true;
+        }
+        // Search additional fields
+        for (const field of searchFields){
+            const value = entity[field];
+            if (typeof value === 'string' && textMatch(value, search, caseSensitive)) {
+                return true;
+            }
+            // Handle arrays of strings (like sounds_like)
+            if (Array.isArray(value)) {
+                for (const item of value){
+                    if (typeof item === 'string' && textMatch(item, search, caseSensitive)) {
+                        return true;
+                    }
+                }
+            }
+        }
+        return false;
+    };
+    const sortEntities = (entities, sort)=>{
+        return [
+            ...entities
+        ].sort((a, b)=>{
+            for (const { field, direction } of sort){
+                const aVal = a[field];
+                const bVal = b[field];
+                if (aVal === bVal) continue;
+                if (aVal === undefined || aVal === null) return direction === 'asc' ? 1 : -1;
+                if (bVal === undefined || bVal === null) return direction === 'asc' ? -1 : 1;
+                let cmp;
+                if (typeof aVal === 'string' && typeof bVal === 'string') {
+                    cmp = aVal.localeCompare(bVal);
+                } else if (aVal instanceof Date && bVal instanceof Date) {
+                    cmp = aVal.getTime() - bVal.getTime();
+                } else {
+                    cmp = aVal < bVal ? -1 : 1;
+                }
+                return direction === 'asc' ? cmp : -cmp;
+            }
+            return 0;
+        });
+    };
+    return {
+        async search (options) {
+            const { type, namespace, ids, search, searchFields = [], caseSensitive = false, limit, offset = 0, sort = [
+                {
+                    field: 'name',
+                    direction: 'asc'
+                }
+            ] } = options;
+            // Determine which types to search
+            const types = type ? Array.isArray(type) ? type : [
+                type
+            ] : registry.types();
+            // Determine which namespaces to search
+            const namespaces = namespace ? Array.isArray(namespace) ? namespace : [
+                namespace
+            ] : [
+                defaultNamespace
+            ];
+            // Collect entities
+            let allEntities = [];
+            for (const t of types){
+                for (const ns of namespaces){
+                    const entities = await provider.getAll(t, ns);
+                    allEntities = allEntities.concat(entities);
+                }
+            }
+            // Apply ID filter
+            if (ids === null || ids === void 0 ? void 0 : ids.length) {
+                allEntities = allEntities.filter((e)=>ids.includes(e.id));
+            }
+            // Apply search filter
+            if (search) {
+                allEntities = allEntities.filter((e)=>matchesSearch(e, search, searchFields, caseSensitive));
+            }
+            // Apply sorting
+            allEntities = sortEntities(allEntities, sort);
+            // Get total before pagination
+            const total = allEntities.length;
+            // Apply pagination
+            const paginated = allEntities.slice(offset, limit ? offset + limit : undefined);
+            return {
+                items: paginated,
+                total,
+                hasMore: limit ? offset + limit < total : false,
+                query: options
+            };
+        },
+        async quickSearch (query, options = {}) {
+            const result = await this.search({
+                ...options,
+                search: query
+            });
+            return result.items;
+        }
+    };
+};
+
+const createContext = (options)=>{
+    const { provider, registry, defaultNamespace } = options;
+    const resolveNamespace = (ns)=>ns !== null && ns !== void 0 ? ns : defaultNamespace;
+    const searchEngine = createSearchEngine({
+        provider,
+        registry,
+        defaultNamespace
+    });
+    const api = {
+        provider,
+        registry,
+        defaultNamespace,
+        async get (type, id, namespace) {
+            return provider.get(type, id, resolveNamespace(namespace));
+        },
+        async getAll (type, namespace) {
+            return provider.getAll(type, resolveNamespace(namespace));
+        },
+        async exists (type, id, namespace) {
+            return provider.exists(type, id, resolveNamespace(namespace));
+        },
+        async create (type, data, options = {}) {
+            var _options_generateUniqueId;
+            const namespace = resolveNamespace(options.namespace);
+            const shouldGenerateUnique = (_options_generateUniqueId = options.generateUniqueId) !== null && _options_generateUniqueId !== void 0 ? _options_generateUniqueId : true;
+            let id;
+            if (options.id) {
+                id = options.id;
+            } else if (shouldGenerateUnique) {
+                id = await generateUniqueId(data.name, (testId)=>provider.exists(type, testId, namespace));
+            } else {
+                id = slugify(data.name);
+            }
+            const entity = {
+                ...data,
+                id,
+                type,
+                createdAt: new Date(),
+                updatedAt: new Date()
+            };
+            return provider.save(entity, namespace);
+        },
+        async update (type, id, updates, namespace) {
+            const ns = resolveNamespace(namespace);
+            const existing = await provider.get(type, id, ns);
+            if (!existing) {
+                throw new EntityNotFoundError(type, id, ns);
+            }
+            const updated = {
+                ...existing,
+                ...updates,
+                id,
+                type,
+                updatedAt: new Date()
+            };
+            return provider.save(updated, ns);
+        },
+        async upsert (type, entity, namespace) {
+            const ns = resolveNamespace(namespace);
+            const existing = await provider.get(type, entity.id, ns);
+            const now = new Date();
+            const toSave = {
+                ...existing,
+                ...entity,
+                type,
+                createdAt: (existing === null || existing === void 0 ? void 0 : existing.createdAt) || now,
+                updatedAt: now
+            };
+            return provider.save(toSave, ns);
+        },
+        async delete (type, id, namespace) {
+            return provider.delete(type, id, resolveNamespace(namespace));
+        },
+        types () {
+            return registry.types();
+        },
+        withNamespace (namespace) {
+            return createContext({
+                ...options,
+                defaultNamespace: namespace
+            });
+        },
+        search: searchEngine.search.bind(searchEngine),
+        quickSearch: searchEngine.quickSearch.bind(searchEngine)
+    };
+    return api;
+};
+
+const createTypedAPI = (options)=>{
+    const { schemas, provider, defaultNamespace, pluralNames = {} } = options;
+    // Create registry from schemas
+    const registry = createSchemaRegistry();
+    for (const [type, schema] of Object.entries(schemas)){
+        registry.register({
+            type,
+            schema: schema,
+            pluralName: pluralNames[type]
+        });
+    }
+    return createContext({
+        provider,
+        registry,
+        schemas,
+        defaultNamespace
+    });
+};
+
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+/**
+ * Fluent query builder for constructing search queries.
+ */ class QueryBuilder {
+    /**
+     * Filter by entity type(s).
+     */ type(type) {
+        this.options.type = type;
+        return this;
+    }
+    /**
+     * Filter by namespace(s).
+     */ namespace(ns) {
+        this.options.namespace = ns;
+        return this;
+    }
+    /**
+     * Filter by specific IDs.
+     */ ids(ids) {
+        this.options.ids = ids;
+        return this;
+    }
+    /**
+     * Add text search.
+     */ search(query, fields) {
+        this.options.search = query;
+        if (fields) this.options.searchFields = fields;
+        return this;
+    }
+    /**
+     * Enable case-sensitive search.
+     */ caseSensitive(enabled = true) {
+        this.options.caseSensitive = enabled;
+        return this;
+    }
+    /**
+     * Add sort field.
+     */ sortBy(field, direction = 'asc') {
+        this.options.sort = [
+            ...this.options.sort || [],
+            {
+                field,
+                direction
+            }
+        ];
+        return this;
+    }
+    /**
+     * Set result limit.
+     */ limit(n) {
+        this.options.limit = n;
+        return this;
+    }
+    /**
+     * Set result offset.
+     */ offset(n) {
+        this.options.offset = n;
+        return this;
+    }
+    /**
+     * Set page (calculates offset from limit).
+     */ page(pageNum, pageSize) {
+        this.options.limit = pageSize;
+        this.options.offset = (pageNum - 1) * pageSize;
+        return this;
+    }
+    /**
+     * Build the query options.
+     */ build() {
+        return {
+            ...this.options
+        };
+    }
+    constructor(){
+        _define_property(this, "options", {});
+    }
+}
+/**
+ * Start building a query.
+ */ const query = ()=>new QueryBuilder();
+
+const createNamespaceResolver = (options)=>{
+    const { provider, defaultNamespace = '_default' } = options;
+    const configuredNamespaces = new Map();
+    // Load initial configurations
+    if (options.namespaces) {
+        for (const ns of options.namespaces){
+            configuredNamespaces.set(ns.id, ns);
+        }
+    }
+    return {
+        async resolve (requested) {
+            let namespaceIds;
+            if (!requested) {
+                namespaceIds = [
+                    defaultNamespace
+                ];
+            } else if (typeof requested === 'string') {
+                namespaceIds = [
+                    requested
+                ];
+            } else {
+                namespaceIds = requested;
+            }
+            const references = [];
+            const readable = [];
+            let primary;
+            for(let i = 0; i < namespaceIds.length; i++){
+                const nsId = namespaceIds[i];
+                const config = configuredNamespaces.get(nsId);
+                // Include all requested namespaces, even if they don't exist yet
+                const ref = {
+                    namespace: nsId,
+                    priority: namespaceIds.length - i,
+                    searchable: (config === null || config === void 0 ? void 0 : config.active) !== false,
+                    writable: i === 0
+                };
+                references.push(ref);
+                readable.push(nsId);
+                if (!primary) {
+                    primary = nsId;
+                }
+            }
+            if (!primary) {
+                primary = defaultNamespace;
+                readable.push(defaultNamespace);
+            }
+            return {
+                primary,
+                readable,
+                references
+            };
+        },
+        async listAll () {
+            const discovered = await provider.listNamespaces();
+            const all = new Map();
+            // Add configured namespaces
+            for (const [id, config] of configuredNamespaces){
+                all.set(id, config);
+            }
+            // Add discovered namespaces
+            for (const nsId of discovered){
+                if (!all.has(nsId)) {
+                    all.set(nsId, {
+                        id: nsId,
+                        name: nsId,
+                        active: true
+                    });
+                }
+            }
+            return Array.from(all.values());
+        },
+        register (config) {
+            configuredNamespaces.set(config.id, config);
+        },
+        getPrimary () {
+            return defaultNamespace;
+        },
+        async exists (namespace) {
+            return configuredNamespaces.has(namespace) || await provider.namespaceExists(namespace);
+        }
+    };
+};
+
+const createMultiNamespaceContext = async (options, namespaces)=>{
+    const { api, resolver } = options;
+    const { provider } = api;
+    const resolution = await resolver.resolve(namespaces);
+    return {
+        // Forward base API methods
+        provider: api.provider,
+        registry: api.registry,
+        defaultNamespace: resolution.primary,
+        get: (type, id, namespace)=>api.get(type, id, namespace !== null && namespace !== void 0 ? namespace : resolution.primary),
+        getAll: (type, namespace)=>api.getAll(type, namespace !== null && namespace !== void 0 ? namespace : resolution.primary),
+        exists: (type, id, namespace)=>api.exists(type, id, namespace !== null && namespace !== void 0 ? namespace : resolution.primary),
+        create: (type, data, opts)=>{
+            var _ref;
+            return api.create(type, data, {
+                ...opts,
+                namespace: (_ref = opts === null || opts === void 0 ? void 0 : opts.namespace) !== null && _ref !== void 0 ? _ref : resolution.primary
+            });
+        },
+        update: (type, id, updates, namespace)=>api.update(type, id, updates, namespace !== null && namespace !== void 0 ? namespace : resolution.primary),
+        upsert: (type, entity, namespace)=>api.upsert(type, entity, namespace !== null && namespace !== void 0 ? namespace : resolution.primary),
+        delete: (type, id, namespace)=>api.delete(type, id, namespace !== null && namespace !== void 0 ? namespace : resolution.primary),
+        types: ()=>api.types(),
+        search: (opts)=>api.search(opts),
+        quickSearch: (q, opts)=>api.quickSearch(q, opts),
+        withNamespace: (ns)=>api.withNamespace(ns),
+        // Multi-namespace methods
+        async getFromAny (type, id) {
+            for (const ns of resolution.readable){
+                const entity = await provider.get(type, id, ns);
+                if (entity) {
+                    return {
+                        entity: entity,
+                        namespace: ns
+                    };
+                }
+            }
+            return undefined;
+        },
+        async getAllMerged (type) {
+            const byId = new Map();
+            // Process in reverse priority order so higher priority wins
+            const reversed = [
+                ...resolution.readable
+            ].reverse();
+            for (const ns of reversed){
+                const entities = await provider.getAll(type, ns);
+                for (const entity of entities){
+                    byId.set(entity.id, entity);
+                }
+            }
+            return Array.from(byId.values());
+        },
+        async locateEntity (type, id) {
+            for (const ns of resolution.readable){
+                if (await provider.exists(type, id, ns)) {
+                    return ns;
+                }
+            }
+            return undefined;
+        },
+        getResolution () {
+            return resolution;
+        },
+        async withNamespaces (ns) {
+            return createMultiNamespaceContext(options, ns);
+        }
+    };
+};
+
+const createDirectoryWalker = (options)=>{
+    const { startDir, contextDirName, maxLevels, stopAt, stopMarkers = [], registry } = options;
+    const shouldStop = async (dir)=>{
+        if (stopAt && dir === stopAt) return true;
+        for (const marker of stopMarkers){
+            if (node_fs.existsSync(path__namespace.join(dir, marker))) {
+                return true;
+            }
+        }
+        const parent = path__namespace.dirname(dir);
+        return parent === dir; // Root
+    };
+    const getNamespacesAndTypes = async (contextDir)=>{
+        const namespaces = [];
+        const types = [];
+        try {
+            const entries = await fs__namespace.readdir(contextDir, {
+                withFileTypes: true
+            });
+            for (const entry of entries){
+                if (!entry.isDirectory()) continue;
+                const subPath = path__namespace.join(contextDir, entry.name);
+                const subEntries = await fs__namespace.readdir(subPath, {
+                    withFileTypes: true
+                });
+                // Check if this is a type directory (has .yaml files)
+                const hasYamlFiles = subEntries.some((sub)=>sub.isFile() && (sub.name.endsWith('.yaml') || sub.name.endsWith('.yml')));
+                // Check if this looks like a type directory (known to registry)
+                const isTypeDir = registry ? !!registry.getTypeFromDirectory(entry.name) : hasYamlFiles;
+                if (isTypeDir) {
+                    const typeName = (registry === null || registry === void 0 ? void 0 : registry.getTypeFromDirectory(entry.name)) || entry.name;
+                    if (!types.includes(typeName)) {
+                        types.push(typeName);
+                    }
+                } else {
+                    // Check if it's a namespace (contains type directories)
+                    const hasTypeDirs = subEntries.some((sub)=>{
+                        if (!sub.isDirectory()) return false;
+                        return registry ? !!registry.getTypeFromDirectory(sub.name) : true; // Assume any subdir could be a type
+                    });
+                    if (hasTypeDirs) {
+                        namespaces.push(entry.name);
+                    }
+                }
+            }
+        } catch  {
+        // Directory doesn't exist or can't be read
+        }
+        return {
+            namespaces,
+            types
+        };
+    };
+    return {
+        async discover () {
+            const discovered = [];
+            let currentDir = path__namespace.resolve(startDir);
+            let level = 0;
+            while(level < maxLevels){
+                const contextDir = path__namespace.join(currentDir, contextDirName);
+                if (node_fs.existsSync(contextDir)) {
+                    const { namespaces, types } = await getNamespacesAndTypes(contextDir);
+                    discovered.push({
+                        path: contextDir,
+                        level,
+                        namespaces,
+                        types
+                    });
+                }
+                if (await shouldStop(currentDir)) break;
+                currentDir = path__namespace.dirname(currentDir);
+                level++;
+            }
+            return discovered;
+        },
+        async hasContext (dir) {
+            return node_fs.existsSync(path__namespace.join(dir, contextDirName));
+        }
+    };
+};
+
+const discoverContextRoot = async (options = {})=>{
+    var _directories_;
+    const { startDir = process.cwd(), contextDirName = 'context', maxLevels = 10, projectMarkers = [
+        '.git',
+        'package.json'
+    ], registry } = options;
+    const walker = createDirectoryWalker({
+        startDir,
+        contextDirName,
+        maxLevels,
+        stopMarkers: projectMarkers,
+        registry
+    });
+    const directories = await walker.discover();
+    // Collect all namespaces and types (deduped)
+    const namespaceSet = new Set();
+    const typeSet = new Set();
+    for (const dir of directories){
+        for (const ns of dir.namespaces)namespaceSet.add(ns);
+        for (const type of dir.types)typeSet.add(type);
+    }
+    return {
+        directories,
+        primary: (_directories_ = directories[0]) === null || _directories_ === void 0 ? void 0 : _directories_.path,
+        contextPaths: directories.map((d)=>d.path),
+        allNamespaces: Array.from(namespaceSet),
+        allTypes: Array.from(typeSet)
+    };
+};
+/**
+ * Create or ensure a context directory exists.
+ */ const ensureContextRoot = async (projectDir, contextDirName = 'context')=>{
+    const contextPath = path__namespace.join(projectDir, contextDirName);
+    if (!node_fs.existsSync(contextPath)) {
+        const fs = await import('node:fs/promises');
+        await fs.mkdir(contextPath, {
+            recursive: true
+        });
+    }
+    return contextPath;
+};
+
+/**
+ * Storage provider that reads from multiple context directories
+ * and writes to the primary (closest) directory.
+ */ const createHierarchicalProvider = async (options)=>{
+    const { contextRoot, registry, readonly = false } = options;
+    if (contextRoot.contextPaths.length === 0) {
+        throw new Error('No context directories found');
+    }
+    // Create read-only providers for each context directory
+    const readProviders = [];
+    for (const contextPath of contextRoot.contextPaths){
+        const fsProvider = await createFileSystemProvider({
+            basePath: contextPath,
+            registry,
+            createIfMissing: false,
+            readonly: true
+        });
+        await fsProvider.initialize();
+        readProviders.push(fsProvider);
+    }
+    // Primary provider for writes
+    const primaryProvider = await createFileSystemProvider({
+        basePath: contextRoot.primary,
+        registry,
+        createIfMissing: true,
+        readonly
+    });
+    await primaryProvider.initialize();
+    const findEntities = async (filter)=>{
+        const byId = new Map();
+        for (const p of [
+            ...readProviders
+        ].reverse()){
+            const results = await p.find(filter);
+            for (const entity of results){
+                byId.set(entity.id, entity);
+            }
+        }
+        let results = Array.from(byId.values());
+        if (filter.offset) results = results.slice(filter.offset);
+        if (filter.limit) results = results.slice(0, filter.limit);
+        return results;
+    };
+    return {
+        name: 'hierarchical',
+        location: contextRoot.primary,
+        registry,
+        async initialize () {},
+        async dispose () {
+            for (const p of readProviders)await p.dispose();
+            await primaryProvider.dispose();
+        },
+        async isAvailable () {
+            return primaryProvider.isAvailable();
+        },
+        // Read operations search all providers (closest first)
+        async get (type, id, namespace) {
+            for (const p of readProviders){
+                const entity = await p.get(type, id, namespace);
+                if (entity) return entity;
+            }
+            return undefined;
+        },
+        async getAll (type, namespace) {
+            const byId = new Map();
+            // Process in reverse order so closest overwrites
+            for (const p of [
+                ...readProviders
+            ].reverse()){
+                const entities = await p.getAll(type, namespace);
+                for (const entity of entities){
+                    byId.set(entity.id, entity);
+                }
+            }
+            return Array.from(byId.values());
+        },
+        find: findEntities,
+        async exists (type, id, namespace) {
+            for (const p of readProviders){
+                if (await p.exists(type, id, namespace)) return true;
+            }
+            return false;
+        },
+        async count (filter) {
+            const results = await findEntities(filter);
+            return results.length;
+        },
+        // Write operations go to primary
+        save: (entity, namespace)=>primaryProvider.save(entity, namespace),
+        delete: (type, id, namespace)=>primaryProvider.delete(type, id, namespace),
+        saveBatch: (entities, namespace)=>primaryProvider.saveBatch(entities, namespace),
+        deleteBatch: (refs, namespace)=>primaryProvider.deleteBatch(refs, namespace),
+        listNamespaces: ()=>Promise.resolve(contextRoot.allNamespaces),
+        namespaceExists: (ns)=>Promise.resolve(contextRoot.allNamespaces.includes(ns)),
+        listTypes: ()=>Promise.resolve(contextRoot.allTypes)
+    };
+};
+
+/**
+ * Discover context directories and create an API.
+ */ const discoverOvercontext = async (options)=>{
+    const { schemas, pluralNames = {}, readonly, ...rootOptions } = options;
+    // Create registry
+    const registry = createSchemaRegistry();
+    for (const [type, schema] of Object.entries(schemas)){
+        registry.register({
+            type,
+            schema: schema,
+            pluralName: pluralNames[type]
+        });
+    }
+    // Discover context directories
+    const contextRoot = await discoverContextRoot({
+        ...rootOptions,
+        registry
+    });
+    if (!contextRoot.primary) {
+        throw new Error('No context directory found');
+    }
+    // Create hierarchical provider
+    const provider = await createHierarchicalProvider({
+        contextRoot,
+        registry,
+        readonly
+    });
+    // Create context API
+    return createContext({
+        provider,
+        registry,
+        schemas,
+        defaultNamespace: undefined
+    });
+};
+
+/**
+ * Format entities for CLI output.
+ */ const formatEntities = (entities, options)=>{
+    const { format, fields, noHeaders } = options;
+    if (format === 'json') {
+        return JSON.stringify(entities, null, 2);
+    }
+    if (format === 'yaml') {
+        return yaml__namespace.dump(entities);
+    }
+    // Table format
+    if (entities.length === 0) {
+        return 'No entities found.';
+    }
+    const displayFields = fields || [
+        'id',
+        'name',
+        'type'
+    ];
+    const rows = [];
+    if (!noHeaders) {
+        rows.push(displayFields.map((f)=>f.toUpperCase()));
+    }
+    for (const entity of entities){
+        const row = displayFields.map((f)=>{
+            const value = entity[f];
+            if (value === undefined || value === null) return '-';
+            if (typeof value === 'object') return JSON.stringify(value);
+            return String(value);
+        });
+        rows.push(row);
+    }
+    // Calculate column widths
+    const widths = displayFields.map((_, i)=>Math.max(...rows.map((row)=>row[i].length)));
+    // Format rows
+    return rows.map((row)=>row.map((cell, i)=>cell.padEnd(widths[i])).join('  ')).join('\n');
+};
+/**
+ * Format a single entity for display.
+ */ const formatEntity = (entity, options)=>{
+    if (options.format === 'json') {
+        return JSON.stringify(entity, null, 2);
+    }
+    return yaml__namespace.dump(entity);
+};
+
+/**
+ * Build a list command handler.
+ */ const listCommand = async (ctx, options)=>{
+    const result = await ctx.api.search({
+        type: options.type,
+        namespace: ctx.namespace,
+        search: options.search,
+        limit: options.limit || 20
+    });
+    return formatEntities(result.items, {
+        format: ctx.outputFormat,
+        fields: options.fields
+    });
+};
+/**
+ * Build a get command handler.
+ */ const getCommand = async (ctx, options)=>{
+    const entity = await ctx.api.get(options.type, options.id, ctx.namespace);
+    if (!entity) {
+        throw new Error(`Entity not found: ${options.type}/${options.id}`);
+    }
+    return formatEntity(entity, {
+        format: ctx.outputFormat
+    });
+};
+/**
+ * Build a create command handler.
+ */ const createCommand = async (ctx, options)=>{
+    const entity = await ctx.api.create(options.type, {
+        name: options.name,
+        ...options.data
+    }, {
+        id: options.id,
+        namespace: ctx.namespace
+    });
+    return `Created ${options.type}: ${entity.id}`;
+};
+/**
+ * Build an update command handler.
+ */ const updateCommand = async (ctx, options)=>{
+    await ctx.api.update(options.type, options.id, options.data, ctx.namespace);
+    return `Updated ${options.type}: ${options.id}`;
+};
+/**
+ * Build a delete command handler.
+ */ const deleteCommand = async (ctx, options)=>{
+    const deleted = await ctx.api.delete(options.type, options.id, ctx.namespace);
+    if (!deleted) {
+        throw new Error(`Entity not found: ${options.type}/${options.id}`);
+    }
+    return `Deleted ${options.type}: ${options.id}`;
+};
+
+/**
+ * CLI builder for consumers to create their own CLIs.
+ * 
+ * @example
+ * const cli = createCLIBuilder({ api });
+ * 
+ * // In your CLI tool:
+ * const result = await cli.list({ type: 'person' });
+ * console.log(result);
+ */ const createCLIBuilder = (options)=>{
+    const { api, defaultFormat = 'table' } = options;
+    const createContext = (format, namespace)=>({
+            api,
+            outputFormat: format || defaultFormat,
+            namespace
+        });
+    return {
+        /**
+         * List entities.
+         */ list: (opts)=>listCommand(createContext(opts.format, opts.namespace), opts),
+        /**
+         * Get a single entity.
+         */ get: (opts)=>getCommand(createContext(opts.format, opts.namespace), opts),
+        /**
+         * Create an entity.
+         */ create: (opts)=>createCommand(createContext(opts.format, opts.namespace), opts),
+        /**
+         * Update an entity.
+         */ update: (opts)=>updateCommand(createContext(opts.format, opts.namespace), opts),
+        /**
+         * Delete an entity.
+         */ delete: (opts)=>deleteCommand(createContext(opts.format, opts.namespace), opts),
+        /**
+         * List available entity types.
+         */ types: ()=>api.types()
+    };
+};
+
+exports.BaseEntitySchema = BaseEntitySchema;
+exports.EntityMetadataSchema = EntityMetadataSchema;
+exports.EntityNotFoundError = EntityNotFoundError;
+exports.NamespaceNotFoundError = NamespaceNotFoundError;
+exports.QueryBuilder = QueryBuilder;
+exports.ReadonlyStorageError = ReadonlyStorageError;
+exports.SchemaNotRegisteredError = SchemaNotRegisteredError;
+exports.StorageAccessError = StorageAccessError;
+exports.StorageError = StorageError;
+exports.ValidationError = ValidationError;
+exports.createCLIBuilder = createCLIBuilder;
+exports.createCommand = createCommand;
+exports.createContext = createContext;
+exports.createDirectoryWalker = createDirectoryWalker;
+exports.createEntitySchema = createEntitySchema;
+exports.createFileSystemProvider = createFileSystemProvider;
+exports.createHierarchicalProvider = createHierarchicalProvider;
+exports.createMemoryProvider = createMemoryProvider;
+exports.createMultiNamespaceContext = createMultiNamespaceContext;
+exports.createNamespaceResolver = createNamespaceResolver;
+exports.createObservableProvider = createObservableProvider;
+exports.createSchemaRegistry = createSchemaRegistry;
+exports.createSearchEngine = createSearchEngine;
+exports.createTypedAPI = createTypedAPI;
+exports.defineSchemas = defineSchemas;
+exports.deleteCommand = deleteCommand;
+exports.discoverContextRoot = discoverContextRoot;
+exports.discoverOvercontext = discoverOvercontext;
+exports.ensureContextRoot = ensureContextRoot;
+exports.formatEntities = formatEntities;
+exports.formatEntity = formatEntity;
+exports.formatValidationErrors = formatValidationErrors;
+exports.generateUniqueId = generateUniqueId;
+exports.getCommand = getCommand;
+exports.isBaseEntity = isBaseEntity;
+exports.isValidEntitySchema = isValidEntitySchema;
+exports.listCommand = listCommand;
+exports.query = query;
+exports.slugify = slugify;
+exports.updateCommand = updateCommand;
+exports.validateBaseEntity = validateBaseEntity;
+exports.validateEntity = validateEntity;
+//# sourceMappingURL=index.cjs.map