@fractary/core 0.1.0 → 0.1.1

package/README.md

@@ -1,39 +1,92 @@
 # @fractary/core
 
-Fractary Core SDK - Primitive operations for work tracking, repository management, specifications, logging, file storage, and documentation.
+Core SDK for Fractary - Primitive operations for work tracking, repository management, specifications, logging, file storage, and documentation.
 
-> **⚠️ Alpha Release (v0.1.0)** - This is an early-stage release with limited platform support. Only GitHub is fully implemented. Other providers (Bitbucket, GitLab, Jira, Linear) are included as stubs for future compatibility but will throw errors if used.
+[![npm version](https://img.shields.io/npm/v/@fractary/core.svg)](https://www.npmjs.com/package/@fractary/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Overview
 
-`@fractary/core` provides foundational SDKs for common development operations across multiple platforms and services. This package is designed to be used by higher-level frameworks like `@fractary/faber` and can also be used standalone for building custom workflows.
+`@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`.
 
-## Features
+### 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
-Unified interface for work item management:
-- ✅ **GitHub Issues** - Fully implemented
-- ⚠️ **Jira Cloud** - Stub only (not functional)
-- ⚠️ **Linear** - Stub only (not functional)
+
+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 repository operations:
-- ✅ **GitHub** - Fully implemented
-- ⚠️ **GitLab** - Stub only (not functional)
-- ⚠️ **Bitbucket** - Stub only (not functional)
-- ✅ **Local Git operations** - Fully implemented
+
+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
-Create and manage technical specifications with templates and validation.
 
-### Logging
-Structured logging and session capture for workflow tracking.
+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 support for local and cloud storage backends.
 
-### Documentation
-Documentation generation and management utilities.
+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
 
@@ -41,6 +94,48 @@ Documentation generation and management utilities.
 npm install @fractary/core
 ```
 
+## Quick Start
+
+```typescript
+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
@@ -49,7 +144,7 @@ npm install @fractary/core
 import { WorkManager } from '@fractary/core/work';
 
 const workManager = new WorkManager({
-  platform: 'github',
+  provider: 'github',
   config: {
     owner: 'myorg',
     repo: 'myrepo',
@@ -60,9 +155,23 @@ const workManager = new WorkManager({
 // Create an issue
 const issue = await workManager.createIssue({
   title: 'Add new feature',
-  description: 'Description of the feature',
-  labels: ['enhancement']
+  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
@@ -71,7 +180,7 @@ const issue = await workManager.createIssue({
 import { RepoManager } from '@fractary/core/repo';
 
 const repoManager = new RepoManager({
-  platform: 'github',
+  provider: 'github',
   config: {
     owner: 'myorg',
     repo: 'myrepo',
@@ -80,18 +189,27 @@ const repoManager = new RepoManager({
 });
 
 // Create a branch
-await repoManager.createBranch({
-  name: 'feature/new-feature',
-  from: 'main'
+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.createPullRequest({
+const pr = await repoManager.createPR({
   title: 'Add new feature',
+  body: 'PR description',
   head: 'feature/new-feature',
-  base: 'main',
-  body: 'PR description'
+  base: 'main'
 });
+
+// Manage tags
+repoManager.createTag('v1.0.0', { message: 'Release 1.0.0' });
+repoManager.pushTag('v1.0.0');
 ```
 
 ### Specification Management
@@ -162,8 +280,43 @@ MIT
 
 See the [Contributing Guide](../../CONTRIBUTING.md) for details on how to contribute to this project.
 
+## Configuration
+
+Configuration can be provided via files or environment variables:
+
+```yaml
+# .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](../../docs/guides/configuration.md) for details.
+
+## Documentation
+
+- **[API Reference](../../docs/guides/api-reference.md)** - Complete API documentation
+- **[Configuration Guide](../../docs/guides/configuration.md)** - Configuration options
+- **[Integration Guide](../../docs/guides/integration.md)** - Integration patterns
+- **[Examples](../../docs/examples/)** - Usage examples and patterns
+
+## Related Packages
+
+- **[@fractary/core-cli](../../../cli/)** - Command-line interface
+- **[@fractary/core-mcp](../../../mcp/server/)** - MCP server for AI agents
+
 ## Links
 
 - [GitHub Repository](https://github.com/fractary/core)
-- [Documentation](https://docs.fractary.com/core)
 - [Issue Tracker](https://github.com/fractary/core/issues)
+- [NPM Package](https://www.npmjs.com/package/@fractary/core)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fractary/core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Fractary Core SDK - Primitive operations for work tracking, repository management, specifications, logging, file storage, and documentation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",