@ginkoai/cli 1.0.0 → 1.4.2

package/dist/lib/write-dispatcher/adapters/local-adapter.js

@@ -0,0 +1,324 @@
+/**
+ * @fileType: adapter
+ * @status: current
+ * @updated: 2025-11-02
+ * @tags: [write-adapter, local, filesystem, markdown, dual-write, adr-041]
+ * @related: [../write-dispatcher.ts, graph-adapter.ts, ../../packages/cli/src/core/session-log-manager.ts]
+ * @priority: high
+ * @complexity: low
+ * @dependencies: [fs-extra]
+ */
+import * as fs from 'fs-extra';
+import * as path from 'path';
+/**
+ * LocalAdapter
+ *
+ * Writes knowledge documents to local filesystem as Markdown files.
+ * Used during dual-write migration period for safety and rollback capability.
+ *
+ * Environment Variables:
+ * - GINKO_DUAL_WRITE: 'true' to enable local writes alongside graph writes
+ *
+ * File Structure:
+ * - ADR: .ginko/archive/ADR/ADR-{number}-{slug}.md
+ * - PRD: .ginko/archive/PRD/PRD-{number}-{slug}.md
+ * - Pattern: .ginko/archive/patterns/{slug}.md
+ * - Gotcha: .ginko/archive/gotchas/{slug}.md
+ * - LogEntry: .ginko/sessions/{user}/current-session-log.md (append)
+ *
+ * Usage:
+ * ```typescript
+ * const adapter = new LocalAdapter({
+ *   ginkoDir: '/path/to/.ginko'
+ * });
+ *
+ * dispatcher.registerAdapter(adapter);
+ * ```
+ */
+export class LocalAdapter {
+    name = 'local';
+    config;
+    constructor(config) {
+        this.config = {
+            ginkoDir: config.ginkoDir,
+            archiveDir: config.archiveDir || path.join(config.ginkoDir, 'archive'),
+        };
+    }
+    /**
+     * Check if adapter is enabled via environment variable
+     */
+    enabled() {
+        return process.env.GINKO_DUAL_WRITE === 'true';
+    }
+    /**
+     * Write knowledge document to local filesystem
+     */
+    async write(document) {
+        if (!this.enabled()) {
+            throw new Error('LocalAdapter is not enabled. Check GINKO_DUAL_WRITE environment variable.');
+        }
+        try {
+            const filePath = await this.writeDocument(document);
+            return {
+                source: 'local',
+                path: filePath,
+                timestamp: new Date().toISOString(),
+            };
+        }
+        catch (error) {
+            throw new Error(`LocalAdapter write failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Write document to appropriate location
+     */
+    async writeDocument(document) {
+        switch (document.type) {
+            case 'ADR':
+                return this.writeADR(document);
+            case 'PRD':
+                return this.writePRD(document);
+            case 'Pattern':
+                return this.writePattern(document);
+            case 'Gotcha':
+                return this.writeGotcha(document);
+            case 'ContextModule':
+                return this.writeContextModule(document);
+            case 'LogEntry':
+                return this.appendLogEntry(document);
+            case 'Session':
+                return this.writeSession(document);
+            case 'CodeFile':
+                return this.writeCodeFile(document);
+            default:
+                throw new Error(`Unsupported document type: ${document.type}`);
+        }
+    }
+    /**
+     * Write ADR to docs/adr/
+     */
+    async writeADR(document) {
+        const adrDir = path.join(process.cwd(), 'docs', 'adr');
+        await fs.ensureDir(adrDir);
+        const slug = this.slugify(document.title);
+        const number = document.data.number || this.extractNumber(document.id);
+        const filename = `ADR-${number.toString().padStart(3, '0')}-${slug}.md`;
+        const filePath = path.join(adrDir, filename);
+        const content = this.formatADR(document);
+        await fs.writeFile(filePath, content, 'utf-8');
+        return filePath;
+    }
+    /**
+     * Write PRD to docs/PRD/
+     */
+    async writePRD(document) {
+        const prdDir = path.join(process.cwd(), 'docs', 'PRD');
+        await fs.ensureDir(prdDir);
+        const slug = this.slugify(document.title);
+        const number = document.data.number || this.extractNumber(document.id);
+        const filename = `PRD-${number.toString().padStart(3, '0')}-${slug}.md`;
+        const filePath = path.join(prdDir, filename);
+        const content = this.formatPRD(document);
+        await fs.writeFile(filePath, content, 'utf-8');
+        return filePath;
+    }
+    /**
+     * Write Pattern to archive/patterns/
+     */
+    async writePattern(document) {
+        const patternsDir = path.join(this.config.archiveDir, 'patterns');
+        await fs.ensureDir(patternsDir);
+        const slug = this.slugify(document.title);
+        const filename = `${slug}.md`;
+        const filePath = path.join(patternsDir, filename);
+        const content = this.formatPattern(document);
+        await fs.writeFile(filePath, content, 'utf-8');
+        return filePath;
+    }
+    /**
+     * Write Gotcha to archive/gotchas/
+     */
+    async writeGotcha(document) {
+        const gotchasDir = path.join(this.config.archiveDir, 'gotchas');
+        await fs.ensureDir(gotchasDir);
+        const slug = this.slugify(document.title);
+        const filename = `${slug}.md`;
+        const filePath = path.join(gotchasDir, filename);
+        const content = this.formatGotcha(document);
+        await fs.writeFile(filePath, content, 'utf-8');
+        return filePath;
+    }
+    /**
+     * Write ContextModule to context/modules/
+     */
+    async writeContextModule(document) {
+        const modulesDir = path.join(this.config.ginkoDir, 'context', 'modules');
+        await fs.ensureDir(modulesDir);
+        const slug = this.slugify(document.title);
+        const filename = `${slug}.md`;
+        const filePath = path.join(modulesDir, filename);
+        const content = this.formatContextModule(document);
+        await fs.writeFile(filePath, content, 'utf-8');
+        return filePath;
+    }
+    /**
+     * Append LogEntry to session log
+     */
+    async appendLogEntry(document) {
+        const userEmail = document.metadata?.userEmail || 'unknown';
+        const userSlug = userEmail.replace('@', '-at-').replace(/\./g, '-');
+        const sessionDir = path.join(this.config.ginkoDir, 'sessions', userSlug);
+        const logPath = path.join(sessionDir, 'current-session-log.md');
+        await fs.ensureDir(sessionDir);
+        const entry = this.formatLogEntry(document);
+        await fs.appendFile(logPath, entry, 'utf-8');
+        return logPath;
+    }
+    /**
+     * Write Session to archive/
+     */
+    async writeSession(document) {
+        const sessionsDir = path.join(this.config.archiveDir, 'sessions');
+        await fs.ensureDir(sessionsDir);
+        const timestamp = document.metadata?.timestamp || new Date().toISOString();
+        const filename = `session-${timestamp.replace(/:/g, '-')}.md`;
+        const filePath = path.join(sessionsDir, filename);
+        await fs.writeFile(filePath, document.content, 'utf-8');
+        return filePath;
+    }
+    /**
+     * Write CodeFile to archive/code/
+     */
+    async writeCodeFile(document) {
+        const codeDir = path.join(this.config.archiveDir, 'code');
+        await fs.ensureDir(codeDir);
+        const slug = this.slugify(document.title);
+        const ext = document.metadata?.extension || '.txt';
+        const filename = `${slug}${ext}`;
+        const filePath = path.join(codeDir, filename);
+        await fs.writeFile(filePath, document.content, 'utf-8');
+        return filePath;
+    }
+    /**
+     * Format ADR markdown with frontmatter
+     */
+    formatADR(document) {
+        const frontmatter = this.buildFrontmatter({
+            status: document.metadata?.status || 'proposed',
+            date: document.metadata?.date || new Date().toISOString().split('T')[0],
+            tags: document.metadata?.tags || [],
+            ...document.data,
+        });
+        return `---\n${frontmatter}---\n\n${document.content}`;
+    }
+    /**
+     * Format PRD markdown with frontmatter
+     */
+    formatPRD(document) {
+        const frontmatter = this.buildFrontmatter({
+            status: document.metadata?.status || 'draft',
+            date: document.metadata?.date || new Date().toISOString().split('T')[0],
+            tags: document.metadata?.tags || [],
+            ...document.data,
+        });
+        return `---\n${frontmatter}---\n\n${document.content}`;
+    }
+    /**
+     * Format Pattern markdown
+     */
+    formatPattern(document) {
+        const frontmatter = this.buildFrontmatter({
+            category: document.metadata?.category || 'pattern',
+            tags: document.metadata?.tags || [],
+            ...document.data,
+        });
+        return `---\n${frontmatter}---\n\n${document.content}`;
+    }
+    /**
+     * Format Gotcha markdown
+     */
+    formatGotcha(document) {
+        const frontmatter = this.buildFrontmatter({
+            category: document.metadata?.category || 'gotcha',
+            impact: document.metadata?.impact || 'medium',
+            tags: document.metadata?.tags || [],
+            ...document.data,
+        });
+        return `---\n${frontmatter}---\n\n${document.content}`;
+    }
+    /**
+     * Format ContextModule markdown
+     */
+    formatContextModule(document) {
+        const frontmatter = this.buildFrontmatter({
+            type: 'context-module',
+            tags: document.metadata?.tags || [],
+            ...document.data,
+        });
+        return `---\n${frontmatter}---\n\n${document.content}`;
+    }
+    /**
+     * Format log entry for appending
+     */
+    formatLogEntry(document) {
+        const timestamp = document.metadata?.timestamp
+            ? new Date(document.metadata.timestamp).toLocaleTimeString('en-US', { hour12: false, hour: '2-digit', minute: '2-digit' })
+            : new Date().toLocaleTimeString('en-US', { hour12: false, hour: '2-digit', minute: '2-digit' });
+        const category = document.metadata?.category || 'feature';
+        const impact = document.metadata?.impact || 'medium';
+        const files = document.metadata?.files || [];
+        let entry = `\n### ${timestamp} - [${category}]\n`;
+        entry += `${document.content}\n`;
+        if (files.length > 0) {
+            entry += `Files: ${files.join(', ')}\n`;
+        }
+        entry += `Impact: ${impact}\n`;
+        return entry;
+    }
+    /**
+     * Build YAML frontmatter from object
+     */
+    buildFrontmatter(data) {
+        let frontmatter = '';
+        for (const [key, value] of Object.entries(data)) {
+            if (value === undefined || value === null)
+                continue;
+            if (Array.isArray(value)) {
+                if (value.length > 0) {
+                    frontmatter += `${key}:\n${value.map(v => `  - ${v}`).join('\n')}\n`;
+                }
+            }
+            else if (typeof value === 'object') {
+                frontmatter += `${key}: ${JSON.stringify(value)}\n`;
+            }
+            else {
+                frontmatter += `${key}: ${value}\n`;
+            }
+        }
+        return frontmatter;
+    }
+    /**
+     * Slugify a string for filename
+     */
+    slugify(text) {
+        return text
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-|-$/g, '')
+            .substring(0, 60);
+    }
+    /**
+     * Extract number from ID (e.g., 'adr_042' -> 42)
+     */
+    extractNumber(id) {
+        const match = id.match(/\d+/);
+        return match ? parseInt(match[0], 10) : Date.now();
+    }
+}
+/**
+ * Create LocalAdapter from environment and Ginko directory
+ */
+export async function createLocalAdapterFromEnv(ginkoDir) {
+    return new LocalAdapter({ ginkoDir });
+}
+//# sourceMappingURL=local-adapter.js.map

package/dist/lib/write-dispatcher/adapters/local-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-adapter.js","sourceRoot":"","sources":["../../../../src/lib/write-dispatcher/adapters/local-adapter.ts"],"names":[],"mappings":"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"}

package/dist/lib/write-dispatcher/write-dispatcher.d.ts

@@ -0,0 +1,151 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2025-11-02
+ * @tags: [write-dispatch, adapter-pattern, multi-backend, adr-041]
+ * @related: [adapters/graph-adapter.ts, adapters/local-adapter.ts, api/v1/graph/_cloud-graph-client.ts]
+ * @priority: critical
+ * @complexity: medium
+ * @dependencies: []
+ */
+/**
+ * Knowledge document types supported
+ */
+export type KnowledgeDocumentType = 'ADR' | 'PRD' | 'Pattern' | 'Gotcha' | 'Session' | 'CodeFile' | 'ContextModule' | 'LogEntry';
+/**
+ * Knowledge document structure
+ */
+export interface KnowledgeDocument {
+    type: KnowledgeDocumentType;
+    id: string;
+    title: string;
+    content: string;
+    data: Record<string, any>;
+    metadata?: {
+        tags?: string[];
+        status?: string;
+        category?: string;
+        impact?: string;
+        files?: string[];
+        timestamp?: string;
+        [key: string]: any;
+    };
+}
+/**
+ * Write operation result
+ */
+export interface WriteResult {
+    source: string;
+    id?: string;
+    path?: string;
+    error?: string;
+    timestamp: string;
+}
+/**
+ * Write adapter interface
+ * All write destinations implement this interface
+ */
+export interface WriteAdapter {
+    name: string;
+    enabled(): boolean;
+    write(document: KnowledgeDocument): Promise<WriteResult>;
+}
+/**
+ * WriteDispatcher Configuration
+ */
+export interface WriteDispatcherConfig {
+    primaryAdapter: string;
+    enabledAdapters?: string[];
+    dualWrite?: boolean;
+    failFast?: boolean;
+}
+/**
+ * WriteDispatcher
+ *
+ * Routes write operations to multiple backends using the adapter pattern.
+ * Supports dual-write migration strategy and graceful fallback.
+ *
+ * Architecture (ADR-041):
+ * - Primary adapter (graph) must succeed for write to be considered successful
+ * - Secondary adapters (local) run concurrently for dual-write period
+ * - Environment variables control which adapters are enabled
+ * - Single source of truth: graph for reads, dispatched writes
+ *
+ * Usage:
+ * ```typescript
+ * const dispatcher = new WriteDispatcher({ primaryAdapter: 'graph' });
+ * dispatcher.registerAdapter(new GraphAdapter());
+ * dispatcher.registerAdapter(new LocalAdapter());
+ *
+ * const result = await dispatcher.dispatch({
+ *   type: 'ADR',
+ *   id: 'adr_042',
+ *   title: 'Use JWT',
+ *   content: '# ADR-042...',
+ *   data: { status: 'proposed' }
+ * });
+ * ```
+ */
+export declare class WriteDispatcher {
+    private adapters;
+    private config;
+    constructor(config: WriteDispatcherConfig);
+    /**
+     * Register a write adapter
+     */
+    registerAdapter(adapter: WriteAdapter): void;
+    /**
+     * Unregister an adapter
+     */
+    unregisterAdapter(name: string): void;
+    /**
+     * Get list of registered adapters
+     */
+    getAdapters(): string[];
+    /**
+     * Get enabled adapters based on configuration
+     */
+    private getEnabledAdapters;
+    /**
+     * Dispatch write operation to all enabled adapters
+     *
+     * Strategy:
+     * 1. Execute all enabled adapters concurrently
+     * 2. Wait for primary adapter to complete
+     * 3. If primary fails, throw error (fail fast)
+     * 4. If primary succeeds, return its result
+     * 5. Secondary adapter failures are logged but don't block
+     *
+     * @throws Error if primary adapter fails
+     */
+    dispatch(document: KnowledgeDocument): Promise<WriteResult>;
+    /**
+     * Validate configuration and adapters
+     */
+    validate(): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Get dispatcher status
+     */
+    getStatus(): {
+        primaryAdapter: string;
+        registeredAdapters: string[];
+        enabledAdapters: string[];
+        dualWrite: boolean;
+    };
+}
+/**
+ * Initialize global dispatcher
+ */
+export declare function initializeDispatcher(config: WriteDispatcherConfig): WriteDispatcher;
+/**
+ * Get global dispatcher instance
+ */
+export declare function getDispatcher(): WriteDispatcher;
+/**
+ * Check if dispatcher is initialized
+ */
+export declare function isDispatcherInitialized(): boolean;
+//# sourceMappingURL=write-dispatcher.d.ts.map

package/dist/lib/write-dispatcher/write-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-dispatcher.d.ts","sourceRoot":"","sources":["../../../src/lib/write-dispatcher/write-dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAC7B,KAAK,GACL,KAAK,GACL,SAAS,GACT,QAAQ,GACR,SAAS,GACT,UAAU,GACV,eAAe,GACf,UAAU,CAAC;AAEf;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC1B,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KACpB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,IAAI,OAAO,CAAC;IACnB,KAAK,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAC1D;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAwC;IACxD,OAAO,CAAC,MAAM,CAAkC;gBAEpC,MAAM,EAAE,qBAAqB;IASzC;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAI5C;;OAEG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIrC;;OAEG;IACH,WAAW,IAAI,MAAM,EAAE;IAIvB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAgB1B;;;;;;;;;;;OAWG;IACG,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IAsDjE;;OAEG;IACH,QAAQ,IAAI;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE;IA0BhD;;OAEG;IACH,SAAS,IAAI;QACX,cAAc,EAAE,MAAM,CAAC;QACvB,kBAAkB,EAAE,MAAM,EAAE,CAAC;QAC7B,eAAe,EAAE,MAAM,EAAE,CAAC;QAC1B,SAAS,EAAE,OAAO,CAAC;KACpB;CAUF;AAOD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAGnF;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,eAAe,CAK/C;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAEjD"}