crewly 1.8.9 → 1.8.12

package/dist/backend/backend/src/services/wiki/wiki-search.service.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Wiki Search Service
+ *
+ * In-process full-text search across a wiki vault's `.md` files. Returns
+ * per-file matches with line numbers + short snippets so the UI can render
+ * a result list and let the user jump straight to a page.
+ *
+ * Phase 1: simple case-insensitive substring search. No tokenization,
+ * stemming, or inverted index. The vaults here are O(100s) of pages so
+ * walking + grepping per request is fine; we'll revisit when volumes
+ * justify a real index.
+ *
+ * @module services/wiki/wiki-search.service
+ */
+/** Cap on how many .md files are inspected per search. */
+export declare const WIKI_SEARCH_MAX_FILES = 500;
+/** Cap on how many results returned to the caller. */
+export declare const WIKI_SEARCH_MAX_RESULTS = 50;
+/** Cap on how many snippets surfaced per matching file. */
+export declare const WIKI_SEARCH_MAX_SNIPPETS_PER_FILE = 3;
+/** Maximum query length — guards against pathological input. */
+export declare const WIKI_SEARCH_MAX_QUERY_LENGTH = 200;
+/** Cap on per-file size we will read; larger files are skipped. */
+export declare const WIKI_SEARCH_MAX_FILE_BYTES: number;
+export interface WikiSearchSnippet {
+    /** 1-based line number where the match was found. */
+    lineNumber: number;
+    /** The matching line (trimmed for display). */
+    text: string;
+}
+export interface WikiSearchHit {
+    /** Relative path inside the vault, with forward slashes. */
+    relativePath: string;
+    /** True when the filename itself contains the query. */
+    filenameMatch: boolean;
+    /** Number of total content matches across the file. */
+    matchCount: number;
+    /** Up to `WIKI_SEARCH_MAX_SNIPPETS_PER_FILE` matching lines. */
+    snippets: WikiSearchSnippet[];
+}
+export interface WikiSearchResult {
+    ok: true;
+    vaultPath: string;
+    query: string;
+    hits: WikiSearchHit[];
+    /** True when the file/result cap was hit; UI should hint "narrow your search". */
+    truncated: boolean;
+}
+export interface WikiSearchFailure {
+    ok: false;
+    reason: 'vault_missing' | 'invalid_input' | 'invalid_query';
+    message: string;
+}
+export interface WikiSearchInput {
+    vaultPath: string;
+    query: string;
+}
+/**
+ * Service exposing `search()`. Stateless singleton — the constructor is
+ * empty but we use the class pattern to match the rest of the wiki
+ * services (`WikiBookkeepService.getInstance()`, etc.).
+ */
+export declare class WikiSearchService {
+    private static instance;
+    /** Singleton accessor. */
+    static getInstance(): WikiSearchService;
+    /** Reset for tests. */
+    static resetInstance(): void;
+    /**
+     * Search a vault. Returns either `{ok:true, hits}` or a structured
+     * failure. The handler never throws on filesystem read errors — they
+     * are silently skipped so one bad file doesn't blank the whole result.
+     */
+    search(input: WikiSearchInput): Promise<WikiSearchResult | WikiSearchFailure>;
+    /**
+     * Recursive walk collecting `.md` files. Skips dotfile dirs (e.g.
+     * `.git`, `.queue`) and stops once `WIKI_SEARCH_MAX_FILES` is reached.
+     *
+     * @param rootDir - vault root (used to compute relativePath).
+     * @param dir - current directory being walked.
+     * @param acc - accumulator populated with relative paths.
+     */
+    private collectMdFiles;
+    /**
+     * Read one file and accumulate up to `WIKI_SEARCH_MAX_SNIPPETS_PER_FILE`
+     * snippets. Returns null when the file matches nothing.
+     */
+    private searchFile;
+}
+//# sourceMappingURL=wiki-search.service.d.ts.map

