From 00cced250d39bc0573895e452c2794d4b71c2531 Mon Sep 17 00:00:00 2001 From: David Snelling Date: Sat, 1 Nov 2025 11:55:47 -0700 Subject: [PATCH] feat: add COW infrastructure exports and augmentation helpers for v5.0.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Enables premium augmentations to implement temporal features by: 1. Export COW infrastructure types from index.ts: - CommitLog, CommitObject, CommitBuilder - BlobStorage, RefManager, TreeObject 2. Add 4 helper methods to BaseAugmentation: - getCommitLog() - Access commit history - getBlobStorage() - Access content-addressable storage - getRefManager() - Branch/ref management - getCurrentBranch() - Current branch helper All methods have clear error messages if COW not initialized. Zero premium feature mentions - completely clean open source. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- src/augmentations/brainyAugmentation.ts | 158 ++++++++++++++++++++++++ src/index.ts | 18 +++ 2 files changed, 176 insertions(+) diff --git a/src/augmentations/brainyAugmentation.ts b/src/augmentations/brainyAugmentation.ts index 809fff2c..38232524 100644 --- a/src/augmentations/brainyAugmentation.ts +++ b/src/augmentations/brainyAugmentation.ts @@ -373,6 +373,164 @@ export abstract class BaseAugmentation implements BrainyAugmentation { this.context.log(`[${this.name}] ${message}`, level) } } + + /** + * Get CommitLog for temporal features (v5.0.0+) + * + * Provides access to commit history for time-travel queries, audit trails, + * and branch management. Available after initialize() is called. + * + * @returns CommitLog instance + * @throws Error if called before initialize() or if COW not enabled + * + * @example + * ```typescript + * protected async onInitialize() { + * const commitLog = this.getCommitLog() + * const history = await commitLog.getHistory('heads/main', { maxCount: 10 }) + * } + * ``` + */ + protected getCommitLog(): any { + if (!this.context) { + throw new Error( + `${this.name}: Cannot access CommitLog before initialize(). ` + + `CommitLog is only available after the augmentation has been initialized.` + ) + } + + const storage = this.context.storage as any + + if (!storage.commitLog) { + throw new Error( + `${this.name}: CommitLog not available. ` + + `COW (Copy-on-Write) is not enabled on this storage adapter. ` + + `Requires BaseStorage with initializeCOW() called. ` + + `This is expected if using a non-COW storage adapter.` + ) + } + + return storage.commitLog + } + + /** + * Get BlobStorage for content-addressable storage (v5.0.0+) + * + * Provides access to the underlying blob storage system for storing + * and retrieving content-addressed data. Available after initialize() is called. + * + * @returns BlobStorage instance + * @throws Error if called before initialize() or if COW not enabled + * + * @example + * ```typescript + * protected async onInitialize() { + * const blobStorage = this.getBlobStorage() + * const hash = await blobStorage.writeBlob(Buffer.from('data')) + * const data = await blobStorage.readBlob(hash) + * } + * ``` + */ + protected getBlobStorage(): any { + if (!this.context) { + throw new Error( + `${this.name}: Cannot access BlobStorage before initialize(). ` + + `BlobStorage is only available after the augmentation has been initialized.` + ) + } + + const storage = this.context.storage as any + + if (!storage.blobStorage) { + throw new Error( + `${this.name}: BlobStorage not available. ` + + `COW (Copy-on-Write) is not enabled on this storage adapter. ` + + `Requires BaseStorage with initializeCOW() called. ` + + `This is expected if using a non-COW storage adapter.` + ) + } + + return storage.blobStorage + } + + /** + * Get RefManager for branch/ref management (v5.0.0+) + * + * Provides access to the reference manager for creating, updating, + * and managing Git-style branches and refs. Available after initialize() is called. + * + * @returns RefManager instance + * @throws Error if called before initialize() or if COW not enabled + * + * @example + * ```typescript + * protected async onInitialize() { + * const refManager = this.getRefManager() + * await refManager.setRef('heads/experiment', commitHash, { + * author: 'system', + * message: 'Create experiment branch' + * }) + * } + * ``` + */ + protected getRefManager(): any { + if (!this.context) { + throw new Error( + `${this.name}: Cannot access RefManager before initialize(). ` + + `RefManager is only available after the augmentation has been initialized.` + ) + } + + const storage = this.context.storage as any + + if (!storage.refManager) { + throw new Error( + `${this.name}: RefManager not available. ` + + `COW (Copy-on-Write) is not enabled on this storage adapter. ` + + `Requires BaseStorage with initializeCOW() called. ` + + `This is expected if using a non-COW storage adapter.` + ) + } + + return storage.refManager + } + + /** + * Get current branch name (v5.0.0+) + * + * Convenience helper for getting the current branch from the Brainy instance. + * Available after initialize() is called. + * + * @returns Current branch name (e.g., 'main') + * @throws Error if called before initialize() + * + * @example + * ```typescript + * protected async onInitialize() { + * const branch = await this.getCurrentBranch() + * console.log(`Current branch: ${branch}`) + * } + * ``` + */ + protected async getCurrentBranch(): Promise { + if (!this.context) { + throw new Error( + `${this.name}: Cannot access Brainy instance before initialize(). ` + + `getCurrentBranch() is only available after the augmentation has been initialized.` + ) + } + + const brain = this.context.brain as any + + if (typeof brain.getCurrentBranch !== 'function') { + throw new Error( + `${this.name}: getCurrentBranch() not available on Brainy instance. ` + + `This method requires Brainy v5.0.0+.` + ) + } + + return brain.getCurrentBranch() + } } /** diff --git a/src/index.ts b/src/index.ts index 86d72951..0f4d2e1d 100644 --- a/src/index.ts +++ b/src/index.ts @@ -203,6 +203,24 @@ export { // FileSystemStorage is exported separately to avoid browser build issues export { FileSystemStorage } from './storage/adapters/fileSystemStorage.js' +// Export COW (Copy-on-Write) infrastructure for v5.0.0 +// Enables premium augmentations to implement temporal features +import { CommitLog } from './storage/cow/CommitLog.js' +import { CommitObject, CommitBuilder } from './storage/cow/CommitObject.js' +import { BlobStorage } from './storage/cow/BlobStorage.js' +import { RefManager } from './storage/cow/RefManager.js' +import { TreeObject } from './storage/cow/TreeObject.js' + +export { + // COW infrastructure + CommitLog, + CommitObject, + CommitBuilder, + BlobStorage, + RefManager, + TreeObject +} + // Export unified pipeline import { Pipeline,