@fractary/codex 0.12.16 → 0.12.18

package/README.md

@@ -11,83 +11,250 @@ JavaScript/TypeScript SDK for Fractary Codex - knowledge infrastructure for AI a
 npm install @fractary/codex
 ```
 
-## Features
+## Quick Start
 
-- **Universal References**: `codex://` URI scheme for cross-project knowledge references
-- **Multi-Provider Storage**: Local filesystem, GitHub, HTTP, and S3 storage backends
-- **Intelligent Caching**: Multi-tier caching with LRU eviction
-- **File Synchronization**: Bidirectional sync with conflict detection
-- **MCP Integration**: Model Context Protocol server for AI agents
-- **Permission System**: Fine-grained access control
-- **Type-Safe**: Full TypeScript support
+### Using CodexClient (recommended)
 
-## Quick Start
+```typescript
+import { CodexClient } from '@fractary/codex'
+
+// Create client from project config (.fractary/config.yaml)
+const client = await CodexClient.create()
+
+// Fetch a document
+const result = await client.fetch('codex://myorg/project/docs/api.md')
+console.log(result.content.toString())
+
+// Fetch with options
+const fresh = await client.fetch('codex://myorg/project/docs/api.md', {
+  bypassCache: true,
+  ttl: 3600
+})
+
+// Cache management
+const stats = await client.getCacheStats()
+await client.invalidateCache('codex://myorg/*')
+
+// Health checks
+const checks = await client.getHealthChecks()
+```
+
+### Using individual modules
 
 ```typescript
-import { parseReference, CacheManager, StorageManager } from '@fractary/codex'
+import {
+  parseReference,
+  buildUri,
+  isValidUri,
+  CacheManager,
+  StorageManager,
+  TypeRegistry
+} from '@fractary/codex'
 
-// Parse a codex URI
-const ref = parseReference('codex://myorg/docs/api-guide.md')
+// Parse a codex:// URI
+const ref = parseReference('codex://myorg/project/docs/api.md')
+// { org: 'myorg', project: 'project', path: 'docs/api.md' }
 
-// Create managers
-const storage = StorageManager.create()
-const cache = CacheManager.create({ cacheDir: '.fractary/codex/cache' })
-cache.setStorageManager(storage)
+// Build a URI
+const uri = buildUri('myorg', 'project', 'docs/api.md')
+// 'codex://myorg/project/docs/api.md'
 
-// Fetch content with caching
-const content = await cache.get('codex://myorg/docs/api-guide.md')
+// Validate
+isValidUri('codex://myorg/project/docs/api.md') // true
 ```
 
-## Documentation
+## API Reference
 
-**Full documentation**: [docs/sdk/js/](../../docs/sdk/js/)
+### CodexClient
 