package/dist/backend/backend/src/services/wiki/wiki-search.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki-search.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/wiki/wiki-search.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAC1C,2DAA2D;AAC3D,eAAO,MAAM,iCAAiC,IAAI,CAAC;AACnD,gEAAgE;AAChE,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAChD,mEAAmE;AACnE,eAAO,MAAM,0BAA0B,QAAa,CAAC;AAErD,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,aAAa,EAAE,OAAO,CAAC;IACvB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,IAAI,CAAC;IACT,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,kFAAkF;IAClF,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,eAAe,GAAG,eAAe,GAAG,eAAe,CAAC;IAC5D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAkC;IAEzD,0BAA0B;IAC1B,MAAM,CAAC,WAAW,IAAI,iBAAiB;IAKvC,uBAAuB;IACvB,MAAM,CAAC,aAAa,IAAI,IAAI;IAI5B;;;;OAIG;IACG,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,GAAG,iBAAiB,CAAC;IAwDnF;;;;;;;OAOG;YACW,cAAc;IAqB5B;;;OAGG;YACW,UAAU;CAuDzB"}

package/dist/backend/backend/src/services/wiki/wiki-search.service.js

@@ -0,0 +1,190 @@
+/**
+ * Wiki Search Service
+ *
+ * In-process full-text search across a wiki vault's `.md` files. Returns
+ * per-file matches with line numbers + short snippets so the UI can render
+ * a result list and let the user jump straight to a page.
+ *
+ * Phase 1: simple case-insensitive substring search. No tokenization,
+ * stemming, or inverted index. The vaults here are O(100s) of pages so
+ * walking + grepping per request is fine; we'll revisit when volumes
+ * justify a real index.
+ *
+ * @module services/wiki/wiki-search.service
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { existsSync } from 'fs';
+/** Cap on how many .md files are inspected per search. */
+export const WIKI_SEARCH_MAX_FILES = 500;
+/** Cap on how many results returned to the caller. */
+export const WIKI_SEARCH_MAX_RESULTS = 50;
+/** Cap on how many snippets surfaced per matching file. */
+export const WIKI_SEARCH_MAX_SNIPPETS_PER_FILE = 3;
+/** Maximum query length — guards against pathological input. */
+export const WIKI_SEARCH_MAX_QUERY_LENGTH = 200;
+/** Cap on per-file size we will read; larger files are skipped. */
+export const WIKI_SEARCH_MAX_FILE_BYTES = 256 * 1024;
+/**
+ * Service exposing `search()`. Stateless singleton — the constructor is
+ * empty but we use the class pattern to match the rest of the wiki
+ * services (`WikiBookkeepService.getInstance()`, etc.).
+ */
+export class WikiSearchService {
+    static instance = null;
+    /** Singleton accessor. */
+    static getInstance() {
+        if (!this.instance)
+            this.instance = new WikiSearchService();
+        return this.instance;
+    }
+    /** Reset for tests. */
+    static resetInstance() {
+        this.instance = null;
+    }
+    /**
+     * Search a vault. Returns either `{ok:true, hits}` or a structured
+     * failure. The handler never throws on filesystem read errors — they
+     * are silently skipped so one bad file doesn't blank the whole result.
+     */
+    async search(input) {
+        const vaultPath = input.vaultPath;
+        const rawQuery = input.query ?? '';
+        if (!vaultPath || !path.isAbsolute(vaultPath)) {
+            return {
+                ok: false,
+                reason: 'invalid_input',
+                message: 'vaultPath must be an absolute path',
+            };
+        }
+        if (!existsSync(vaultPath)) {
+            return { ok: false, reason: 'vault_missing', message: `vault not found: ${vaultPath}` };
+        }
+        const query = rawQuery.trim();
+        if (query.length === 0) {
+            return {
+                ok: false,
+                reason: 'invalid_query',
+                message: 'query must be at least one non-whitespace character',
+            };
+        }
+        if (query.length > WIKI_SEARCH_MAX_QUERY_LENGTH) {
+            return {
+                ok: false,
+                reason: 'invalid_query',
+                message: `query exceeds ${WIKI_SEARCH_MAX_QUERY_LENGTH} characters`,
+            };
+        }
+        const needle = query.toLowerCase();
+        const allFiles = [];
+        await this.collectMdFiles(vaultPath, vaultPath, allFiles);
+        const truncatedFiles = allFiles.length >= WIKI_SEARCH_MAX_FILES;
+        const slice = allFiles.slice(0, WIKI_SEARCH_MAX_FILES);
+        const hits = [];
+        for (const relativePath of slice) {
+            const hit = await this.searchFile(vaultPath, relativePath, needle);
+            if (hit)
+                hits.push(hit);
+        }
+        // Rank: filename matches first, then matchCount desc, then path asc for stability.
+        hits.sort((a, b) => {
+            if (a.filenameMatch !== b.filenameMatch)
+                return a.filenameMatch ? -1 : 1;
+            if (a.matchCount !== b.matchCount)
+                return b.matchCount - a.matchCount;
+            return a.relativePath.localeCompare(b.relativePath);
+        });
+        const truncatedResults = hits.length > WIKI_SEARCH_MAX_RESULTS;
+        const capped = hits.slice(0, WIKI_SEARCH_MAX_RESULTS);
+        const truncated = truncatedFiles || truncatedResults;
+        return { ok: true, vaultPath, query, hits: capped, truncated };
+    }
+    /**
+     * Recursive walk collecting `.md` files. Skips dotfile dirs (e.g.
+     * `.git`, `.queue`) and stops once `WIKI_SEARCH_MAX_FILES` is reached.
+     *
+     * @param rootDir - vault root (used to compute relativePath).
+     * @param dir - current directory being walked.
+     * @param acc - accumulator populated with relative paths.
+     */
+    async collectMdFiles(rootDir, dir, acc) {
+        if (acc.length >= WIKI_SEARCH_MAX_FILES)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (acc.length >= WIKI_SEARCH_MAX_FILES)
+                return;
+            if (entry.name.startsWith('.'))
+                continue;
+            const abs = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await this.collectMdFiles(rootDir, abs, acc);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                const rel = path.relative(rootDir, abs).replace(/\\/g, '/');
+                acc.push(rel);
+            }
+        }
+    }
+    /**
+     * Read one file and accumulate up to `WIKI_SEARCH_MAX_SNIPPETS_PER_FILE`
+     * snippets. Returns null when the file matches nothing.
+     */
+    async searchFile(vaultPath, relativePath, needle) {
+        const absPath = path.join(vaultPath, relativePath);
+        const filenameMatch = relativePath.toLowerCase().includes(needle);
+        let stat;
+        try {
+            stat = await fs.stat(absPath);
+        }
+        catch {
+            return filenameMatch
+                ? { relativePath, filenameMatch: true, matchCount: 0, snippets: [] }
+                : null;
+        }
+        if (stat.size > WIKI_SEARCH_MAX_FILE_BYTES) {
+            return filenameMatch
+                ? { relativePath, filenameMatch: true, matchCount: 0, snippets: [] }
+                : null;
+        }
+        let content;
+        try {
+            content = await fs.readFile(absPath, 'utf8');
+        }
+        catch {
+            return filenameMatch
+                ? { relativePath, filenameMatch: true, matchCount: 0, snippets: [] }
+                : null;
+        }
+        const lines = content.split(/\r?\n/);
+        const snippets = [];
+        let matchCount = 0;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (line.toLowerCase().includes(needle)) {
+                matchCount++;
+                if (snippets.length < WIKI_SEARCH_MAX_SNIPPETS_PER_FILE) {
+                    snippets.push({
+                        lineNumber: i + 1,
+                        text: line.trim().slice(0, 300),
+                    });
+                }
+            }
+        }
+        if (matchCount === 0 && !filenameMatch)
+            return null;
+        return {
+            relativePath,
+            filenameMatch,
+            matchCount,
+            snippets,
+        };
+    }
+}
+//# sourceMappingURL=wiki-search.service.js.map

