Skip to content

GEMINI.md

Latest commit

 

History

History
56 lines (42 loc) · 2.94 KB

GEMINI.md

File metadata and controls

56 lines (42 loc) · 2.94 KB

SpecForge: fs-inspect

fs-inspect is a high-integrity, agent-facing CLI tool designed for filesystem exploration and inspection. It is built following the CLI Doctrine (see SKILL.md), which mandates a contract-first approach, strict separation between domain core and adapters, and machine-safe output standards.

Project Overview

  • Core Purpose: Provide a reliable, machine-readable interface for agents to perform filesystem operations like stat and find.
  • Architecture:
    • Contract (src/contract/): Defines the JSON schema for requests and responses. All input/output is governed by versioned schemas (e.g., fscli.v1).
    • Core (src/core/): Contains the domain logic and command definitions, independent of the filesystem backend or serialization.
    • Adapters (src/fs/): Concrete implementations for filesystem access, including security policies (e.g., RootPolicy).
    • CLI (src/main.rs): A thin wrapper using clap to route requests to the core and format results as JSON envelopes.

Building and Running

The project is written in Rust (Edition 2024).

Key Commands

  • Build: cargo build
  • Test: cargo test (includes unit tests and integration tests in tests/)
  • Run (Stat): 
    cargo run -- stat --request '{"root": "/abs/path", "path": "relative/path"}'
  • Run (Find): 
    cargo run -- find --request '{"root": "/abs/path", "include": ["*.rs"]}'
  • Read from Stdin: Use --request @- to pipe JSON into the command.

Features

  • schema: (Optional) Enables JSON schema generation using schemars.

Development Conventions

  1. Contract-First: Never modify the implementation before updating the contract in src/contract/.
  2. Machine-Safe Output: stdout is reserved for valid JSON envelopes. All logs, warnings (unless part of the contract), and diagnostic info must go to stderr.
  3. Error Modeling: Errors are categorized by ErrorCode and mapped to specific exit codes (e.g., InvalidRequest = 2, RootNotFound = 3).
  4. Root Policy: All filesystem operations must be bounded by a "Root" path. Path traversal (..) is strictly prohibited.
  5. No Dependencies in Core: Keep the core module free of IO and external crates where possible.

Key Files

  • SKILL.md: The "CLI Doctrine" - the foundational rules for the project.
  • src/contract/schema.rs: The source of truth for the JSON API.
  • src/fs/root_policy.rs: Logic for enforcing security boundaries.
  • references/: Detailed documentation for specific modules and implementation lessons.
  • assets/templates/: Blueprints for expanding the tool with new capabilities.

Usage for Agents

When interacting with this tool, always:

  • Expect a JSON object with a status field (complete, partial_failure, truncated, or error).
  • Use the --request @- pattern for complex queries.
  • Check the exit code to differentiate between system failures and contract-level errors.