npm package: @giteam/openvfs
Description: Agent-oriented Markdown virtual file system implemented in Rust
Author: OpenVFS Contributors
Latest version: 0.1.0

# openvfs (Rust + npm)

`openvfs` is a Rust implementation of the OpenVFS Markdown virtual file system, with Node.js bindings via `napi-rs`.

## Features

- Markdown file CRUD on `openvfs://` URI scheme.
- Structured section/cell operations based on Markdown headings.
- Selector query syntax: `@id=install`, `@@scope=guide@@text()="Quick Start"`.
- Thread-safe mutations via per-file lock.
- Chain-style document builder for append-heavy workflows.
- Pluggable stores:
  - `MemoryStore` (default)
  - `RedisStore` (`--features redis-store`)
  - `S3Store` (`--features s3-store`, AWS S3/TOS/MinIO compatible)

## Install

```bash
npm install @giteam/openvfs
```

If prebuilt native artifacts are unavailable for your platform:

```bash
npm run build
```

## CLI

Build and run:

```bash
cargo run --bin openvfs -- --help
```

NPM CLI (after install):

```bash
npm i -g @giteam/openvfs
openvfs --help
```

NPM CLI config file default path:
- `~/.openvfs/cli.json`

Examples:

```bash
# Local store (default, persisted to ~/.openvfs/data)
cargo run --bin openvfs -- create --uri openvfs://resources/demo/readme --content '# Demo'
cargo run --bin openvfs -- add-cell --path resources/demo/readme --title Install --content-file ./install.md --attrs id=install,scope=guide
cargo run --bin openvfs -- find-cell --path resources/demo/readme --selector @id=install --expect one --output json

# Redis store (requires redis-store feature)
REDIS_HOST=127.0.0.1 REDIS_PORT=6379 REDIS_DB=0 cargo run --features redis-store --bin openvfs -- --store redis --prefix myspace create --uri openvfs://resources/demo/readme --content '# Redis Demo'

# S3 store (requires s3-store feature)
S3_BUCKET_NAME=my-bucket S3_REGION_NAME=ap-southeast-1 S3_ENDPOINT_URL=https://s3.ap-southeast-1.amazonaws.com \
S3_ACCESS_KEY_ID=ak S3_SECRET_ACCESS_KEY=sk \
cargo run --features s3-store --bin openvfs -- --store s3 --prefix myspace read --uri openvfs://resources/demo/readme
```

### CLI 配置（Redis）

CLI 支持配置文件、环境变量、命令行参数三层配置。

优先级（高 -> 低）：
- 命令行参数
- 环境变量
- 配置文件

生成配置模板：

```bash
cargo run --features redis-store --bin openvfs -- config init
```

首次即可直接初始化 Redis 配置（推荐）：

```bash
cargo run --features redis-store --bin openvfs -- config init --force \
  --prefix openvfs \
  --redis-host 115.190.10.130 \
  --redis-port 16379 \
  --redis-password 'your-password' \
  --redis-db 0
```

如不配置 Redis，默认使用本地持久化目录（自动创建）：

```bash
cargo run --bin openvfs -- config init --force --store local --local-dir ~/.openvfs/data
```

默认配置路径：
- `~/.openvfs/cli.toml`

查看当前配置文件：

```bash
cargo run --features redis-store --bin openvfs -- config show
```

配置文件示例：

```toml
store = "redis"
prefix = "openvfs"
namespaces = ["resources", "user", "agent"]

[local]
dir = "/Users/you/.openvfs/data"

[redis]
host = "115.190.10.130"
port = 16379
password = "your-password"
db = 0
# redis_url = "redis://:password@host:port/db" # 如设置则优先使用

[s3]
bucket = "my-bucket"
region = "ap-southeast-1"
endpoint_url = "https://s3.ap-southeast-1.amazonaws.com"
access_key_id = "your-ak"
secret_access_key = "your-sk"
```

也可用环境变量覆盖：
- `REDIS_URL`
- `REDIS_HOST`
- `REDIS_PORT`
- `REDIS_PASSWORD`
- `REDIS_DB`
- `OPENVFS_LOCAL_DIR`
- `S3_BUCKET_NAME`
- `S3_REGION_NAME`
- `S3_ENDPOINT_URL`
- `S3_ACCESS_KEY_ID`
- `S3_SECRET_ACCESS_KEY`

`--content-file` 支持两种输入：
- 文件路径，如 `--content-file ./body.md`
- 标准输入，如 `--content-file -`

## Quick Start (Node.js)

```ts
const { JsOpenVfs } = require('@giteam/openvfs')

const vfs = JsOpenVfs.initVfs()
const file = vfs.findFile('resources/project/readme', false)
if (!file) throw new Error('Cannot create file object')

file.create('# Project\n')
const doc = file.asMarkdown()
doc.addCell('Install', 'npm i @giteam/openvfs', 2, { id: 'install', class: 'guide' }, true)

const one = JSON.parse(doc.findCellJson('@id=install', 'one'))
const updated = JSON.parse(doc.updateCellJson('@id=install', 'npm i @giteam/openvfs\nnpm i @napi-rs/cli', 'one'))

console.log(one, updated)
```

## Rust API

```rust
use openvfs::OpenVfs;

let vfs = OpenVfs::default();
vfs.create("openvfs://resources/project/readme", "# Project\n")?;
let cell = vfs.add_cell(
    "resources/project/readme",
    "Install",
    "cargo add openvfs",
    2,
    None,
)?;
println!("{}", cell.title);
# Ok::<(), openvfs::OpenvfsError>(())
```

## Optional Stores (Rust)

### RedisStore

```rust
#[cfg(feature = "redis-store")]
{
    use std::sync::Arc;
    use openvfs::{OpenVfs, RedisStore, Store};

    let store = RedisStore::new("redis://127.0.0.1:6379/0", "openvfs")?;
    let vfs = OpenVfs::init_vfs(Some(Arc::new(store) as Arc<dyn Store>), None);
    let _ = vfs;
}
# Ok::<(), openvfs::OpenvfsError>(())
```

### S3Store

```rust
#[cfg(feature = "s3-store")]
{
    use std::sync::Arc;
    use openvfs::{OpenVfs, S3Store, Store};

    let store = S3Store::new(
        "my-bucket",
        "ap-southeast-1",
        Some("https://s3.ap-southeast-1.amazonaws.com"),
        Some("your-ak"),
        Some("your-sk"),
        "openvfs",
    )?;
    let vfs = OpenVfs::init_vfs(Some(Arc::new(store) as Arc<dyn Store>), None);
    let _ = vfs;
}
# Ok::<(), openvfs::OpenvfsError>(())
```

## Development

```bash
cargo test
cargo check --features node,redis-store,s3-store
npm run build
```

## Publish

1. Push tag like `v0.1.0` (or manually trigger GitHub Actions `NPM Publish` workflow).
2. Ensure `NPM_TOKEN` secret is configured in repository settings.
3. Workflow executes `cargo test`, `npm run build`, and `npm publish --access public`.

## License

MIT