@rljson/fs-agent 0.0.2

package/dist/fs-blob-adapter.d.ts

@@ -0,0 +1,92 @@
+import { Bs } from '@rljson/bs';
+import { Json } from '@rljson/json';
+/**
+ * File metadata returned when storing a file as a blob
+ */
+export interface FileBlobMeta extends Json {
+    /** Name of the file */
+    name: string;
+    /** Blob ID where content is stored */
+    blobId: string;
+    /** File size in bytes */
+    size: number;
+    /** Last modified timestamp (milliseconds since epoch) */
+    mtime: number;
+    /** Original file path */
+    path: string;
+}
+/**
+ * Options for file-to-blob conversion
+ */
+export interface FileToBlobOptions {
+    /** Custom blob storage (defaults to BsMem) */
+    bs?: Bs;
+    /** Include full path in metadata (default: true) */
+    includePath?: boolean;
+}
+/**
+ * Options for blob-to-file conversion
+ */
+export interface BlobToFileOptions {
+    /** Custom blob storage (defaults to BsMem) */
+    bs?: Bs;
+    /** Create parent directories if they don't exist (default: true) */
+    createDirs?: boolean;
+    /** Preserve modification time (default: true) */
+    preserveMtime?: boolean;
+}
+/**
+ * Handles conversion between files and blobs in blob storage
+ */
+export declare class FsBlobAdapter {
+    private _bs;
+    constructor(bs?: Bs);
+    /**
+     * Gets the blob storage instance
+     */
+    get bs(): Bs;
+    /**
+     * Converts a file to a blob and returns metadata
+     * @param filePath - Absolute path to the file
+     * @param options - Conversion options
+     * @returns File metadata including blob ID
+     */
+    fileToBlob(filePath: string, options?: FileToBlobOptions): Promise<FileBlobMeta>;
+    /**
+     * Converts multiple files to blobs
+     * @param filePaths - Array of absolute file paths
+     * @param options - Conversion options
+     * @returns Array of file metadata
+     */
+    filesToBlobs(filePaths: string[], options?: FileToBlobOptions): Promise<FileBlobMeta[]>;
+    /**
+     * Writes a file from a blob using metadata
+     * @param metadata - File metadata including blob ID
+     * @param targetPath - Target path where file should be written
+     * @param options - Conversion options
+     */
+    blobToFile(metadata: FileBlobMeta, targetPath: string, options?: BlobToFileOptions): Promise<void>;
+    /**
+     * Writes multiple files from blobs
+     * @param metadataList - Array of file metadata
+     * @param targetDir - Target directory where files should be written
+     * @param options - Conversion options
+     */
+    blobsToFiles(metadataList: FileBlobMeta[], targetDir: string, options?: BlobToFileOptions): Promise<void>;
+    /**
+     * Retrieves file content from blob storage
+     * @param blobId - Blob ID
+     * @returns File content as Buffer
+     */
+    getFileContent(blobId: string): Promise<Buffer>;
+    /**
+     * Checks if a blob exists in storage
+     * @param blobId - Blob ID to check
+     * @returns True if blob exists
+     */
+    hasBlob(blobId: string): Promise<boolean>;
+    /**
+     * Creates an example instance for testing
+     */
+    static example(): FsBlobAdapter;
+}

package/dist/fs-db-adapter.d.ts

@@ -0,0 +1,34 @@
+import { Db } from '@rljson/db';
+import { FsTree } from './fs-scanner.js';
+/**
+ * Options for storing filesystem trees in database
+ */
+export interface StoreFsTreeOptions {
+    /**
+     * Whether to trigger notifications after storing (defaults to false)
+     */
+    notify?: boolean;
+}
+/**
+ * Adapter for storing filesystem trees in a database
+ */
+export declare class FsDbAdapter {
+    private db;
+    private treeKey;
+    constructor(db: Db, treeKey: string);
+    /**
+     * Store a filesystem tree in the database
+     * @param fsTree - The filesystem tree to store
+     * @param options - Storage options
+     * @returns The root tree reference
+     */
+    storeFsTree(fsTree: FsTree, options?: StoreFsTreeOptions): Promise<string>;
+    /**
+     * Get the tree table key
+     */
+    getTreeKey(): string;
+    /**
+     * Get the database instance
+     */
+    getDb(): Db;
+}

package/dist/fs-scanner.d.ts

