crewly 1.8.9 → 1.8.11

package/dist/cli/backend/src/services/ai/prompt-modules/prompt-module.interface.js

@@ -0,0 +1,37 @@
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Load a role-specific fragment file from config/roles/{role}/fragments/{fragmentName}.md.
+ * Returns null if the file doesn't exist.
+ *
+ * @param projectRoot - Project root path (where config/ lives)
+ * @param role - Agent role (e.g. 'orchestrator')
+ * @param fragmentName - Fragment file name without .md extension
+ * @returns Fragment content string or null
+ */
+export function loadRoleFragment(projectRoot, role, fragmentName) {
+    try {
+        const fragmentPath = path.join(projectRoot, 'config', 'roles', role, 'fragments', `${fragmentName}.md`);
+        if (fs.existsSync(fragmentPath)) {
+            return fs.readFileSync(fragmentPath, 'utf-8');
+        }
+    }
+    catch {
+        // Fragment not found — fall back to inline content
+    }
+    return null;
+}
+/**
+ * Estimate token count from a string.
+ * Uses the rough heuristic of ~4 characters per token (suitable for English/code mix).
+ *
+ * @param text - Text to estimate tokens for
+ * @returns Estimated token count
+ */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    // ~4 chars per token is a reasonable estimate for English + code
+    return Math.ceil(text.length / 4);
+}
+//# sourceMappingURL=prompt-module.interface.js.map

package/dist/cli/backend/src/services/ai/prompt-modules/prompt-module.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-module.interface.js","sourceRoot":"","sources":["../../../../../../../backend/src/services/ai/prompt-modules/prompt-module.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAyM7B;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAC/B,WAAmB,EACnB,IAAY,EACZ,YAAoB;IAEpB,IAAI,CAAC;QACJ,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC;QACxG,IAAI,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YACjC,OAAO,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QAC/C,CAAC;IACF,CAAC;IAAC,MAAM,CAAC;QACR,mDAAmD;IACpD,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IAC1C,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC;IACpB,iEAAiE;IACjE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACnC,CAAC"}

package/dist/cli/backend/src/services/knowledge/fts5-search-strategy.d.ts

@@ -0,0 +1,56 @@
+/**
+ * FTS5 Search Strategy
+ *
+ * Implements the KnowledgeSearchStrategy interface using the SQLite FTS5
+ * full-text search index. Maps FTS5 BM25-ranked results to the existing
+ * ScoredDocument format used by KnowledgeSearchService.
+ *
+ * @module services/knowledge/fts5-search-strategy
+ */
+import type { KnowledgeSearchStrategy, ScoredDocument } from './knowledge-search.service.js';
+import type { KnowledgeDocumentSummary } from '../../types/knowledge.types.js';
+import { WikiCompilerService } from './wiki-compiler.service.js';
+/**
+ * FTS5-based search strategy for the Wiki-First Knowledge System.
+ *
+ * This strategy provides pure full-text search via SQLite FTS5 with BM25 ranking.
+ *
+ * Note on semantic fallback (design doc Section 10): The 10% semantic fallback
+ * weight is achieved at the MemoryService level, which runs both FTS5 knowledge
+ * search AND vector-based semantic search in parallel. This strategy intentionally
+ * does not mix semantic results — that composition happens upstream in the recall
+ * pipeline (MemoryService.recall -> searchKnowledgeDocuments + semanticSearch).
+ *
+ * Uses SQLite FTS5 MATCH with BM25 ranking for fast, zero-cost retrieval.
+ * Results are mapped back to the KnowledgeDocumentSummary objects provided
+ * by the caller, falling back to minimal summaries when a document is found
+ * in the FTS5 index but not in the provided documents array.
+ *
+ * @example
+ * ```typescript
+ * const strategy = new Fts5SearchStrategy(wikiCompiler);
+ * const results = await strategy.search('deployment guide', documents);
+ * ```
+ */
+export declare class Fts5SearchStrategy implements KnowledgeSearchStrategy {
+    private readonly wikiCompiler;
+    private readonly logger;
+    /**
+     * Create an Fts5SearchStrategy.
+     *
+     * @param wikiCompiler - The WikiCompilerService instance providing FTS5 search
+     */
+    constructor(wikiCompiler: WikiCompilerService);
+    /**
+     * Search for documents matching the query using FTS5 full-text search.
+     *
+     * FTS5 BM25 rank values are negative (more negative = more relevant),
+     * so scores are converted to positive values for the ScoredDocument interface.
+     *
+     * @param query - The search query text
+     * @param documents - Candidate document summaries to match against
+     * @returns Documents sorted by descending relevance score
+     */
+    search(query: string, documents: KnowledgeDocumentSummary[]): Promise<ScoredDocument[]>;
+}
+//# sourceMappingURL=fts5-search-strategy.d.ts.map