-- [API Reference](../../docs/sdk/js/#api-reference)
-- [Authentication](../../docs/sdk/js/#authentication)
-- [Troubleshooting](../../docs/sdk/js/#troubleshooting)
-- [Configuration Guide](../../docs/configuration.md)
+High-level facade for all codex operations.
 
-## Development
+```typescript
+interface CodexClientOptions {
+  configPath?: string        // Path to .fractary/config.yaml
+  cacheDir?: string          // Override cache directory
+  organizationSlug?: string  // Override organization
+}
 
-```bash
-# Install dependencies
-npm install
+const client = await CodexClient.create(options?)
 
-# Build the package
-npm run build
+// Document operations
+client.fetch(uri, options?)           // Fetch document by URI
+client.invalidateCache(pattern?)      // Invalidate cache entries
+client.invalidateCachePattern(regex)  // Invalidate by regex
 
-# Run tests
-npm test
+// Cache
+client.getCacheStats()                // Get cache statistics
+client.listCacheEntries(options?)     // List cached entries
 
-# Type check
-npm run typecheck
+// Health
+client.getHealthChecks()              // Run health diagnostics
 
-# Lint
-npm run lint
+// Accessors
+client.getTypeRegistry()              // Get type registry
+client.getCacheManager()              // Get cache manager
+client.getStorageManager()            // Get storage manager
+client.getOrganization()              // Get organization slug
 ```
 
-## Publishing
+### References
 
-```bash
-# Build and test
-npm run build && npm test
+Parse, build, validate, and resolve `codex://` URIs.
+
+```typescript
+// Parsing and building
+parseReference(uri: string): ParsedReference
+buildUri(org: string, project: string, path: string): string
+isValidUri(uri: string): boolean
+validateUri(uri: string): boolean
 
-# Bump version
-npm version patch  # or minor/major
+// Resolution (adds filesystem paths, cache paths)
+resolveReference(uri: string, options?): ResolvedReference
+resolveReferences(uris: string[], options?): ResolvedReference[]
 
-# Push with tags
-git push && git push --tags
+// Utilities
+getExtension(uri: string): string
+getFilename(uri: string): string
+getDirectory(uri: string): string
+isCurrentProjectUri(uri: string): boolean
 
-# Publish
-npm publish
+// Legacy format support
+isLegacyReference(ref: string): boolean
+convertLegacyReference(ref: string): string
 ```
 
-## License
+### StorageManager
+
+Multi-provider storage with priority-based fallback.
+
+```typescript
+// Built-in providers
+LocalStorage      // Filesystem
+GitHubStorage     // GitHub repositories (needs GITHUB_TOKEN for private repos)
+HttpStorage       // HTTP/HTTPS endpoints
+FilePluginStorage // File plugin integration
+
+// Manager
+const manager = StorageManager.create(config)
+const result = await manager.fetch(ref, options?)
+// result: { content: Buffer, contentType?: string, size: number }
+```
+
+### CacheManager
+
+TTL-based caching with disk persistence.
+
+```typescript
+const cache = CacheManager.create(config)
+
+await cache.get(ref, options?)        // Get from cache (or fetch)
+await cache.set(uri, result)          // Store in cache
+await cache.clear()                   // Clear all entries
+await cache.invalidate(pattern)       // Invalidate by glob
+await cache.invalidatePattern(regex)  // Invalidate by regex
+await cache.getStats()                // Cache statistics
+await cache.listEntries(options?)     // List entries with filtering
+```
+
+### TypeRegistry
+
+Maps file paths to artifact types with TTL defaults.
+
+```typescript
+const registry = TypeRegistry.create()
+
+registry.detectType('docs/api.md')    // 'docs'
+registry.getTtl('docs/api.md')        // 86400 (1 day)
+registry.register(customTypeConfig)   // Add custom type
+registry.list()                       // List all types
+```
+
+**Built-in types:**
+
+| Type | Patterns | Default TTL |
+|------|----------|-------------|
+| `docs` | `docs/**`, `**/*.md` | 1 day |
+| `specs` | `specs/**`, `**/SPEC-*.md` | 7 days |
+| `config` | `**/*.yaml`, `**/*.json` | 1 hour |
+| `logs` | `logs/**`, `**/*.log` | 1 hour |
+| `schemas` | `schemas/**`, `**/*.schema.json` | 7 days |
 
-MIT - see [LICENSE](LICENSE)
+### SyncManager
 
-## See Also
+Bidirectional file synchronization.
+
+```typescript
+const sync = SyncManager.create(config)
+
+const plan = await sync.createPlan(org, project, targetDir, patterns)
+// plan: { direction, operations[], stats, conflicts[] }
+
+const result = await sync.executePlan(plan, options?)
+```
+
+### PermissionManager
+
+Fine-grained access control.
+
+```typescript
+const permissions = PermissionManager.create(config)
+
+permissions.isAllowed(context)        // Check if action allowed
+permissions.hasPermission(context, level) // Check permission level
+
+// Permission levels: none < read < write < admin
+// Actions: fetch, cache, sync, invalidate, manage
+```
+
+### ConfigManager
+
+Configuration management (used by CLI internally).
+
+```typescript
+const result = await ConfigManager.init(options)   // Initialize config
+const result = await ConfigManager.update(options)  // Update config
+const result = await ConfigManager.validate(options) // Validate config
+```
+
+### HealthChecker
+
+```typescript
+const checker = HealthChecker.create(options)
+const results = await checker.runAll()
+// Checks: config, storage, client, cache, type registry
+```
+
+### Errors
+
+```typescript
+import {
+  CodexError, ConfigurationError, ValidationError, PermissionDeniedError
+} from '@fractary/codex'
+
+try {
+  await client.fetch(uri)
+} catch (err) {
+  // PermissionDeniedError extends Error directly, not CodexError - check it first
+  if (err instanceof PermissionDeniedError) { /* access denied */ }
+  if (err instanceof ConfigurationError) { /* config issue */ }
+  if (err instanceof ValidationError) { /* validation issue */ }
+  if (err instanceof CodexError) { /* other SDK error */ }
+}
+```
+
+## Configuration
+
+The SDK reads from `.fractary/config.yaml`. See the [Configuration Guide](../../docs/configuration.md).
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+npm run typecheck
+```
+
+## License
 
-- [Python SDK](../py/) - `fractary-codex` on PyPI
-- [CLI](../../cli/) - Command-line interface
-- [MCP Server](../../mcp/server/) - AI agent integration
+MIT