package/dist/backend/backend/src/services/wiki/wiki-search.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki-search.service.js","sourceRoot":"","sources":["../../../../../../backend/src/services/wiki/wiki-search.service.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/wiki/wiki-workitem-bridge.service.d.ts

@@ -0,0 +1,164 @@
+/**
+ * WikiWorkItemBridgeService — materialises pending wiki work as claimable WIs.
+ *
+ * Replaces the wiki-bookkeep / wiki-reflect "shouldFire ≥ threshold" cron
+ * model with the same V3 pool the rest of the system uses. Two source
+ * streams feed the pool:
+ *
+ *   1. Pending `wiki-queue` items (one WI per vault that has ≥ 1 pending
+ *      item; the agent drains the whole vault in that WI).
+ *   2. Legacy `.crewly/knowledge/*` migration candidates per project (one
+ *      WI per project root with > 0 proposed pages).
+ *
+ * Idle agents claim them through `TaskPoolService.claimFromPool` — no
+ * extra cron decisions about who to ping. Failures route through the
+ * standard task:failed / reconciler escalation paths (closing the loop
+ * with the 2026-05-27 reconciler-escalation fix in
+ * `reconciler-data-provider.ts:applyCorrection`).
+ *
+ * PR-1 routing (conservative): both kinds target the orchestrator
+ * session. The wiki skills today live under `config/skills/orchestrator/`,
+ * so ORC is the only role with a built-in handler. Broadening to TLs is
+ * a follow-up once the skills are promoted to a shared path.
+ *
+ * Dedupe: at most one non-terminal WI per (kind, vaultPath/projectRoot).
+ *
+ * @module services/wiki/wiki-workitem-bridge.service
+ */
+import { TaskPoolService } from '../task-pool/task-pool.service.js';
+import { WikiQueueService } from './wiki-queue.service.js';
+import { WikiMigrateService } from './wiki-migrate.service.js';
+import { WikiCleanupService } from './wiki-cleanup.service.js';
+/** WorkItem.metadata.kind value identifying a wiki queue drain WI. */
+export declare const META_KIND_WIKI_DRAIN: "wiki_queue_drain";
+/** WorkItem.metadata.kind value identifying a wiki legacy migration WI. */
+export declare const META_KIND_WIKI_MIGRATE: "wiki_legacy_migrate";
+/** WorkItem.metadata.kind value identifying a wiki cleanup (low-quality removal) WI. */
+export declare const META_KIND_WIKI_CLEANUP: "wiki_quality_cleanup";
+export interface WikiWorkItemBridgeOptions {
+    /** How often to scan vaults + projects (default 10 min). */
+    intervalMs?: number;
+    /** Target agent session for the created WIs (default `crewly-orc`). */
+    targetAgent?: string;
+    /**
+     * Max new WIs to publish per tick (default 2). Throttles PTY flood —
+     * see {@link DEFAULT_MAX_CREATES_PER_TICK}.
+     */
+    maxCreatesPerTick?: number;
+    /**
+     * Per-key cooldown (default 30 min) between successive create attempts
+     * for the same vault path or project root. Survives pool deletes —
+     * see {@link DEFAULT_COOLDOWN_MS}.
+     */
+    cooldownMs?: number;
+    /** Time source override (test seam). Returns `Date.now()` by default. */
+    now?: () => number;
+    /**
+     * Override the state file path (test seam). When omitted, the bridge
+     * resolves `~/.crewly/wiki-bridge-state.json` via `getCrewlyHomePath()`.
+     * Passing `null` disables persistence entirely — handy for unit tests
+     * that don't want filesystem side effects.
+     */
+    statePath?: string | null;
+    /** Vault discovery override (default: `discoverWikiVaults`). */
+    discoverRoots?: () => Promise<string[]>;
+    /** Project-root discovery override (default: cwd + projects.json entries). */
+    discoverProjectRoots?: () => Promise<string[]>;
+    /** Wiki queue service override (test seam). */
+    queueService?: WikiQueueService;
+    /** Wiki migrate service override (test seam). */
+    migrateService?: WikiMigrateService;
+    /** Wiki cleanup service override (test seam). */
+    cleanupService?: WikiCleanupService;
+    /** Task pool override (test seam). */
+    taskPool?: TaskPoolService;
+}
+export interface WikiBridgeTickResult {
+    scannedVaults: string[];
+    createdForVault: string[];
+    skippedInflightVaults: string[];
+    scannedProjects: string[];
+    createdForProject: string[];
+    skippedInflightProjects: string[];
+    /** Candidates that were eligible but deferred to the next tick because of {@link WikiWorkItemBridgeOptions.maxCreatesPerTick}. */
+    deferredByThrottle: string[];
+    /** Candidates skipped because their cooldown hasn't elapsed yet. */
+    skippedByCooldown: string[];
+    /** Vault paths for which a cleanup WI was created this tick. */
+    createdCleanupForVault: string[];
+}
+/**
+ * Periodic bridge: pending wiki queue items + migration candidates
+ * become claimable WorkItems in the V3 pool.
+ */
+export declare class WikiWorkItemBridgeService {
+    private static instance;
+    private readonly logger;
+    private readonly intervalMs;
+    private readonly targetAgent;
+    private readonly maxCreatesPerTick;
+    private readonly cooldownMs;
+    private readonly nowFn;
+    private readonly discoverRoots;
+    private readonly discoverProjectRoots;
+    private readonly queue;
+    private readonly migrate;
+    private readonly cleanup;
+    private readonly pool;
+    private timer;
+    private running;
+    /** Per-key (kind + path) last-create timestamp. Survives pool deletes. */
+    private readonly lastCreatedAt;
+    /** Absolute path of the persisted state file (or `null` to disable). */
+    private readonly statePath;
+    /** True after `loadStateFromDisk` has either populated or no-op'd. */
+    private stateLoaded;
+    constructor(opts?: WikiWorkItemBridgeOptions);
+    /**
+     * Hydrate {@link lastCreatedAt} from disk. Idempotent — runs once per
+     * service lifetime. Bad/missing/stale-version files reset to empty.
+     */
+    private loadStateFromDisk;
+    /**
+     * Persist {@link lastCreatedAt} to disk. Best-effort — write failures
+     * are logged but never throw (the bridge is non-essential infrastructure).
+     * Prunes expired entries before writing so the file stays small.
+     */
+    private saveStateToDisk;
+    /**
+     * True iff the key's cooldown is still active (i.e., we created a WI
+     * for this key recently). Survives forced pool deletes so an
+     * agent-driven cleanup can't trick the bridge into re-creating
+     * immediately.
+     */
+    private isCoolingDown;
+    private markCreated;
+    static getInstance(): WikiWorkItemBridgeService | null;
+    /** Wire / detach the production singleton. */
+    static setInstance(next: WikiWorkItemBridgeService | null): void;
+    /** Start the periodic scan. Idempotent. Fires an immediate tick. */
+    start(): void;
+    stop(): void;
+    /** Single pass — exposed for tests and the initial boot-time fire. */
+    tick(): Promise<WikiBridgeTickResult>;
+    /**
+     * Build the dedupe sets from the pool's current contents. A WI is
+     * "in-flight" if its kind metadata matches and its status is not
+     * terminal — i.e. it's still queued/claimed/running/etc.
+     */
+    private snapshotInflight;
+    private createDrainWorkItem;
+    private createCleanupWorkItem;
+    private createMigrateWorkItem;
+}
+/**
+ * Best-effort label for a vault path that surfaces in UI/list views.
+ * Order matters: check global before the generic project tail.
+ */
+export declare function describeVaultScope(vaultPath: string): string;
+/**
+ * Default project-root discovery used by the production bridge. Mirrors
+ * `discoverWikiVaults`'s project sources but returns roots, not vault paths.
+ */
+export declare function defaultProjectRoots(): Promise<string[]>;
+//# sourceMappingURL=wiki-workitem-bridge.service.d.ts.map

package/dist/backend/backend/src/services/wiki/wiki-workitem-bridge.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki-workitem-bridge.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/wiki/wiki-workitem-bridge.service.ts"],"names":[],"mappings":"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"}