package/dist/cli/backend/src/services/knowledge/fts5-search-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fts5-search-strategy.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/knowledge/fts5-search-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC7F,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAC/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGjE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,kBAAmB,YAAW,uBAAuB;IAChE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC;;;;OAIG;gBACS,YAAY,EAAE,mBAAmB;IAK7C;;;;;;;;;OASG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,wBAAwB,EAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;CAyC9F"}

package/dist/cli/backend/src/services/knowledge/fts5-search-strategy.js

@@ -0,0 +1,91 @@
+/**
+ * FTS5 Search Strategy
+ *
+ * Implements the KnowledgeSearchStrategy interface using the SQLite FTS5
+ * full-text search index. Maps FTS5 BM25-ranked results to the existing
+ * ScoredDocument format used by KnowledgeSearchService.
+ *
+ * @module services/knowledge/fts5-search-strategy
+ */
+import { LoggerService } from '../core/logger.service.js';
+/**
+ * FTS5-based search strategy for the Wiki-First Knowledge System.
+ *
+ * This strategy provides pure full-text search via SQLite FTS5 with BM25 ranking.
+ *
+ * Note on semantic fallback (design doc Section 10): The 10% semantic fallback
+ * weight is achieved at the MemoryService level, which runs both FTS5 knowledge
+ * search AND vector-based semantic search in parallel. This strategy intentionally
+ * does not mix semantic results — that composition happens upstream in the recall
+ * pipeline (MemoryService.recall -> searchKnowledgeDocuments + semanticSearch).
+ *
+ * Uses SQLite FTS5 MATCH with BM25 ranking for fast, zero-cost retrieval.
+ * Results are mapped back to the KnowledgeDocumentSummary objects provided
+ * by the caller, falling back to minimal summaries when a document is found
+ * in the FTS5 index but not in the provided documents array.
+ *
+ * @example
+ * ```typescript
+ * const strategy = new Fts5SearchStrategy(wikiCompiler);
+ * const results = await strategy.search('deployment guide', documents);
+ * ```
+ */
+export class Fts5SearchStrategy {
+    wikiCompiler;
+    logger;
+    /**
+     * Create an Fts5SearchStrategy.
+     *
+     * @param wikiCompiler - The WikiCompilerService instance providing FTS5 search
+     */
+    constructor(wikiCompiler) {
+        this.wikiCompiler = wikiCompiler;
+        this.logger = LoggerService.getInstance().createComponentLogger('Fts5SearchStrategy');
+    }
+    /**
+     * Search for documents matching the query using FTS5 full-text search.
+     *
+     * FTS5 BM25 rank values are negative (more negative = more relevant),
+     * so scores are converted to positive values for the ScoredDocument interface.
+     *
+     * @param query - The search query text
+     * @param documents - Candidate document summaries to match against
+     * @returns Documents sorted by descending relevance score
+     */
+    async search(query, documents) {
+        const ftsResults = this.wikiCompiler.search(query, { limit: 10 });
+        if (ftsResults.length === 0) {
+            this.logger.debug('FTS5 search returned no results', { query });
+            return [];
+        }
+        // Build a lookup map from the provided documents array
+        const docById = new Map(documents.map((d) => [d.id, d]));
+        const scored = [];
+        for (const ftsResult of ftsResults) {
+            // FTS5 rank is negative; convert to positive score (higher = more relevant)
+            const score = Math.abs(ftsResult.rank);
+            const existingDoc = docById.get(ftsResult.id);
+            if (existingDoc) {
+                scored.push({ document: existingDoc, score });
+            }
+            else {
+                // Create a minimal summary for documents in FTS5 but not in the provided list
+                const minimalDoc = {
+                    id: ftsResult.id,
+                    title: ftsResult.title,
+                    category: ftsResult.category,
+                    tags: ftsResult.tags ? ftsResult.tags.split(/,\s*/) : [],
+                    preview: ftsResult.content.slice(0, 200),
+                    scope: 'global',
+                    createdBy: 'system',
+                    updatedBy: 'system',
+                    createdAt: new Date().toISOString(),
+                    updatedAt: new Date().toISOString(),
+                };
+                scored.push({ document: minimalDoc, score });
+            }
+        }
+        return scored.sort((a, b) => b.score - a.score);
+    }
+}
+//# sourceMappingURL=fts5-search-strategy.js.map

