Issues-FS

A file-system-based, graph-oriented issue tracking library with hierarchical structure and pluggable storage backends.

Issues-FS stores issues as JSON files in .issues/ directories inside git repos, enabling version control with Git, offline access, and flexible deployment options. It provides the core data layer for building issue tracking applications -- both for human developers and AI agent workflows.

Key Features

File-Based Storage -- Issues stored as issue.json files, easily version-controlled with Git
Graph-Oriented Model -- Issues, types, and links form a traversable graph via MGraph-DB integration
Hierarchical Structure -- Nest issues inside other issues via issues/ subfolders (projects > versions > tasks > subtasks)
Pluggable Backends -- Works with memory, local disk, S3, SQLite, or ZIP via Memory-FS
Type-Safe -- Built with osbot-utils Type_Safe patterns for runtime validation
Recursive Discovery -- Find issues at any depth in the hierarchy
Human-Readable -- Plain JSON files in a simple folder structure, inspectable with any text editor

Installation

pip install issues-fs

For command-line usage, also install the CLI:

pip install issues-fs-cli

Quick Start

from memory_fs.Memory_FS                          import Memory_FS
from memory_fs.storage_fs.Storage_FS__Memory      import Storage_FS__Memory
from memory_fs.storage_fs.Storage_FS__Local_Disk  import Storage_FS__Local_Disk
from issues_fs.issues.graph_services.Graph__Repository  import Graph__Repository
from issues_fs.issues.graph_services.Node__Service      import Node__Service
from issues_fs.issues.graph_services.Type__Service      import Type__Service
from issues_fs.issues.storage.Path__Handler__Graph_Node import Path__Handler__Graph_Node

# Setup with in-memory storage (great for testing)
storage_fs   = Storage_FS__Memory()
memory_fs    = Memory_FS(storage_fs=storage_fs)
path_handler = Path__Handler__Graph_Node(base_path='')
repository   = Graph__Repository(memory_fs=memory_fs, path_handler=path_handler)

# Or use local disk storage
storage_fs   = Storage_FS__Local_Disk(root_path='.issues')
memory_fs    = Memory_FS(storage_fs=storage_fs)
path_handler = Path__Handler__Graph_Node(base_path='')
repository   = Graph__Repository(memory_fs=memory_fs, path_handler=path_handler)

# Initialize services
type_service = Type__Service(repository=repository)
node_service = Node__Service(repository=repository)

# Initialize default types
type_service.initialize_default_types()

Core Operations

Create an Issue

from issues_fs.schemas.graph.Schema__Node__Create__Request import Schema__Node__Create__Request

request = Schema__Node__Create__Request(
    node_type   = 'task',
    title       = 'Implement user authentication',
    description = 'Add OAuth2 support',
    status      = 'backlog',
    tags        = ['security', 'backend']
)

response = node_service.create_node(request)

if response.success:
    print(f"Created: {response.node.label}")  # Task-1

Load an Issue

from issues_fs.schemas.safe_str.Safe_Str__Graph_Types import Safe_Str__Node_Type, Safe_Str__Node_Label

node = repository.node_load(
    node_type = Safe_Str__Node_Type('task'),
    label     = Safe_Str__Node_Label('Task-1')
)

print(node.title)   # "Implement user authentication"
print(node.status)  # "backlog"

Find All Issues (Recursive)

# Find all issues, including nested ones
all_nodes = repository.nodes_list_all()

for info in all_nodes:
    print(f"{info.label} ({info.node_type}) at {info.path}")

# Filter by root path
project_nodes = repository.nodes_list_all(
    root_path=Safe_Str__File__Path('data/project/Project-1')
)

Load by Path

# Load issue by folder path
node = repository.node_load_by_path(
    Safe_Str__File__Path('data/project/Project-1/issues/Version-1/issues/Task-1')
)

# Find path for a label
path = repository.node_find_path_by_label(Safe_Str__Node_Label('Task-1'))

Update an Issue

from issues_fs.schemas.graph.Schema__Node__Update__Request import Schema__Node__Update__Request

request = Schema__Node__Update__Request(
    status = 'in-progress',
    tags   = ['security', 'backend', 'urgent']
)

response = node_service.update_node(
    node_type = Safe_Str__Node_Type('task'),
    label     = Safe_Str__Node_Label('Task-1'),
    request   = request
)

Delete an Issue

response = node_service.delete_node(
    node_type = Safe_Str__Node_Type('task'),
    label     = Safe_Str__Node_Label('Task-1')
)

MGraph-DB Integration

For efficient graph queries and visualization:

