@aigne/afs-explorer 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 1.0.0 (2026-01-16)
+
+
+### Features
+
+* **afs:** add explorer for AFS ([97ebe2d](https://github.com/AIGNE-io/aigne-framework/commit/97ebe2de59fb4ac4a5e5dea51b027a02ee69638d))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/afs bumped to 1.4.0-beta.10
+    * @aigne/core bumped to 1.72.0-beta.24
+  * devDependencies
+    * @aigne/afs-git bumped to 1.0.0
+    * @aigne/afs-history bumped to 1.2.0-beta.11
+    * @aigne/afs-json bumped to 1.0.0
+    * @aigne/afs-local-fs bumped to 1.4.0-beta.25
+    * @aigne/test-utils bumped to 0.5.69-beta.24

package/LICENSE.md

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,133 @@
+# @aigne/afs-explorer
+
+AFS Explorer is a web-based file system explorer for the AIGNE Framework's Agentic File System (AFS). It provides a beautiful, user-friendly interface built with React, TypeScript, and Material-UI to browse, search, and view files in your AFS instances.
+
+## Features
+
+- 📁 Browse AFS file systems with an intuitive folder/file interface
+- 🌲 **File tree navigation** - Explore directories in a collapsible tree view (left sidebar)
+- 🔗 **URL-based routing** - Each directory has its own URL for easy bookmarking and sharing
+- 🔍 Search files and directories across all mounted modules
+- 👁️ View file contents with syntax highlighting for JSON/YAML
+- 📊 Display file metadata (size, type, timestamps)
+- 🎨 Modern, responsive UI built with Material-UI
+- 📱 Mobile-friendly with responsive drawer navigation
+- ⚡ Fast and efficient API based on Express
+
+## Installation
+
+```bash
+pnpm add @aigne/afs-explorer
+```
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { AFS } from "@aigne/afs";
+import { AFSHistory } from "@aigne/afs-history";
+import { LocalFS } from "@aigne/afs-local-fs";
+import { startExplorer } from "@aigne/afs-explorer";
+
+// Create and configure your AFS instance
+const afs = new AFS();
+afs.mount(new AFSHistory({ storage: { url: "file:./memory.sqlite3" } }));
+afs.mount(new LocalFS({ localPath: "./docs" }));
+
+// Start the explorer server
+const server = await startExplorer(afs, {
+  port: 3000,
+  host: "localhost",
+});
+
+console.log("AFS Explorer is running at http://localhost:3000");
+```
+
+### Custom Configuration
+
+```typescript
+import { ExplorerServer } from "@aigne/afs-explorer";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+// For production: specify the path to the built frontend
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const distPath = path.resolve(__dirname, "node_modules/@aigne/afs-explorer/dist");
+
+const server = new ExplorerServer(afs, {
+  port: 8080,
+  host: "0.0.0.0", // Listen on all interfaces
+  distPath, // Path to the built frontend files
+});
+
+await server.start();
+
+// Later, stop the server
+await server.stop();
+```
+
+**Note:** The `distPath` option is optional. If not provided, only the API endpoints will be available. In development, you can run the Vite dev server separately and use a proxy to access the API.
+
+## Development
+
+### Build the Frontend
+
+```bash
+pnpm build:web
+```
+
+This builds the React application into the `dist` directory.
+
+### Build the Library
+
+```bash
+pnpm build:lib
+```
+
+This compiles the TypeScript server code.
+
+### Build Everything
+
+```bash
+pnpm build
+```
+
+### Development Mode
+
+For development, you can run the Vite dev server separately:
+
+```bash
+pnpm dev
+```
+
+This will start the Vite dev server on port 5173 with hot module replacement.
+
+## API Endpoints
+
+The explorer provides the following REST API endpoints:
+
+- `GET /api/list?path={path}&maxDepth={depth}` - List directory contents (start from root `/`)
+- `GET /api/read?path={path}` - Read file contents
+- `GET /api/search?path={path}&query={query}` - Search files and directories
+
+## Architecture
+
+### Backend
+
+The backend is built with Express and provides:
+- RESTful API for AFS operations
+- Static file serving for the React frontend
+- CORS support for development
+
+### Frontend
+
+The frontend is a React application built with:
+- **React 19** - Modern React with hooks
+- **TypeScript** - Type-safe development
+- **Material-UI (MUI)** - Professional UI components
+- **Vite** - Fast build tool and dev server
+
+## License
+
+Elastic-2.0