package/dist/cli/backend/src/services/knowledge/fts5-search-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fts5-search-strategy.js","sourceRoot":"","sources":["../../../../../../backend/src/services/knowledge/fts5-search-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAE,aAAa,EAAwB,MAAM,2BAA2B,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,kBAAkB;IACZ,YAAY,CAAsB;IAClC,MAAM,CAAkB;IAEzC;;;;OAIG;IACH,YAAY,YAAiC;QAC3C,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,WAAW,EAAE,CAAC,qBAAqB,CAAC,oBAAoB,CAAC,CAAC;IACxF,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,SAAqC;QAC/D,MAAM,UAAU,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;QAElE,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YAChE,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,uDAAuD;QACvD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAEzD,MAAM,MAAM,GAAqB,EAAE,CAAC;QAEpC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,4EAA4E;YAC5E,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAEvC,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;YAE9C,IAAI,WAAW,EAAE,CAAC;gBAChB,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;YAChD,CAAC;iBAAM,CAAC;gBACN,8EAA8E;gBAC9E,MAAM,UAAU,GAA6B;oBAC3C,EAAE,EAAE,SAAS,CAAC,EAAE;oBAChB,KAAK,EAAE,SAAS,CAAC,KAAK;oBACtB,QAAQ,EAAE,SAAS,CAAC,QAAQ;oBAC5B,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE;oBACxD,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;oBACxC,KAAK,EAAE,QAAQ;oBACf,SAAS,EAAE,QAAQ;oBACnB,SAAS,EAAE,QAAQ;oBACnB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;oBACnC,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;iBACpC,CAAC;gBACF,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAClD,CAAC;CACF"}

