@soulcraft/brainy 3.9.1 → 3.10.0

package/dist/vfs/types.d.ts

@@ -0,0 +1,330 @@
+/**
+ * Virtual Filesystem Type Definitions
+ *
+ * REAL types for production VFS implementation
+ * No mocks, no stubs, actual working definitions
+ */
+import { Entity, Relation } from '../types/brainy.types.js';
+import { VerbType } from '../types/graphTypes.js';
+import { Vector } from '../coreTypes.js';
+/**
+ * Todo item for task tracking
+ */
+export interface VFSTodo {
+    id: string;
+    task: string;
+    priority: 'low' | 'medium' | 'high';
+    status: 'pending' | 'in_progress' | 'completed';
+    assignee?: string;
+    due?: string;
+}
+/**
+ * VFS-specific metadata that extends entity metadata
+ * This is what makes a Brainy entity a "file" or "directory"
+ */
+export interface VFSMetadata {
+    path: string;
+    name: string;
+    parent?: string;
+    vfsType: 'file' | 'directory' | 'symlink';
+    size: number;
+    mimeType?: string;
+    extension?: string;
+    permissions: number;
+    owner: string;
+    group: string;
+    accessed: number;
+    modified: number;
+    storage?: {
+        type: 'inline' | 'reference' | 'chunked';
+        key?: string;
+        chunks?: string[];
+        compressed?: boolean;
+    };
+    attributes?: Record<string, any>;
+    rawData?: string;
+    tags?: string[];
+    concepts?: Array<{
+        name: string;
+        confidence: number;
+    }>;
+    todos?: VFSTodo[];
+    dependencies?: string[];
+    exports?: string[];
+    language?: string;
+    lineCount?: number;
+    wordCount?: number;
+    charset?: string;
+    hash?: string;
+    symlinkTarget?: string;
+}
+/**
+ * Complete VFS Entity - a file or directory in the virtual filesystem
+ */
+export interface VFSEntity extends Entity<VFSMetadata> {
+    metadata: VFSMetadata;
+    data?: Buffer | Uint8Array | string;
+}
+/**
+ * File stat information (Node.js fs.Stats compatible)
+ */
+export interface VFSStats {
+    size: number;
+    mode: number;
+    uid: number;
+    gid: number;
+    atime: Date;
+    mtime: Date;
+    ctime: Date;
+    birthtime: Date;
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+    path: string;
+    entityId: string;
+    vector?: Vector;
+    connections?: number;
+}
+/**
+ * Directory entry (for readdir)
+ */
+export interface VFSDirent {
+    name: string;
+    path: string;
+    type: 'file' | 'directory' | 'symlink';
+    entityId: string;
+}
+/**
+ * Error codes matching Node.js fs errors
+ */
+export declare enum VFSErrorCode {
+    ENOENT = "ENOENT",// No such file or directory
+    EEXIST = "EEXIST",// File exists
+    ENOTDIR = "ENOTDIR",// Not a directory
+    EISDIR = "EISDIR",// Is a directory
+    ENOTEMPTY = "ENOTEMPTY",// Directory not empty
+    EACCES = "EACCES",// Permission denied
+    EINVAL = "EINVAL",// Invalid argument
+    EMFILE = "EMFILE",// Too many open files
+    ENOSPC = "ENOSPC",// No space left
+    EIO = "EIO",// I/O error
+    ELOOP = "ELOOP"
+}
+/**
+ * VFS-specific error class
+ */
+export declare class VFSError extends Error {
+    code: VFSErrorCode;
+    path?: string;
+    syscall?: string;
+    constructor(code: VFSErrorCode, message: string, path?: string, syscall?: string);
+}
+export interface WriteOptions {
+    encoding?: BufferEncoding;
+    mode?: number;
+    flag?: string;
+    generateEmbedding?: boolean;
+    extractMetadata?: boolean;
+    compress?: boolean;
+    deduplicate?: boolean;
+    metadata?: Record<string, any>;
+}
+export interface ReadOptions {
+    encoding?: BufferEncoding;
+    flag?: string;
+    cache?: boolean;
+    decompress?: boolean;
+}
+export interface MkdirOptions {
+    recursive?: boolean;
+    mode?: number;
+    metadata?: Partial<VFSMetadata>;
+}
+export interface ReaddirOptions {
+    encoding?: BufferEncoding;
+    withFileTypes?: boolean;
+    recursive?: boolean;
+    limit?: number;
+    offset?: number;
+    cursor?: string;
+    filter?: {
+        pattern?: string;
+        type?: 'file' | 'directory';
+        minSize?: number;
+        maxSize?: number;
+        modifiedAfter?: Date;
+        modifiedBefore?: Date;
+    };
+    sort?: 'name' | 'size' | 'modified' | 'created';
+    order?: 'asc' | 'desc';
+}
+export interface CopyOptions {
+    overwrite?: boolean;
+    preserveTimestamps?: boolean;
+    preserveVector?: boolean;
+    preserveRelationships?: boolean;
+    deepCopy?: boolean;
+}
+export interface SearchOptions {
+    path?: string;
+    recursive?: boolean;
+    type?: 'file' | 'directory' | 'any';
+    where?: Record<string, any>;
+    limit?: number;
+    offset?: number;
+    includeContent?: boolean;
+    includeVector?: boolean;
+    explain?: boolean;
+}
+export interface SimilarOptions {
+    limit?: number;
+    threshold?: number;
+    type?: 'file' | 'directory' | 'any';
+    withinPath?: string;
+}
+export interface SearchResult {
+    path: string;
+    entityId: string;
+    score: number;
+    type: 'file' | 'directory' | 'symlink';
+    size: number;
+    modified: Date;
+    explanation?: {
+        vectorScore?: number;
+        metadataScore?: number;
+        graphScore?: number;
+    };
+}
+export interface RelatedOptions {
+    depth?: number;
+    types?: VerbType[];
+    limit?: number;
+}
+export interface ReadStreamOptions {
+    encoding?: BufferEncoding;
+    start?: number;
+    end?: number;
+    highWaterMark?: number;
+}
+export interface WriteStreamOptions {
+    encoding?: BufferEncoding;
+    mode?: number;
+    autoClose?: boolean;
+    emitClose?: boolean;
+}
+export interface WatchOptions {
+    persistent?: boolean;
+    recursive?: boolean;
+    encoding?: BufferEncoding;
+}
+export type WatchEventType = 'rename' | 'change' | 'error';
+export interface WatchListener {
+    (eventType: WatchEventType, filename: string | null): void;
+}
+export interface VFSConfig {
+    root?: string;
+    rootEntityId?: string;
+    cache?: {
+        enabled?: boolean;
+        maxPaths?: number;
+        maxContent?: number;
+        ttl?: number;
+    };
+    storage?: {
+        inline?: {
+            maxSize?: number;
+        };
+        chunking?: {
+            enabled?: boolean;
+            chunkSize?: number;
+            parallel?: number;
+        };
+        compression?: {
+            enabled?: boolean;
+            minSize?: number;
+            algorithm?: 'gzip' | 'brotli' | 'zstd';
+        };
+    };
+    intelligence?: {
+        enabled?: boolean;
+        autoEmbed?: boolean;
+        autoExtract?: boolean;
+        autoTag?: boolean;
+        autoConcepts?: boolean;
+    };
+    knowledgeLayer?: {
+        enabled?: boolean;
+        eventRecording?: boolean;
+        semanticVersioning?: boolean;
+        persistentEntities?: boolean;
+        concepts?: boolean;
+        gitBridge?: boolean;
+    };
+    permissions?: {
+        defaultFile?: number;
+        defaultDirectory?: number;
+        umask?: number;
+    };
+    limits?: {
+        maxFileSize?: number;
+        maxPathLength?: number;
+        maxDirectoryEntries?: number;
+    };
+}
+export interface IVirtualFileSystem {
+    init(config?: VFSConfig): Promise<void>;
+    close(): Promise<void>;
+    readFile(path: string, options?: ReadOptions): Promise<Buffer>;
+    writeFile(path: string, data: Buffer | string, options?: WriteOptions): Promise<void>;
+    appendFile(path: string, data: Buffer | string, options?: WriteOptions): Promise<void>;
+    unlink(path: string): Promise<void>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    rmdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(path: string, options?: ReaddirOptions): Promise<string[] | VFSDirent[]>;
+    stat(path: string): Promise<VFSStats>;
+    lstat(path: string): Promise<VFSStats>;
+    exists(path: string): Promise<boolean>;
+    chmod(path: string, mode: number): Promise<void>;
+    chown(path: string, uid: number, gid: number): Promise<void>;
+    utimes(path: string, atime: Date, mtime: Date): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    copy(src: string, dest: string, options?: CopyOptions): Promise<void>;
+    move(src: string, dest: string): Promise<void>;
+    symlink(target: string, path: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+    realpath(path: string): Promise<string>;
+    getxattr(path: string, name: string): Promise<any>;
+    setxattr(path: string, name: string, value: any): Promise<void>;
+    listxattr(path: string): Promise<string[]>;
+    removexattr(path: string, name: string): Promise<void>;
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    findSimilar(path: string, options?: SimilarOptions): Promise<SearchResult[]>;
+    getRelated(path: string, options?: RelatedOptions): Promise<Array<{
+        path: string;
+        relationship: string;
+        direction: 'from' | 'to';
+    }>>;
+    addRelationship(from: string, to: string, type: string): Promise<void>;
+    removeRelationship(from: string, to: string, type?: string): Promise<void>;
+    getRelationships(path: string): Promise<Relation[]>;
+    getTodos(path: string): Promise<VFSTodo[] | undefined>;
+    setTodos(path: string, todos: VFSTodo[]): Promise<void>;
+    addTodo(path: string, todo: VFSTodo): Promise<void>;
+    getMetadata(path: string): Promise<VFSMetadata | undefined>;
+    setMetadata(path: string, metadata: Partial<VFSMetadata>): Promise<void>;
+    createReadStream(path: string, options?: ReadStreamOptions): NodeJS.ReadableStream;
+    createWriteStream(path: string, options?: WriteStreamOptions): NodeJS.WritableStream;
+    watch(path: string, listener: WatchListener): {
+        close(): void;
+    };
+    watchFile(path: string, listener: WatchListener): void;
+    unwatchFile(path: string): void;
+    getEntity(path: string): Promise<VFSEntity>;
+    getEntityById(id: string): Promise<VFSEntity>;
+    resolvePath(path: string, from?: string): Promise<string>;
+}
+export declare function isFile(stats: VFSStats): boolean;
+export declare function isDirectory(stats: VFSStats): boolean;
+export declare function isSymlink(stats: VFSStats): boolean;

package/dist/vfs/types.js

@@ -0,0 +1,46 @@
+/**
+ * Virtual Filesystem Type Definitions
+ *
+ * REAL types for production VFS implementation
+ * No mocks, no stubs, actual working definitions
+ */
+/**
+ * Error codes matching Node.js fs errors
+ */
+export var VFSErrorCode;
+(function (VFSErrorCode) {
+    VFSErrorCode["ENOENT"] = "ENOENT";
+    VFSErrorCode["EEXIST"] = "EEXIST";
+    VFSErrorCode["ENOTDIR"] = "ENOTDIR";
+    VFSErrorCode["EISDIR"] = "EISDIR";
+    VFSErrorCode["ENOTEMPTY"] = "ENOTEMPTY";
+    VFSErrorCode["EACCES"] = "EACCES";
+    VFSErrorCode["EINVAL"] = "EINVAL";
+    VFSErrorCode["EMFILE"] = "EMFILE";
+    VFSErrorCode["ENOSPC"] = "ENOSPC";
+    VFSErrorCode["EIO"] = "EIO";
+    VFSErrorCode["ELOOP"] = "ELOOP"; // Too many symbolic links
+})(VFSErrorCode || (VFSErrorCode = {}));
+/**
+ * VFS-specific error class
+ */
+export class VFSError extends Error {
+    constructor(code, message, path, syscall) {
+        super(message);
+        this.name = 'VFSError';
+        this.code = code;
+        this.path = path;
+        this.syscall = syscall;
+    }
+}
+// Export utility type guards
+export function isFile(stats) {
+    return stats.isFile();
+}
+export function isDirectory(stats) {
+    return stats.isDirectory();
+}
+export function isSymlink(stats) {
+    return stats.isSymbolicLink();
+}
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "3.9.1",
+  "version": "3.10.0",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
   "main": "dist/index.js",
   "module": "dist/index.js",