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

npm install @giteam/openvfs

If prebuilt native artifacts are unavailable for your platform:

npm run build

CLI

Build and run:

cargo run --bin openvfs -- --help

NPM CLI (after install):

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

NPM CLI config file default path:

• ~/.openvfs/cli.json

Examples:

# 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 支持配置文件、环境变量、命令行参数三层配置。

优先级（高 -> 低）：

• 命令行参数
• 环境变量
• 配置文件

生成配置模板：

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

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

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，默认使用本地持久化目录（自动创建）：

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

默认配置路径：

• ~/.openvfs/cli.toml

查看当前配置文件：

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

配置文件示例：

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)

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

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

#[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

#[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

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