package/dist/cli/backend/src/services/knowledge/learnings-index.service.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Learnings Index Service
+ *
+ * Surfaces project-scoped record-learning entries (`.crewly/knowledge/learnings.md`)
+ * as virtual `KnowledgeDocumentSummary` entries so they appear in the `/knowledge`
+ * UI and are returned by recall searches.
+ *
+ * Background (memory.f1, 2026-04-28): the `record-learning` skill writes to
+ * `learnings.md` (an append-only log owned by `ProjectMemoryService`), but the
+ * `/knowledge` UI reads `KnowledgeService.listDocuments()` which only sees
+ * `.crewly/docs/`. As a result, learnings persisted to disk were not visible
+ * in the UI and were not returned by recall. This service bridges that gap by
+ * parsing the learnings log on demand and exposing each entry under a stable
+ * synthetic ID (`learning:<sha1-prefix>`) that the rest of the knowledge stack
+ * can carry through `listDocuments` / `getDocument` / search.
+ *
+ * @module services/knowledge/learnings-index.service
+ */
+import type { KnowledgeDocument, KnowledgeDocumentSummary, KnowledgeScope } from '../../types/knowledge.types.js';
+/** Prefix that marks a synthetic learning document ID. */
+export declare const LEARNING_ID_PREFIX = "learning:";
+/** Category label used for learnings surfaced in the knowledge UI. */
+export declare const LEARNINGS_CATEGORY = "Learnings";
+/**
+ * A learning entry parsed out of `learnings.md`.
+ *
+ * @internal
+ */
+export interface ParsedLearning {
+    /** Stable synthetic ID — `learning:` prefix + sha1 hash of (timestamp + author + content). */
+    id: string;
+    /** Title — Karpathy-lite `[[Entity]]` opener if present, else first sentence (capped). */
+    title: string;
+    /** Tags — `learning` always, plus any `[tag-name]` tokens found in the body. */
+    tags: string[];
+    /** Full body of the entry (date / agent header lines stripped). */
+    content: string;
+    /** ISO timestamp parsed from `## YYYY-MM-DD` and `### [role/agent] HH:MM:SS` headers. */
+    createdAt: string;
+    /** Same as `createdAt` — learnings are append-only, no separate update timestamp. */
+    updatedAt: string;
+    /** Agent author string from the `[role/agentId]` header (or `unknown`). */
+    author: string;
+}
+/**
+ * Parse `learnings.md` content into discrete learning entries.
+ *
+ * The expected format produced by `ProjectMemoryService.recordLearning` is:
+ *
+ * ```
+ * ## YYYY-MM-DD
+ *
+ * ### [role/agentId] HH:MM:SS
+ * <content>
+ *
+ * ---
+ * ```
+ *
+ * Older entries may lack the `### [role/agentId]` header — those are still
+ * parsed, with `author = 'unknown'` and time defaulting to `00:00:00`. Entries
+ * containing only the file-level header (`# Project Learnings`) are skipped.
+ *
+ * Exported for testing only — callers should use {@link LearningsIndexService}.
+ *
+ * @param raw - Full file content (YAML frontmatter is stripped if present)
+ * @returns Parsed entries in file order
+ */
+export declare function parseLearnings(raw: string): ParsedLearning[];
+/**
+ * Service that surfaces `learnings.md` entries as virtual knowledge documents.
+ *
+ * Singleton, file-system-backed, no caching — `learnings.md` is small enough
+ * (a single project's append-only log) that re-parsing on every list call is
+ * acceptable and avoids stale-cache bugs across writes from the agent skill.
+ */
+export declare class LearningsIndexService {
+    private static instance;
+    private readonly logger;
+    private constructor();
+    /**
+     * Get the singleton instance.
+     *
+     * @returns LearningsIndexService instance
+     */
+    static getInstance(): LearningsIndexService;
+    /**
+     * Reset the singleton (for testing).
+     */
+    static resetInstance(): void;
+    /**
+     * Detect whether an ID belongs to this service's synthetic namespace.
+     *
+     * @param id - Document ID to test
+     * @returns True if the ID has the learning prefix
+     */
+    static isLearningId(id: string): boolean;
+    /**
+     * Resolve the absolute path to `learnings.md` for the given scope.
+     *
+     * Learnings only exist at project scope today (the `record-learning` skill
+     * always requires a `projectPath`). Global scope returns null so callers
+     * can short-circuit cleanly.
+     *
+     * @param scope - 'global' or 'project'
+     * @param projectPath - Required when scope is 'project'
+     * @returns Absolute file path, or null if learnings cannot exist for this scope
+     */
+    private learningsPath;
+    /**
+     * Read and parse `learnings.md` for the given scope.
+     *
+     * Missing-file and read-error cases both return an empty array — the
+     * indexer must never fail callers just because no learnings exist yet.
+     *
+     * @param scope - Document scope
+     * @param projectPath - Project path (required for 'project' scope)
+     * @returns Parsed learning entries (empty if file missing or unreadable)
+     */
+    private readLearnings;
+    /**
+     * List all learnings for the given scope as `KnowledgeDocumentSummary` entries.
+     *
+     * Sorted newest-first so the UI shows recent learnings at the top of the
+     * unified knowledge list (matching the user mental model that learnings
+     * are a chronological journal).
+     *
+     * @param scope - 'global' or 'project'
+     * @param projectPath - Required when scope is 'project'
+     * @returns Array of summaries (empty if scope is 'global' or no learnings exist)
+     */
+    listLearnings(scope: KnowledgeScope, projectPath?: string): Promise<KnowledgeDocumentSummary[]>;
+    /**
+     * Fetch a single learning by its synthetic ID.
+     *
+     * @param id - Synthetic document ID (must start with `learning:`)
+     * @param scope - Document scope
+     * @param projectPath - Required when scope is 'project'
+     * @returns Full document, or null if id is not a learning id or not found
+     */
+    getLearning(id: string, scope: KnowledgeScope, projectPath?: string): Promise<KnowledgeDocument | null>;
+    /**
+     * Project a parsed entry into a `KnowledgeDocumentSummary`.
+     *
+     * @param e - Parsed learning entry
+     * @param scope - Target scope label
+     * @returns Summary suitable for the knowledge list API
+     */
+    private toSummary;
+    /**
+     * Project a parsed entry into a full `KnowledgeDocument`.
+     *
+     * @param e - Parsed learning entry
+     * @param scope - Target scope label
+     * @param projectPath - Carried into the document for project-scoped entries
+     * @returns Full document suitable for the knowledge document API
+     */
+    private toDocument;
+}
+//# sourceMappingURL=learnings-index.service.d.ts.map

