@fractary/core

Core SDK for Fractary - Primitive operations for work tracking, repository management, specifications, logging, file storage, and documentation.

Overview

@fractary/core provides foundational infrastructure for managing software development workflows across multiple platforms. It implements primitive operations that can be used standalone or as building blocks for higher-level frameworks like @fractary/faber.

Key Features

• Multi-Platform Work Tracking: Unified interface for GitHub Issues, Jira, and Linear
• Repository Management: Git operations with GitHub, GitLab, and Bitbucket integration
• Specification Management: Create, validate, and refine technical specifications
• Log Management: Capture, search, and archive session logs
• File Storage: Local and remote file operations with validation
• Documentation Management: Create, search, and export documentation
• Type-Safe: Full TypeScript support with comprehensive type definitions

Modules

Work Tracking

Manage work items across GitHub Issues, Jira, and Linear:

• Create, update, and fetch issues
• Manage comments, labels, and milestones
• Search and filter issues
• Track issue state and assignments

Supported Platforms:

• GitHub Issues (full support)
• Jira Cloud (full support)
• Linear (full support)

Repository Management

Git and platform operations:

• Branch management (create, delete, list)
• Commit operations with semantic versioning
• Pull request workflows
• Tag management
• Worktree support
• Multi-platform support (GitHub, GitLab, Bitbucket)

Supported Platforms:

• GitHub (full support)
• GitLab (full support)
• Bitbucket (full support)
• Local Git operations (full support)

Specification Management

Technical specification workflows:

• Create and validate specifications
• Template-based generation
• Refinement and versioning
• Specification search and indexing

Log Management

Session and operation logging:

• Capture session logs
• Search and filter logs
• Archive and export
• Log type classification

File Storage

File operations with validation:

• Read, write, list, delete operations
• Pattern matching and filtering
• Local and remote storage
• File validation and safety checks

Documentation Management

Documentation workflows:

• Create and update documentation
• Search and indexing
• Export to multiple formats
• Version tracking

Installation

npm install @fractary/core

Quick Start

import { WorkManager, RepoManager, SpecManager } from '@fractary/core';

// Work tracking
const workManager = new WorkManager({
  provider: 'github',
  config: {
    owner: 'myorg',
    repo: 'myrepo',
    token: process.env.GITHUB_TOKEN
  }
});

const issue = await workManager.createIssue({
  title: 'Add user authentication',
  body: 'Implement JWT-based authentication',
  workType: 'feature',
  labels: ['enhancement']
});

// Repository operations
const repoManager = new RepoManager({
  provider: 'github',
  config: {
    owner: 'myorg',
    repo: 'myrepo',
    token: process.env.GITHUB_TOKEN
  }
});

await repoManager.createBranch('feature/auth', { base: 'main' });

// Specification management
const specManager = new SpecManager({ specDirectory: './specs' });
const spec = specManager.createSpec('Authentication System', {
  workId: issue.number.toString(),
  template: 'feature'
});

Usage

Work Tracking

import { WorkManager } from '@fractary/core/work';

const workManager = new WorkManager({
  provider: 'github',
  config: {
    owner: 'myorg',
    repo: 'myrepo',
    token: process.env.GITHUB_TOKEN
  }
});

// Create an issue
const issue = await workManager.createIssue({
  title: 'Add new feature',
  body: 'Description of the feature',
  workType: 'feature',
  labels: ['enhancement'],
  assignees: ['developer1']
});

// Fetch an issue
const fetchedIssue = await workManager.fetchIssue(123);

// Search issues
const openBugs = await workManager.searchIssues('is:open label:bug');

// Add comment
await workManager.createComment(123, 'Working on this now');

// Manage labels
await workManager.addLabels(123, ['priority:high', 'needs-review']);

Repository Management

import { RepoManager } from '@fractary/core/repo';

const repoManager = new RepoManager({
  provider: 'github',
  config: {
    owner: 'myorg',
    repo: 'myrepo',
    token: process.env.GITHUB_TOKEN
  }
});

// Create a branch
await repoManager.createBranch('feature/new-feature', { base: 'main' });

// Make commits with semantic versioning
repoManager.commit({
  message: 'Add authentication middleware',
  type: 'feat',
  scope: 'auth',
  files: ['src/middleware/auth.ts']
});

// Create a pull request
const pr = await repoManager.createPR({
  title: 'Add new feature',
  body: 'PR description',
  head: 'feature/new-feature',
  base: 'main'
});

// Manage tags
repoManager.createTag('v1.0.0', { message: 'Release 1.0.0' });
repoManager.pushTag('v1.0.0');

Specification Management

import { SpecManager } from '@fractary/core/spec';

const specManager = new SpecManager({
  rootDir: './specs'
});

// Create a new spec
await specManager.createSpec({
  id: 'SPEC-001',
  title: 'Authentication System',
  template: 'technical'
});

Logging

import { LogsManager } from '@fractary/core/logs';

const logsManager = new LogsManager({
  logDir: './logs'
});

// Start a session
const sessionId = await logsManager.startSession({
  name: 'deployment',
  metadata: { version: '1.0.0' }
});

// Log events
await logsManager.log(sessionId, {
  level: 'info',
  message: 'Deployment started'
});

Module Exports

The package provides the following subpath exports:

• @fractary/core - All primitives
• @fractary/core/work - Work tracking only
• @fractary/core/repo - Repository management only
• @fractary/core/spec - Specification management only
• @fractary/core/logs - Logging only
• @fractary/core/file - File storage only
• @fractary/core/docs - Documentation only

TypeScript Support

This package is written in TypeScript and includes type definitions. TypeScript 5.0+ is recommended.

Requirements

• Node.js 18.0.0 or higher
• npm 9.0.0 or higher

License

MIT

Contributing

See the Contributing Guide for details on how to contribute to this project.

Configuration

Configuration can be provided via files or environment variables:

# .fractary/core.yaml
work:
  provider: github
  config:
    owner: myorg
    repo: myrepo
    token: ${GITHUB_TOKEN}

repo:
  provider: github
  config:
    owner: myorg
    repo: myrepo
    token: ${GITHUB_TOKEN}

See the Configuration Guide for details.

Documentation

• API Reference - Complete API documentation
• Configuration Guide - Configuration options
• Integration Guide - Integration patterns
• Examples - Usage examples and patterns

Related Packages

• @fractary/core-cli - Command-line interface
• @fractary/core-mcp - MCP server for AI agents

Links

• GitHub Repository
• Issue Tracker
• NPM Package