from issues_fs.mgraph.MGraph__Issues__Domain import MGraph__Issues__Domain

# Create sync service
from issues_fs.issues.graph_services.Graph__Repository__Factory import Graph__Repository__Factory

factory    = Graph__Repository__Factory(root_path='.issues')
repository = factory.create_repository()

# Query the graph
sync_service = MGraph__Issues__Sync__Service(
    repository   = repository,
    path_handler = path_handler
)

# Lazy load graph (syncs from filesystem)
graph = sync_service.ensure_loaded()

# Query by label
node = graph.get_node_by_label('Task-1')

# Get children
children = graph.get_children(node.node_id)

# Get ancestors (path to root)
ancestors = graph.get_ancestors(node.node_id)

# Force resync after external changes
sync_service.full_sync()

CLI Usage

The Issues-FS CLI provides command-line access to all operations:

# List all issues in the current repo
issues-fs list

# Create a new issue
issues-fs create --type task --title "Fix login bug"

# Show issue details
issues-fs show Task-1

# Update status
issues-fs update Task-1 --status in-progress

Install the CLI separately: pip install issues-fs-cli

Storage Structure

Issues-FS uses a simple, human-readable folder structure:

.issues/
├── config/
│   ├── node-types.json          # Issue type definitions
│   └── link-types.json          # Link type definitions
├── data/
│   └── {type}/
│       └── {Label}/
│           ├── issue.json       # Issue data
│           └── issues/          # Child issues
│               └── {Child-Label}/
│                   └── issue.json
└── indexes/
    └── issues.mgraph.json       # MGraph-DB cache

Example Structure

.issues/
├── data/
│   └── project/
│       └── Project-1/
│           ├── issue.json
│           └── issues/
│               ├── Version-1/
│               │   ├── issue.json
│               │   └── issues/
│               │       ├── Task-1/
│               │       │   └── issue.json
│               │       └── Bug-2/
│               │           └── issue.json
│               └── Version-2/
│                   └── issue.json

Issue JSON Schema

{
  "node_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "node_type": "task",
  "node_index": 1,
  "label": "Task-1",
  "title": "Implement user authentication",
  "description": "Add OAuth2 support for user login",
  "status": "in-progress",
  "created_at": 1706745600000,
  "updated_at": 1706832000000,
  "tags": ["security", "backend"],
  "links": [
    {
      "verb": "blocks",
      "target_label": "Task-2"
    }
  ],
  "properties": {
    "priority": "high",
    "estimate": "3d"
  }
}

Node Types

Default node types are created on initialization:

type_service.initialize_default_types()

Type	Display Name	Default Status
`git-repo`	Git Repo	active
`project`	Project	active
`version`	Version	planned
`task`	Task	backlog
`bug`	Bug	open
`feature`	Feature	backlog
`user-story`	User Story	backlog

Custom Types

from issues_fs.schemas.graph.Schema__Node__Type import Schema__Node__Type

custom_type = Schema__Node__Type(
    name           = 'epic',
    display_name   = 'Epic',
    color          = '#9B59B6',
    icon           = 'rocket',
    statuses       = ['draft', 'active', 'completed'],
    default_status = 'draft'
)

type_service.create_node_type(custom_type)

Architecture

┌──────────────────────────────────────────────────────────┐
│                       Services                           │
│      Node__Service  │  Type__Service  │  Link__Service   │
└───────────────────────────┬──────────────────────────────┘
                            │
┌───────────────────────────▼──────────────────────────────┐
│                   Graph__Repository                      │
│           (Data access layer with Type_Safe)             │
└───────────────────────────┬──────────────────────────────┘
                            │
┌───────────────────────────▼──────────────────────────────┐
│                       Memory-FS                          │
│    Storage_FS__Memory │ Storage_FS__Local_Disk │ S3 │ …  │
└──────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────┐
│                   MGraph Integration                     │
│ MGraph__Issues__Sync__Service  →  MGraph__Issues__Domain │
└──────────────────────────────────────────────────────────┘

Key Components

Component	Purpose
`Graph__Repository`	Data access layer for nodes, types, indexes
`Graph__Repository__Factory`	Factory for creating configured repository instances
`Node__Service`	Business logic for CRUD operations
`Type__Service`	Manage node and link type definitions
`Link__Service`	Manage links between issues
`Comments__Service`	Manage comments on issues
`MGraph__Issues__Sync__Service`	Syncs filesystem to MGraph-DB
`MGraph__Issues__Domain`	Graph operations and indexes
`Path__Handler__Graph_Node`	Generate filesystem paths for graph nodes
`Path__Handler__Issues`	Generate filesystem paths for issue operations