package/dist/cli/backend/src/services/knowledge/learnings-index.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learnings-index.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/knowledge/learnings-index.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAQH,OAAO,KAAK,EACV,iBAAiB,EACjB,wBAAwB,EACxB,cAAc,EACf,MAAM,gCAAgC,CAAC;AAGxC,0DAA0D;AAC1D,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAE9C,sEAAsE;AACtE,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAQ9C;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,8FAA8F;IAC9F,EAAE,EAAE,MAAM,CAAC;IACX,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,yFAAyF;IACzF,SAAS,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,EAAE,CAiG5D;AAED;;;;;;GAMG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAsC;IAC7D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC,OAAO;IAIP;;;;OAIG;IACH,MAAM,CAAC,WAAW,IAAI,qBAAqB;IAO3C;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,IAAI;IAI5B;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,aAAa;IAYrB;;;;;;;;;OASG;YACW,aAAa;IAiB3B;;;;;;;;;;OAUG;IACG,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,EAAE,CAAC;IAOrG;;;;;;;OAOG;IACG,WAAW,CACf,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,cAAc,EACrB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IASpC;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IAejB;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;CAmBnB"}

package/dist/cli/backend/src/services/knowledge/learnings-index.service.js

@@ -0,0 +1,304 @@
+/**
+ * Learnings Index Service
+ *
+ * Surfaces project-scoped record-learning entries (`.crewly/knowledge/learnings.md`)
+ * as virtual `KnowledgeDocumentSummary` entries so they appear in the `/knowledge`
+ * UI and are returned by recall searches.
+ *
+ * Background (memory.f1, 2026-04-28): the `record-learning` skill writes to
+ * `learnings.md` (an append-only log owned by `ProjectMemoryService`), but the
+ * `/knowledge` UI reads `KnowledgeService.listDocuments()` which only sees
+ * `.crewly/docs/`. As a result, learnings persisted to disk were not visible
+ * in the UI and were not returned by recall. This service bridges that gap by
+ * parsing the learnings log on demand and exposing each entry under a stable
+ * synthetic ID (`learning:<sha1-prefix>`) that the rest of the knowledge stack
+ * can carry through `listDocuments` / `getDocument` / search.
+ *
+ * @module services/knowledge/learnings-index.service
+ */
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import { existsSync } from 'fs';
+import { createHash } from 'crypto';
+import { LoggerService } from '../core/logger.service.js';
+import { CREWLY_CONSTANTS, MEMORY_CONSTANTS } from '../../constants.js';
+import { KNOWLEDGE_CONSTANTS } from '../../types/knowledge.types.js';
+/** Prefix that marks a synthetic learning document ID. */
+export const LEARNING_ID_PREFIX = 'learning:';
+/** Category label used for learnings surfaced in the knowledge UI. */
+export const LEARNINGS_CATEGORY = 'Learnings';
+/** Maximum title length for a synthesized learning summary (kept short for list rendering). */
+const MAX_TITLE_LENGTH = 100;
+/** Length of the sha1 hash prefix used for synthetic IDs (16 hex chars = 64 bits collision space). */
+const ID_HASH_LENGTH = 16;
+/**
+ * Parse `learnings.md` content into discrete learning entries.
+ *
+ * The expected format produced by `ProjectMemoryService.recordLearning` is:
+ *
+ * ```
+ * ## YYYY-MM-DD
+ *
+ * ### [role/agentId] HH:MM:SS
+ * <content>
+ *
+ * ---
+ * ```
+ *
+ * Older entries may lack the `### [role/agentId]` header — those are still
+ * parsed, with `author = 'unknown'` and time defaulting to `00:00:00`. Entries
+ * containing only the file-level header (`# Project Learnings`) are skipped.
+ *
+ * Exported for testing only — callers should use {@link LearningsIndexService}.
+ *
+ * @param raw - Full file content (YAML frontmatter is stripped if present)
+ * @returns Parsed entries in file order
+ */
+export function parseLearnings(raw) {
+    // Strip YAML frontmatter (if present) so the first `---` after it doesn't
+    // get treated as a section separator.
+    let body = raw;
+    if (body.startsWith('---')) {
+        const end = body.indexOf('\n---', 3);
+        if (end !== -1) {
+            body = body.slice(end + 4);
+        }
+    }
+    // Sections are separated by a markdown horizontal rule (a line containing
+    // only `---`). The recordLearning writer always emits this between entries.
+    const sections = body
+        .split(/^---\s*$/m)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    const entries = [];
+    for (const section of sections) {
+        // Skip file-level headers (`# Project Learnings: ...`).
+        if (/^#\s+(Project Learnings|Learnings from)/i.test(section)) {
+            continue;
+        }
+        const dateMatch = section.match(/^##\s+(\d{4}-\d{2}-\d{2})/m);
+        const date = dateMatch?.[1] ?? '';
+        const agentMatch = section.match(/^###\s+\[([^\]]+)\]\s+(\d{2}:\d{2}:\d{2})/m);
+        const author = agentMatch?.[1] ?? 'unknown';
+        const time = agentMatch?.[2] ?? '00:00:00';
+        // ISO timestamp: combine date + time as UTC. If date is missing (truly
+        // malformed), fall back to epoch so the entry still surfaces but sorts
+        // last. This is intentionally permissive: better to show a learning with
+        // a wrong-looking timestamp than to drop it silently.
+        const createdAt = date ? `${date}T${time}.000Z` : new Date(0).toISOString();
+        // Strip the headers we already parsed from the content body so they don't
+        // appear duplicated in the synthesized document.
+        const content = section
+            .replace(/^##\s+\d{4}-\d{2}-\d{2}\s*$/m, '')
+            .replace(/^###\s+\[[^\]]+\]\s+\d{2}:\d{2}:\d{2}\s*$/m, '')
+            .trim();
+        if (!content) {
+            continue;
+        }
+        // Title selection priority:
+        //   1. Karpathy-lite `[[Entity]]` opener — entity name as title.
+        //   2. First sentence/line of the body, capped at MAX_TITLE_LENGTH.
+        const entityMatch = content.match(/^\[\[([^\]]+)\]\]/);
+        let title;
+        if (entityMatch) {
+            title = entityMatch[1].trim().slice(0, MAX_TITLE_LENGTH);
+        }
+        else {
+            const firstSentence = content.split(/[.\n]/)[0].trim();
+            title = firstSentence.slice(0, MAX_TITLE_LENGTH) || 'Learning';
+        }
+        // Tags: 'learning' plus any `[tag-name]` markers in the body. Matches the
+        // existing convention used by record-learning callers (e.g. `[best-practice]`,
+        // `[gotcha]`, `[architecture-decision]`).
+        const tags = ['learning'];
+        const tagPattern = /\[([a-z][a-z0-9-]{0,49})\]/g;
+        let tagMatch;
+        while ((tagMatch = tagPattern.exec(content)) !== null) {
+            const tag = tagMatch[1];
+            if (!tags.includes(tag) && tags.length < KNOWLEDGE_CONSTANTS.MAX_TAGS) {
+                tags.push(tag);
+            }
+        }
+        // Stable synthetic ID. We hash (timestamp + author + content prefix) so
+        // that re-parsing the same file produces the same IDs, but two entries
+        // written at the same second by the same author with different content
+        // get distinct IDs. SHA-1 + 16 hex chars is sufficient (64 bits) for the
+        // append-only log scale.
+        const idHash = createHash('sha1')
+            .update(`${createdAt}|${author}|${content.slice(0, 200)}`)
+            .digest('hex')
+            .slice(0, ID_HASH_LENGTH);
+        entries.push({
+            id: `${LEARNING_ID_PREFIX}${idHash}`,
+            title,
+            tags,
+            content,
+            createdAt,
+            updatedAt: createdAt,
+            author,
+        });
+    }
+    return entries;
+}
+/**
+ * Service that surfaces `learnings.md` entries as virtual knowledge documents.
+ *
+ * Singleton, file-system-backed, no caching — `learnings.md` is small enough
+ * (a single project's append-only log) that re-parsing on every list call is
+ * acceptable and avoids stale-cache bugs across writes from the agent skill.
+ */
+export class LearningsIndexService {
+    static instance = null;
+    logger;
+    constructor() {
+        this.logger = LoggerService.getInstance().createComponentLogger('LearningsIndexService');
+    }
+    /**
+     * Get the singleton instance.
+     *
+     * @returns LearningsIndexService instance
+     */
+    static getInstance() {
+        if (!LearningsIndexService.instance) {
+            LearningsIndexService.instance = new LearningsIndexService();
+        }
+        return LearningsIndexService.instance;
+    }
+    /**
+     * Reset the singleton (for testing).
+     */
+    static resetInstance() {
+        LearningsIndexService.instance = null;
+    }
+    /**
+     * Detect whether an ID belongs to this service's synthetic namespace.
+     *
+     * @param id - Document ID to test
+     * @returns True if the ID has the learning prefix
+     */
+    static isLearningId(id) {
+        return typeof id === 'string' && id.startsWith(LEARNING_ID_PREFIX);
+    }
+    /**
+     * Resolve the absolute path to `learnings.md` for the given scope.
+     *
+     * Learnings only exist at project scope today (the `record-learning` skill
+     * always requires a `projectPath`). Global scope returns null so callers
+     * can short-circuit cleanly.
+     *
+     * @param scope - 'global' or 'project'
+     * @param projectPath - Required when scope is 'project'
+     * @returns Absolute file path, or null if learnings cannot exist for this scope
+     */
+    learningsPath(scope, projectPath) {
+        if (scope !== 'project' || !projectPath) {
+            return null;
+        }
+        return path.join(projectPath, CREWLY_CONSTANTS.PATHS.CREWLY_HOME, MEMORY_CONSTANTS.PATHS.KNOWLEDGE_DIR, MEMORY_CONSTANTS.PROJECT_FILES.LEARNINGS);
+    }
+    /**
+     * Read and parse `learnings.md` for the given scope.
+     *
+     * Missing-file and read-error cases both return an empty array — the
+     * indexer must never fail callers just because no learnings exist yet.
+     *
+     * @param scope - Document scope
+     * @param projectPath - Project path (required for 'project' scope)
+     * @returns Parsed learning entries (empty if file missing or unreadable)
+     */
+    async readLearnings(scope, projectPath) {
+        const filePath = this.learningsPath(scope, projectPath);
+        if (!filePath || !existsSync(filePath)) {
+            return [];
+        }
+        try {
+            const raw = await fs.readFile(filePath, 'utf-8');
+            return parseLearnings(raw);
+        }
+        catch (error) {
+            this.logger.warn('Failed to read learnings.md', {
+                path: filePath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return [];
+        }
+    }
+    /**
+     * List all learnings for the given scope as `KnowledgeDocumentSummary` entries.
+     *
+     * Sorted newest-first so the UI shows recent learnings at the top of the
+     * unified knowledge list (matching the user mental model that learnings
+     * are a chronological journal).
+     *
+     * @param scope - 'global' or 'project'
+     * @param projectPath - Required when scope is 'project'
+     * @returns Array of summaries (empty if scope is 'global' or no learnings exist)
+     */
+    async listLearnings(scope, projectPath) {
+        const parsed = await this.readLearnings(scope, projectPath);
+        return parsed
+            .map((e) => this.toSummary(e, scope))
+            .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    }
+    /**
+     * Fetch a single learning by its synthetic ID.
+     *
+     * @param id - Synthetic document ID (must start with `learning:`)
+     * @param scope - Document scope
+     * @param projectPath - Required when scope is 'project'
+     * @returns Full document, or null if id is not a learning id or not found
+     */
+    async getLearning(id, scope, projectPath) {
+        if (!LearningsIndexService.isLearningId(id)) {
+            return null;
+        }
+        const parsed = await this.readLearnings(scope, projectPath);
+        const found = parsed.find((e) => e.id === id);
+        return found ? this.toDocument(found, scope, projectPath) : null;
+    }
+    /**
+     * Project a parsed entry into a `KnowledgeDocumentSummary`.
+     *
+     * @param e - Parsed learning entry
+     * @param scope - Target scope label
+     * @returns Summary suitable for the knowledge list API
+     */
+    toSummary(e, scope) {
+        return {
+            id: e.id,
+            title: e.title,
+            category: LEARNINGS_CATEGORY,
+            tags: e.tags,
+            preview: e.content.slice(0, KNOWLEDGE_CONSTANTS.PREVIEW_LENGTH),
+            scope,
+            createdBy: e.author,
+            updatedBy: e.author,
+            createdAt: e.createdAt,
+            updatedAt: e.updatedAt,
+        };
+    }
+    /**
+     * Project a parsed entry into a full `KnowledgeDocument`.
+     *
+     * @param e - Parsed learning entry
+     * @param scope - Target scope label
+     * @param projectPath - Carried into the document for project-scoped entries
+     * @returns Full document suitable for the knowledge document API
+     */
+    toDocument(e, scope, projectPath) {
+        return {
+            id: e.id,
+            title: e.title,
+            category: LEARNINGS_CATEGORY,
+            tags: e.tags,
+            content: e.content,
+            scope,
+            projectPath: scope === 'project' ? projectPath : undefined,
+            createdBy: e.author,
+            updatedBy: e.author,
+            createdAt: e.createdAt,
+            updatedAt: e.updatedAt,
+        };
+    }
+}
+//# sourceMappingURL=learnings-index.service.js.map