fsman 0.1.4

Parse and resolve readable filesystem selection manifests
Documentation

fsman describes a filesystem selection as a tree. A manifest can name exact paths, select the children of a directory, recurse through a subtree, and exclude paths. The workspace provides a reusable Rust library, a validator and resolver CLI, an LSP server, and editor extensions for VS Code and Zed.

Manifest format

.config {
  fish {
    config.fish
    functions {
      *
      !legacy.fish
    }
  }

  hypr {
    **
    !cache
  }
}

Work {
  **
  assets {
    ***
  }
}

.hidden

Each directive occupies its own line:

Syntax Meaning
path Select an exact file or directory.
path { ... } Descend into a directory and apply nested directives.
* Select every immediate child of the current directory.
** Select recursively, respecting .gitignore files and global Git ignores inside repositories.
*** Select recursively without applying Git ignore rules.
!path Exclude a path and everything below it.

Paths are relative to the current block. Absolute paths and parent traversal with .. are rejected during resolution. Missing literal paths are ignored, and symbolic links are selected without being followed. Git-aware recursion also skips repository .git metadata. Both recursive forms honor --depth <LEVELS>.

See examples/basic.fsman for a larger example.

Getting started

Build the workspace with a current Rust toolchain:

cargo build --workspace

Validate a manifest:

cargo run -p fsman-cli -- examples/basic.fsman

Resolve it against a directory and print the selected tree:

cargo run -p fsman-cli -- resolve examples/basic.fsman --cwd "$HOME"

The resolver also supports --depth <LEVELS> for bounded recursion, --short for collapsed paths, --json for structured output, and --flat for a path list. Flags can be combined, including --json --flat.

To install the published binaries from crates.io:

cargo install fsman-cli
cargo install fsman-lsp

Node.js and TypeScript

The fsmanifest package provides a typed, promise-based API backed by an in-process Neon addon:

import { FSMan } from "fsmanifest";

const config = await FSMan.load("./dots.fsman");

if (await FSMan.validate()) {
  const paths = await FSMan.resolve(config, { short: true, flat: true });
}

The package requires Node.js 20 or newer. See its README for resolution options and local development commands.

Editor support

  • Visual Studio Code provides syntax highlighting and live parser diagnostics.
  • Zed registers the language and provides live parser diagnostics.

Both extensions launch fsman-lsp, which must be available on PATH or configured explicitly in the editor.

Publishing

Publishing is handled by the manually triggered Publish release GitHub Actions workflow. Create and push a semantic-version tag such as v0.1.0, then run the workflow for that tag from the Actions tab. The workflow verifies that the tag matches all Cargo and npm versions before publishing anything.

The release GitHub environment needs a CRATES_IO_TOKEN secret. npm packages use OIDC trusted publishing configured for publish.yml and the release environment, so no npm token is stored in GitHub. Configure that trusted publisher on fsmanifest and on each @okei/fsmanifest-* native package. The npm account must own the @okei scope. Cargo and npm publishing can be enabled independently in the workflow form.

Workspace layout

  • crates/fsman — typed manifest model, Pest parser, and filesystem resolver.
  • crates/fsman-cli — command-line validation and resolution.
  • crates/fsman-lsp — stdio language server for syntax diagnostics.
  • crates/fsman-node — Neon bindings for the Node package.
  • node — TypeScript API for loading, validation, and resolution.
  • vscode and zed — editor integrations.
  • examples — representative manifests.

Development

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

License

fsman is available under the MIT License.