Module Structure

issues_fs/
├── issues/
│   ├── graph_services/      # Core services (Repository, Node, Type, Link, Comments)
│   ├── storage/             # Path handlers for filesystem operations
│   ├── phase_1/             # Root issue and children services
│   └── status/              # Issue status management
├── mgraph/                  # MGraph-DB integration (domain model, sync, schemas)
├── schemas/                 # Data models and type definitions
│   ├── graph/               # Graph node schemas (create, update, delete)
│   ├── issues/              # Issue-specific schemas
│   ├── identifiers/         # ID types and generators
│   ├── safe_str/            # Type-safe string primitives
│   ├── enums/               # Enumeration types
│   └── status/              # Status-related schemas
├── scripts/                 # Utility scripts
├── utils/                   # Version info and utilities
└── version/                 # Package version management

The Issues-FS Ecosystem

This library is the core of a broader ecosystem coordinated through Issues-FS__Dev, which includes a CLI, web service, documentation, and a team of 10 AI agent roles that collaborate through Issues-FS itself.

Repository Map

Core Libraries

Repository	Description
Issues-FS	This repo -- core Python library
Issues-FS__CLI	Command-line interface
Issues-FS__Docs	Architecture documents, design briefs, specifications

Services

Repository	Description
Issues-FS__Service	FastAPI web service
Issues-FS__Service__UI	Web UI
Issues-FS__Service__Client__Python	Python client for the service API

Development

Repository	Description
Issues-FS__Dev	Parent orchestration repo for all submodules

Agent Roles

Repository	Description
Issues-FS__Dev__Role__Dev	Dev agent -- implementation
Issues-FS__Dev__Role__Architect	Architect agent -- system design
Issues-FS__Dev__Role__QA	QA agent -- testing
Issues-FS__Dev__Role__AppSec	AppSec agent -- security
Issues-FS__Dev__Role__DevOps	DevOps agent -- CI/CD
Issues-FS__Dev__Role__Librarian	Librarian agent -- knowledge connectivity
Issues-FS__Dev__Role__Cartographer	Cartographer agent -- system mapping
Issues-FS__Dev__Role__Historian	Historian agent -- project narrative
Issues-FS__Dev__Role__Journalist	Journalist agent -- reporting
Issues-FS__Dev__Role__Conductor	Conductor agent -- orchestration

Human

Repository	Description
Issues-FS__Dev__Human__Dinis_Cruz	Stakeholder repo for Dinis Cruz

Current Status

Version: v0.4.5
Tests: 475+ test methods across 36 test files
Python: 3.12+
Status: Actively developed

Development

Setup

git clone https://github.com/owasp-sbot/Issues-FS.git
cd Issues-FS
pip install -e ".[dev]"

Run Tests

pytest

Code Style

This project follows the OSBot Python Formatting Guide:

Type_Safe inheritance on all classes
Safe_* primitives for type validation
@type_safe decorator on public methods
Aligned imports/parameters at column 70-80
Explicit is True / is False for booleans

Dependencies

Memory-FS -- Pluggable filesystem abstraction
MGraph-DB -- Graph database operations
OSBot-Utils -- Type_Safe utilities

Use Cases

Git-native issue tracking -- Store issues alongside code, branch/merge with PRs
Offline-first workflows -- Full functionality without network access
Custom integrations -- Simple JSON format for easy tooling
Hierarchical project management -- Organize epics > features > tasks > subtasks
Embedded issue tracking -- Add issue tracking to any Python application
AI agent collaboration -- Agents read and write issues as structured graph nodes

License

Apache License 2.0 -- see LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 66 Commits
.github/workflows		.github/workflows
.issues		.issues
issues_fs		issues_fs
scripts		scripts
tests/unit		tests/unit
to_refactor-in		to_refactor-in
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml
requirements-test.txt		requirements-test.txt

License

owasp-sbot/Issues-FS

Folders and files

Latest commit

History

Repository files navigation

Issues-FS

Key Features

Installation

Quick Start

Core Operations

Create an Issue

Load an Issue

Find All Issues (Recursive)

Load by Path

Update an Issue

Delete an Issue

MGraph-DB Integration

CLI Usage

Storage Structure

Example Structure

Issue JSON Schema

Node Types

Custom Types

Architecture

Key Components

Module Structure

The Issues-FS Ecosystem

Repository Map

Core Libraries

Services

Development

Agent Roles

Human

Current Status

Development

Setup

Run Tests

Code Style

Dependencies

Use Cases

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 3

Uh oh!

Languages

Packages