@@ -0,0 +1,104 @@
+import { Bs } from '@rljson/bs';
+import { Json } from '@rljson/json';
+import { Tree, TreeRef } from '@rljson/rljson';
+/**
+ * Metadata stored in Tree.meta for file system nodes
+ */
+export interface FsNodeMeta extends Json {
+    /** Node name (file or directory name) */
+    name: string;
+    /** Type of node */
+    type: 'file' | 'directory';
+    /** Absolute path */
+    path: string;
+    /** Relative path from scan root */
+    relativePath: string;
+    /** File size in bytes (for files) */
+    size?: number;
+    /** Last modified timestamp (milliseconds since epoch) */
+    mtime: number;
+    /** Blob ID for file content (files only) */
+    blobId?: string;
+}
+/**
+ * Tree structure with hash mapping
+ */
+export interface FsTree {
+    /** Root tree hash */
+    rootHash: TreeRef;
+    /** Map of hash to tree node */
+    trees: Map<TreeRef, Tree>;
+}
+/**
+ * Type of file system change
+ */
+export type FsChangeType = 'added' | 'modified' | 'deleted';
+/**
+ * File system change event
+ */
+export interface FsChange {
+    /** Type of change */
+    type: FsChangeType;
+    /** Path that changed (relative to scan root) */
+    path: string;
+    /** Tree node (for added/modified) */
+    tree?: Tree;
+}
+/**
+ * Callback for file system changes
+ */
+export type FsChangeCallback = (change: FsChange) => void | Promise<void>;
+/**
+ * Options for scanning
+ */
+export interface FsScanOptions {
+    /** Patterns to ignore (glob patterns) */
+    ignore?: string[];
+    /** Maximum depth to scan (undefined = unlimited) */
+    maxDepth?: number;
+    /** Follow symbolic links */
+    followSymlinks?: boolean;
+    /** Blob storage implementation (defaults to BsMem) */
+    bs?: Bs;
+}
+/**
+ * Scans and watches file system changes, extracting RLJSON tree structure
+ */
+export declare class FsScanner {
+    private _rootPath;
+    private _tree;
+    private _watcher;
+    private _changeCallbacks;
+    private _options;
+    private _bs;
+    private _paused;
+    constructor(rootPath: string, options?: FsScanOptions);
+    get tree(): FsTree | null;
+    get rootPath(): string;
+    get bs(): Bs;
+    scan(): Promise<FsTree>;
+    private _scanDirectory;
+    private _shouldIgnore;
+    watch(): Promise<void>;
+    private _handleFileChange;
+    private _findTreeByPath;
+    private _notifyChange;
+    onChange(callback: FsChangeCallback): void;
+    offChange(callback: FsChangeCallback): void;
+    stopWatch(): void;
+    /**
+     * Temporarily pause file change notifications
+     * Used to prevent loops when updating filesystem from external source
+     */
+    pauseWatch(): void;
+    /**
+     * Resume file change notifications
+     */
+    resumeWatch(): void;
+    getTreeByHash(treeHash: TreeRef): Tree | undefined;
+    getTreeByPath(relativePath: string): Tree | undefined;
+    getAllTrees(): Tree[];
+    getChildren(treeHash: TreeRef): Tree[];
+    getRootTree(): Tree | undefined;
+    static example(): FsScanner;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { FsAgent, type FsAgentOptions } from './fs-agent.ts';
+export { FsBlobAdapter, type BlobToFileOptions, type FileBlobMeta, type FileToBlobOptions, } from './fs-blob-adapter.ts';
+export { FsDbAdapter, type StoreFsTreeOptions } from './fs-db-adapter.ts';
+export { FsScanner, type FsChange, type FsChangeCallback, type FsChangeType, type FsNodeMeta, type FsScanOptions, type FsTree, } from './fs-scanner.ts';
+export { runClientServerSetup, type ClientServerSetupOptions, type ClientServerSetupResult, } from './client-server/client-server-setup.ts';

package/dist/src/example.ts

@@ -0,0 +1,101 @@
+// @license
+// Copyright (c) 2025 Rljson
+//
+// Use of this source code is governed by terms that can be
+// found in the LICENSE file in the root of this package.
+
+import { FsAgent } from './fs-agent.ts';
+import { FsScanner } from './fs-scanner.ts';
+
+export const example = async () => {
+  // Print methods
+  const l = console.log;
+  const h1 = (text: string) => l(`${text}`);
+  const h2 = (text: string) => l(`  ${text}`);
+  const p = (text: string) => l(`    ${text}`);
+
+  // Example 1: Basic FsAgent
+  h1('FsAgent.example');
+  h2('Returns an instance of the FsAgent.');
+  const fsAgent = FsAgent.example;
+  p(JSON.stringify(fsAgent, null, 2));
+
+  // Example 2: File System Scanner
+  h1('\nFsScanner - Scan file system');
+  h2('Scans a directory and extracts RLJSON tree structure');
+
+  const scanner = new FsScanner('./src', {
+    ignore: ['node_modules', '.git'],
+    maxDepth: 3,
+  });
+
+  const tree = await scanner.scan();
+  p(`Scanned ${tree.trees.size} tree nodes`);
+  p(`Root hash: ${tree.rootHash}`);
+
+  // Show root tree
+  h2('Root tree:');
+  const rootTree = scanner.getRootTree();
+  if (rootTree) {
+    p(`ID: ${rootTree.id}`);
+    p(`Is Parent: ${rootTree.isParent}`);
+    p(`Children: ${rootTree.children?.length || 0}`);
+  }
+
+  // Show some trees
+  h2('Sample trees:');
+  let count = 0;
+  for (const [hash, treeNode] of tree.trees) {
+    if (count++ >= 5) break;
+    const meta = treeNode.meta as any;
+    p(
+      `${meta.type === 'directory' ? '📁' : '📄'} ${meta.name} [${hash.substring(0, 8)}...]`,
+    );
+  }
+
+  // Example 3: Watch for changes
+  h1('\nFsScanner - Watch for changes');
+  h2('Register a callback to be notified of file system changes');
+
+  scanner.onChange(async (change) => {
+    p(`${change.type.toUpperCase()}: ${change.path}`);
+  });
+
+  p('Scanner is ready. Changes will be logged.');
+  p('(Call scanner.watch() to start watching)');
+
+  // Example 4: Manual Database Sync
+  h1('\nFsAgent - Manual Database Sync');
+  h2('Manually sync filesystem changes to database using Connector');
+  p('Use syncToDb() with a Connector for socket-based synchronization:');
+  p('');
+  p('import { Connector } from "@rljson/db";');
+  p('import { Route } from "@rljson/rljson";');
+  p('import { SocketMock } from "@rljson/io";');
+  p('');
+  p('const agent = new FsAgent(');
+  p('  "./my-project",');
+  p('  myBlobStorage,');
+  p('  { ignore: ["node_modules", ".git"] }');
+  p(');');
+  p('');
+  p('const socket = new SocketMock();');
+  p('const route = Route.fromFlat("/projectTree+");');
+  p('const connector = new Connector(db, route, socket);');
+  p('');
+  p('const stopSync = await agent.syncToDb(db, connector, "projectTree");');
+  p('');
+  p('// Agent now:');
+  p('// 1. Watches for file changes');
+  p('// 2. Extracts trees and stores blobs');
+  p('// 3. Broadcasts changes via Connector');
+  p('');
+  p('// Stop syncing:');
+  p('stopSync();');
+  p('agent.dispose();');
+};
+
+/*
+// Run via "npx vite-node src/example.ts"
+example();
+*/

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@rljson/fs-agent",
+  "version": "0.0.2",
+  "description": "Rljson fs-agent description",
+  "homepage": "https://github.com/rljson/fs-agent",
+  "bugs": "https://github.com/rljson/fs-agent/issues",
+  "private": false,
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rljson/fs-agent.git"
+  },
+  "main": "dist/fs-agent.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "devDependencies": {
+    "@rljson/server": "^0.0.5",
+    "@types/node": "^25.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "cross-env": "^10.1.0",
+    "eslint": "^9.39.2",
+    "eslint-plugin-jsdoc": "^62.5.0",
+    "eslint-plugin-tsdoc": "^0.5.0",
+    "globals": "^17.3.0",
+    "jsdoc": "^4.0.5",
+    "read-pkg": "^10.0.0",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.54.0",
+    "vite": "^7.3.1",
+    "vite-node": "^5.3.0",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-tsconfig-paths": "^6.0.5",
+    "vitest": "^4.0.18",
+    "vitest-dom": "^0.1.1"
+  },
+  "dependencies": {
+    "@rljson/bs": "^0.0.20",
+    "@rljson/db": "^0.0.13",
+    "@rljson/hash": "^0.0.18",
+    "@rljson/io": "^0.0.65",
+    "@rljson/json": "^0.0.23",
+    "@rljson/rljson": "^0.0.75"
+  },
+  "scripts": {
+    "build": "pnpx vite build && tsc && node scripts/copy-readme-to-dist.js",
+    "test": "cross-env NODE_OPTIONS=--max-old-space-size=8192 pnpx vitest run --coverage && pnpm run lint",
+    "prebuild": "npm run test",
+    "lint": "pnpx eslint",
+    "updateGoldens": "cross-env UPDATE_GOLDENS=true pnpm test"
+  }
+}