@mcoda/integrations 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -3,5 +3,8 @@
 ## Unreleased
 - Initial public packaging for @mcoda/integrations.
 
+## 0.1.9
+- Release v0.1.9.
+
 ## 0.1.8
 - Initial release.

package/README.md

@@ -7,7 +7,7 @@ External integrations for mcoda (docdex, telemetry, VCS, QA runners, update chec
 - Install: `npm i @mcoda/integrations`
 
 ## What it provides
-- DocdexClient for local or remote docdex queries.
+- DocdexClient for docdex daemon queries and CLI-backed ingestion.
 - TelemetryClient for token usage reporting.
 - VcsClient for Git operations.
 - SystemClient for update checks.
@@ -26,6 +26,8 @@ const docs = await client.search({ docType: "rfp", query: "payments" });
 ```
 
 ## Notes
+- Docdex state lives under `~/.docdex` (managed by the `docdex` CLI); mcoda does not create repo-local `.docdex`.
+- Chromium QA expects Playwright browsers provisioned via `docdex setup`.
 - Some integrations call external services; configure base URLs and tokens as needed.
 - Primarily used by the mcoda CLI; APIs may evolve.
 

package/dist/docdex/DocdexClient.d.ts

@@ -25,17 +25,21 @@ export interface RegisterDocumentInput {
 }
 export declare class DocdexClient {
     private options;
+    private resolvedBaseUrl?;
+    private repoId?;
+    private initializing;
     constructor(options?: {
         workspaceRoot?: string;
-        storePath?: string;
         baseUrl?: string;
         authToken?: string;
+        repoId?: string;
     });
-    private getStorePath;
     private normalizePath;
-    private loadStore;
+    private resolveBaseUrl;
+    private ensureRepoInitialized;
     private fetchRemote;
-    private saveStore;
+    private buildLocalDoc;
+    private coerceSearchResults;
     fetchDocumentById(id: string): Promise<DocdexDocument>;
     findDocumentByPath(docPath: string, docType?: string): Promise<DocdexDocument | undefined>;
     search(filter: {
@@ -44,6 +48,7 @@ export declare class DocdexClient {
         query?: string;
         profile?: string;
     }): Promise<DocdexDocument[]>;
+    reindex(): Promise<void>;
     registerDocument(input: RegisterDocumentInput): Promise<DocdexDocument>;
     ensureRegisteredFromFile(docPath: string, docType: string, metadata?: Record<string, unknown>): Promise<DocdexDocument>;
 }

package/dist/docdex/DocdexClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DocdexClient.d.ts","sourceRoot":"","sources":["../../src/docdex/DocdexClient.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAyCD,qBAAa,YAAY;IAErB,OAAO,CAAC,OAAO;gBAAP,OAAO,GAAE;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;KACf;IAGR,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,aAAa;YAYP,SAAS;YAaT,WAAW;YAYX,SAAS;IAOjB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAoBtD,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAU1F,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IA0BtH,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC;IA6DvE,wBAAwB,CAC5B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,cAAc,CAAC;CAO3B"}
+{"version":3,"file":"DocdexClient.d.ts","sourceRoot":"","sources":["../../src/docdex/DocdexClient.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAkDD,qBAAa,YAAY;IAMrB,OAAO,CAAC,OAAO;IALjB,OAAO,CAAC,eAAe,CAAC,CAAS;IACjC,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,YAAY,CAAS;gBAGnB,OAAO,GAAE;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;KACZ;IAKR,OAAO,CAAC,aAAa;YAYP,cAAc;YAWd,qBAAqB;YA0BrB,WAAW;IA8BzB,OAAO,CAAC,aAAa;IAgBrB,OAAO,CAAC,mBAAmB;IAmDrB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA4BtD,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAS1F,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAkBtH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAcxB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC;IA0BvE,wBAAwB,CAC5B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,cAAc,CAAC;CAoB3B"}

package/dist/docdex/DocdexClient.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import path from "node:path";
 import { promises as fs } from "node:fs";
+import { resolveDocdexBaseUrl, runDocdex } from "./DocdexRuntime.js";
 const nowIso = () => new Date().toISOString();
 const segmentize = (docId, content) => {
     const lines = content.split(/\r?\n/);
@@ -33,15 +34,30 @@ const segmentize = (docId, content) => {
     flush();
     return segments;
 };
+const inferDocType = (docPath, fallback = "DOC") => {
+    if (!docPath)
+        return fallback;
+    const name = path.basename(docPath).toLowerCase();
+    if (name.includes("openapi") || name.includes("swagger"))
+        return "OPENAPI";
+    if (name.includes("sds"))
+        return "SDS";
+    if (name.includes("pdr"))
+        return "PDR";
+    if (name.includes("rfp"))
+        return "RFP";
+    return fallback;
+};
+const normalizeBaseUrl = (value) => {
+    if (!value)
+        return value;
+    return value.endsWith("/") ? value.slice(0, -1) : value;
+};
 export class DocdexClient {
     constructor(options = {}) {
         this.options = options;
-    }
-    getStorePath() {
-        const base = this.options.storePath
-            ? path.resolve(this.options.storePath)
-            : path.join(this.options.workspaceRoot ?? process.cwd(), ".mcoda", "docdex", "documents.json");
-        return base;
+        this.initializing = false;
+        this.repoId = options.repoId;
     }
     normalizePath(inputPath) {
         if (!inputPath)
@@ -55,162 +71,264 @@ export class DocdexClient {
         }
         return absolute;
     }
-    async loadStore() {
-        const storePath = this.getStorePath();
+    async resolveBaseUrl() {
+        if (this.options.baseUrl !== undefined) {
+            const trimmed = this.options.baseUrl.trim();
+            return trimmed ? normalizeBaseUrl(trimmed) : undefined;
+        }
+        if (this.resolvedBaseUrl !== undefined)
+            return this.resolvedBaseUrl;
+        const resolved = await resolveDocdexBaseUrl({ cwd: this.options.workspaceRoot });
+        this.resolvedBaseUrl = resolved ? normalizeBaseUrl(resolved) : undefined;
+        return this.resolvedBaseUrl;
+    }
+    async ensureRepoInitialized(baseUrl, force = false) {
+        if ((this.repoId && !force) || this.initializing)
+            return;
+        if (!this.options.workspaceRoot)
+            return;
+        this.initializing = true;
         try {
-            const raw = await fs.readFile(storePath, "utf8");
-            const parsed = JSON.parse(raw);
-            parsed.documents = parsed.documents ?? [];
-            parsed.segments = parsed.segments ?? [];
-            return parsed;
+            const rootUri = `file://${path.resolve(this.options.workspaceRoot)}`;
+            const response = await fetch(`${baseUrl}/v1/initialize`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ rootUri }),
+            });
+            if (!response.ok)
+                return;
+            const payload = (await response.json().catch(() => undefined));
+            const repoId = payload?.repoId ??
+                payload?.repo_id ??
+                payload?.repo ??
+                payload?.id;
+            if (repoId)
+                this.repoId = String(repoId);
         }
         catch {
-            return { updatedAt: nowIso(), documents: [], segments: [] };
+            // ignore initialize errors; assume single-repo daemon
+        }
+        finally {
+            this.initializing = false;
         }
     }
     async fetchRemote(pathname, init) {
-        if (!this.options.baseUrl)
-            throw new Error("Docdex baseUrl not configured");
-        const url = new URL(pathname, this.options.baseUrl);
-        const headers = { "Content-Type": "application/json" };
-        if (this.options.authToken)
-            headers.authorization = `Bearer ${this.options.authToken}`;
-        const response = await fetch(url, { ...init, headers: { ...headers, ...init?.headers } });
+        const baseUrl = await this.resolveBaseUrl();
+        if (!baseUrl) {
+            throw new Error("Docdex baseUrl not configured. Run docdex setup or set MCODA_DOCDEX_URL.");
+        }
+        await this.ensureRepoInitialized(baseUrl);
+        const url = new URL(pathname, baseUrl);
+        const buildHeaders = () => {
+            const headers = { "Content-Type": "application/json" };
+            if (this.options.authToken)
+                headers.authorization = `Bearer ${this.options.authToken}`;
+            if (this.repoId)
+                headers["x-docdex-repo-id"] = this.repoId;
+            return { ...headers, ...init?.headers };
+        };
+        const response = await fetch(url, { ...init, headers: buildHeaders() });
         if (!response.ok) {
-            throw new Error(`Docdex request failed (${response.status}): ${await response.text()}`);
+            const message = await response.text();
+            if (message.includes("missing_repo")) {
+                await this.ensureRepoInitialized(baseUrl, true);
+                if (this.repoId) {
+                    const retry = await fetch(url, { ...init, headers: buildHeaders() });
+                    if (retry.ok)
+                        return retry;
+                    const retryMessage = await retry.text();
+                    throw new Error(`Docdex request failed (${retry.status}): ${retryMessage}`);
+                }
+            }
+            throw new Error(`Docdex request failed (${response.status}): ${message}`);
         }
-        return (await response.json());
+        return response;
     }
-    async saveStore(store) {
-        const storePath = this.getStorePath();
-        await fs.mkdir(path.dirname(storePath), { recursive: true });
-        const payload = { ...store, updatedAt: nowIso() };
-        await fs.writeFile(storePath, JSON.stringify(payload, null, 2), "utf8");
+    buildLocalDoc(docType, docPath, content, metadata) {
+        const now = nowIso();
+        const id = `local-${randomUUID()}`;
+        return {
+            id,
+            docType,
+            path: docPath,
+            title: docPath ? path.basename(docPath) : undefined,
+            content,
+            metadata,
+            createdAt: now,
+            updatedAt: now,
+            segments: segmentize(id, content),
+        };
+    }
+    coerceSearchResults(raw, fallbackDocType) {
+        const items = Array.isArray(raw)
+            ? raw
+            : Array.isArray(raw?.results)
+                ? raw.results
+                : Array.isArray(raw?.hits)
+                    ? raw.hits
+                    : [];
+        const now = nowIso();
+        return items
+            .map((item, idx) => {
+            if (!item || typeof item !== "object")
+                return undefined;
+            const id = (item.doc_id ?? item.docId ?? item.id ?? `doc-${idx + 1}`);
+            const pathValue = (item.path ?? item.file ?? item.rel_path ?? item.file_path);
+            const title = (item.title ?? item.name ?? item.file_name);
+            const docType = (item.doc_type ?? item.docType ?? item.type ?? inferDocType(pathValue, fallbackDocType ?? "DOC"));
+            const snippet = (item.snippet ?? item.summary ?? item.excerpt);
+            const content = (item.content ?? snippet);
+            const segments = Array.isArray(item.segments)
+                ? item.segments.map((seg, segIdx) => ({
+                    id: seg.id ?? `${id}-seg-${segIdx + 1}`,
+                    docId: id,
+                    index: segIdx,
+                    content: seg.content ?? seg.text ?? "",
+                    heading: seg.heading ?? seg.title ?? undefined,
+                }))
+                : snippet
+                    ? [
+                        {
+                            id: `${id}-seg-1`,
+                            docId: id,
+                            index: 0,
+                            content: snippet,
+                            heading: undefined,
+                        },
+                    ]
+                    : undefined;
+            return {
+                id,
+                docType,
+                path: pathValue,
+                title,
+                content,
+                createdAt: item.created_at ?? item.createdAt ?? now,
+                updatedAt: item.updated_at ?? item.updatedAt ?? now,
+                segments,
+            };
+        })
+            .filter(Boolean);
     }
     async fetchDocumentById(id) {
-        if (this.options.baseUrl) {
+        const response = await this.fetchRemote(`/snippet/${encodeURIComponent(id)}?text_only=true`);
+        const contentType = response.headers.get("content-type") ?? "";
+        const body = await response.text();
+        let content = body;
+        if (contentType.includes("application/json")) {
             try {
-                const doc = await this.fetchRemote(`/documents/${id}`);
-                return doc;
+                const parsed = JSON.parse(body);
+                content =
+                    parsed.text ??
+                        parsed.content ??
+                        parsed.snippet ??
+                        body;
             }
-            catch (error) {
-                // fall through to local if remote fails
-                // eslint-disable-next-line no-console
-                console.warn(`Docdex remote fetch failed, falling back to local: ${error.message}`);
+            catch {
+                content = body;
             }
         }
-        const store = await this.loadStore();
-        const doc = store.documents.find((d) => d.id === id);
-        if (!doc) {
-            throw new Error(`Docdex document not found: ${id}`);
-        }
-        const segments = store.segments.filter((s) => s.docId === id);
-        return { ...doc, segments };
+        const now = nowIso();
+        return {
+            id,
+            docType: "DOC",
+            content,
+            createdAt: now,
+            updatedAt: now,
+            segments: content ? segmentize(id, content) : undefined,
+        };
     }
     async findDocumentByPath(docPath, docType) {
         const normalized = this.normalizePath(docPath);
-        const store = await this.loadStore();
-        const doc = store.documents.find((d) => d.path === normalized && (!docType || d.docType.toLowerCase() === docType.toLowerCase()));
-        if (!doc)
+        const query = normalized ?? docPath;
+        const docs = await this.search({ query, docType });
+        if (!docs.length)
             return undefined;
-        return { ...doc, segments: store.segments.filter((s) => s.docId === doc.id) };
+        if (!normalized)
+            return docs[0];
+        return docs.find((doc) => doc.path === normalized) ?? docs[0];
     }
     async search(filter) {
-        if (this.options.baseUrl) {
-            try {
-                const params = new URLSearchParams();
-                if (filter.docType)
-                    params.set("doc_type", filter.docType);
-                if (filter.projectKey)
-                    params.set("project_key", filter.projectKey);
-                if (filter.query)
-                    params.set("q", filter.query);
-                if (filter.profile)
-                    params.set("profile", filter.profile);
-                const path = `/documents?${params.toString()}`;
-                const docs = await this.fetchRemote(path);
-                return docs;
-            }
-            catch (error) {
-                // eslint-disable-next-line no-console
-                console.warn(`Docdex remote search failed, falling back to local: ${error.message}`);
-            }
+        const params = new URLSearchParams();
+        const queryParts = [filter.query, filter.docType, filter.projectKey].filter(Boolean);
+        const query = queryParts.join(" ").trim();
+        if (query)
+            params.set("q", query);
+        if (filter.profile)
+            params.set("profile", filter.profile);
+        if (filter.docType)
+            params.set("doc_type", filter.docType);
+        if (filter.projectKey)
+            params.set("project_key", filter.projectKey);
+        params.set("limit", "8");
+        const baseUrl = await this.resolveBaseUrl();
+        if (!baseUrl) {
+            return [];
         }
-        const store = await this.loadStore();
-        return store.documents
-            .filter((doc) => {
-            if (filter.docType && doc.docType.toLowerCase() !== filter.docType.toLowerCase())
-                return false;
-            if (filter.projectKey && doc.metadata && doc.metadata.projectKey !== filter.projectKey)
-                return false;
-            return true;
-        })
-            .map((doc) => ({ ...doc, segments: store.segments.filter((s) => s.docId === doc.id) }));
+        const response = await this.fetchRemote(`/search?${params.toString()}`);
+        const payload = (await response.json());
+        return this.coerceSearchResults(payload, filter.docType);
+    }
+    async reindex() {
+        const repoRoot = this.options.workspaceRoot ?? process.cwd();
+        const baseUrl = await this.resolveBaseUrl();
+        await runDocdex(["index", "--repo", repoRoot], {
+            cwd: repoRoot,
+            env: baseUrl
+                ? {
+                    DOCDEX_URL: baseUrl,
+                    MCODA_DOCDEX_URL: baseUrl,
+                }
+                : undefined,
+        });
     }
     async registerDocument(input) {
-        if (this.options.baseUrl) {
-            try {
-                const registered = await this.fetchRemote(`/documents`, {
-                    method: "POST",
-                    body: JSON.stringify({
-                        doc_type: input.docType,
-                        path: input.path,
-                        title: input.title,
-                        content: input.content,
-                        metadata: input.metadata,
-                    }),
-                });
-                return registered;
-            }
-            catch (error) {
-                // eslint-disable-next-line no-console
-                console.warn(`Docdex remote register failed, falling back to local: ${error.message}`);
-            }
+        const baseUrl = await this.resolveBaseUrl();
+        if (!baseUrl) {
+            const normalized = input.path ? this.normalizePath(input.path) ?? input.path : undefined;
+            return this.buildLocalDoc(input.docType, normalized, input.content, input.metadata);
         }
-        const store = await this.loadStore();
-        const normalizedPath = this.normalizePath(input.path);
-        const existingByPath = normalizedPath
-            ? store.documents.find((d) => d.path === normalizedPath &&
-                d.docType.toLowerCase() === input.docType.toLowerCase() &&
-                (input.metadata?.projectKey ? d.metadata?.projectKey === input.metadata.projectKey : true))
-            : undefined;
-        const now = nowIso();
-        if (existingByPath) {
-            const updated = {
-                ...existingByPath,
-                content: input.content ?? existingByPath.content,
-                metadata: { ...(existingByPath.metadata ?? {}), ...(input.metadata ?? {}) },
-                title: input.title ?? existingByPath.title,
-                updatedAt: now,
-            };
-            const segments = segmentize(updated.id, input.content);
-            store.documents[store.documents.findIndex((d) => d.id === existingByPath.id)] = updated;
-            store.segments = store.segments.filter((s) => s.docId !== updated.id).concat(segments);
-            await this.saveStore(store);
-            return { ...updated, segments };
-        }
-        const doc = {
-            id: randomUUID(),
-            docType: input.docType,
-            path: normalizedPath,
-            content: input.content,
-            metadata: input.metadata,
-            title: input.title,
-            createdAt: now,
-            updatedAt: now,
-        };
-        const segments = segmentize(doc.id, input.content);
-        store.documents.push(doc);
-        store.segments.push(...segments);
-        await this.saveStore(store);
-        return { ...doc, segments };
+        if (!input.path) {
+            throw new Error("Docdex register requires a file path to ingest.");
+        }
+        await this.ensureRepoInitialized(baseUrl);
+        const resolvedPath = path.isAbsolute(input.path)
+            ? input.path
+            : path.join(this.options.workspaceRoot ?? process.cwd(), input.path);
+        const repoRoot = this.options.workspaceRoot ?? process.cwd();
+        await runDocdex(["ingest", "--repo", repoRoot, "--file", resolvedPath], {
+            cwd: repoRoot,
+            env: {
+                DOCDEX_URL: baseUrl,
+                MCODA_DOCDEX_URL: baseUrl,
+            },
+        });
+        const registered = await this.findDocumentByPath(resolvedPath, input.docType).catch(() => undefined);
+        if (registered)
+            return registered;
+        return this.buildLocalDoc(input.docType, resolvedPath, input.content, input.metadata);
     }
     async ensureRegisteredFromFile(docPath, docType, metadata) {
         const normalizedPath = this.normalizePath(docPath) ?? docPath;
-        const existing = await this.findDocumentByPath(normalizedPath, docType);
-        if (existing)
-            return existing;
+        try {
+            const existing = await this.findDocumentByPath(normalizedPath, docType);
+            if (existing)
+                return existing;
+        }
+        catch {
+            // ignore docdex lookup failures; fall back to local
+        }
         const content = await fs.readFile(docPath, "utf8");
-        return this.registerDocument({ docType, path: docPath, content, metadata });
+        const inferredType = docType || inferDocType(docPath);
+        const baseUrl = await this.resolveBaseUrl();
+        if (!baseUrl) {
+            return this.buildLocalDoc(inferredType, normalizedPath, content, metadata);
+        }
+        try {
+            return await this.registerDocument({ docType: inferredType, path: docPath, content, metadata });
+        }
+        catch {
+            return this.buildLocalDoc(inferredType, normalizedPath, content, metadata);
+        }
     }
 }

package/dist/docdex/DocdexRuntime.d.ts

@@ -0,0 +1,42 @@
+export interface DocdexCheckResult {
+    status?: string;
+    success?: boolean;
+    checks?: Array<{
+        name?: string;
+        status?: string;
+        message?: string;
+        details?: Record<string, unknown>;
+    }>;
+}
+export interface DocdexBrowserInfo {
+    ok: boolean;
+    message?: string;
+    browsersPath?: string;
+    browsers?: Array<{
+        name?: string;
+        path?: string;
+        version?: string;
+    }>;
+}
+export declare const resolveDocdexBinary: () => string | undefined;
+export declare const resolvePlaywrightCli: () => string | undefined;
+export declare const runDocdex: (args: string[], options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare const readDocdexCheck: (options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}) => Promise<DocdexCheckResult>;
+export declare const resolveDocdexBaseUrl: (options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}) => Promise<string | undefined>;
+export declare const resolveDocdexBrowserInfo: (options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}) => Promise<DocdexBrowserInfo>;
+//# sourceMappingURL=DocdexRuntime.d.ts.map

package/dist/docdex/DocdexRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocdexRuntime.d.ts","sourceRoot":"","sources":["../../src/docdex/DocdexRuntime.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,KAAK,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtE;AAuBD,eAAO,MAAM,mBAAmB,QAAO,MAAM,GAAG,SAI/C,CAAC;AAEF,eAAO,MAAM,oBAAoB,QAAO,MAAM,GAAG,SAehD,CAAC;AAEF,eAAO,MAAM,SAAS,GACpB,MAAM,MAAM,EAAE,EACd,UAAS;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAO,KACtD,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAU5C,CAAC;AAEF,eAAO,MAAM,eAAe,GAAU,UAAS;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAO,KAAG,OAAO,CAAC,iBAAiB,CAsBxH,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAU,UAAS;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAO,KAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAsB9H,CAAC;AAEF,eAAO,MAAM,wBAAwB,GACnC,UAAS;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAO,KACtD,OAAO,CAAC,iBAAiB,CAgC3B,CAAC"}

package/dist/docdex/DocdexRuntime.js

@@ -0,0 +1,145 @@
+import path from "node:path";
+import os from "node:os";
+import { createRequire } from "node:module";
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+const execFile = promisify(execFileCb);
+const DOCDEX_ENV_URLS = ["MCODA_DOCDEX_URL", "DOCDEX_URL"];
+const DEFAULT_DOCDEX_STATE_DIR = path.join(os.homedir(), ".docdex", "state");
+const buildDocdexEnv = (env) => {
+    const merged = { ...process.env, ...(env ?? {}) };
+    if (!merged.DOCDEX_STATE_DIR) {
+        merged.DOCDEX_STATE_DIR = DEFAULT_DOCDEX_STATE_DIR;
+    }
+    return merged;
+};
+const resolveDocdexPackageRoot = () => {
+    try {
+        const require = createRequire(import.meta.url);
+        const pkgPath = require.resolve("docdex/package.json");
+        return path.dirname(pkgPath);
+    }
+    catch {
+        return undefined;
+    }
+};
+export const resolveDocdexBinary = () => {
+    const root = resolveDocdexPackageRoot();
+    if (!root)
+        return undefined;
+    return path.join(root, "bin", "docdex.js");
+};
+export const resolvePlaywrightCli = () => {
+    const require = createRequire(import.meta.url);
+    try {
+        return require.resolve("playwright/cli.js");
+    }
+    catch {
+        // fall through to docdex-local resolution
+    }
+    const root = resolveDocdexPackageRoot();
+    if (!root)
+        return undefined;
+    try {
+        const requireFromDocdex = createRequire(path.join(root, "package.json"));
+        return requireFromDocdex.resolve("playwright/cli.js");
+    }
+    catch {
+        return undefined;
+    }
+};
+export const runDocdex = async (args, options = {}) => {
+    const binary = resolveDocdexBinary();
+    if (!binary) {
+        throw new Error("Docdex npm package not found. Install docdex and retry.");
+    }
+    const { stdout, stderr } = await execFile(process.execPath, [binary, ...args], {
+        cwd: options.cwd,
+        env: buildDocdexEnv(options.env),
+    });
+    return { stdout: stdout ?? "", stderr: stderr ?? "" };
+};
+export const readDocdexCheck = async (options = {}) => {
+    let stdout = "";
+    let stderr = "";
+    try {
+        ({ stdout, stderr } = await runDocdex(["check"], options));
+    }
+    catch (error) {
+        const execError = error;
+        stdout = typeof execError.stdout === "string" ? execError.stdout : execError.stdout?.toString() ?? "";
+        stderr = typeof execError.stderr === "string" ? execError.stderr : execError.stderr?.toString() ?? "";
+        if (!stdout && !stderr) {
+            throw error;
+        }
+    }
+    const trimmed = stdout.trim() || stderr.trim();
+    if (!trimmed) {
+        throw new Error("Docdex check returned empty output");
+    }
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch (error) {
+        throw new Error(`Docdex check returned invalid JSON: ${error.message}`);
+    }
+};
+export const resolveDocdexBaseUrl = async (options = {}) => {
+    for (const key of DOCDEX_ENV_URLS) {
+        const envValue = process.env[key];
+        if (envValue)
+            return envValue;
+    }
+    if (process.env.MCODA_SKIP_DOCDEX_CHECKS === "1" ||
+        process.env.MCODA_SKIP_DOCDEX_RUNTIME_CHECKS === "1" ||
+        (process.platform === "win32" && process.env.CI)) {
+        return undefined;
+    }
+    try {
+        const check = await readDocdexCheck(options);
+        const bind = check.checks?.find((c) => c.name === "bind")?.details;
+        const bindAddr = bind?.bind_addr;
+        if (!bindAddr)
+            return undefined;
+        if (bindAddr.startsWith("http://") || bindAddr.startsWith("https://"))
+            return bindAddr;
+        return `http://${bindAddr}`;
+    }
+    catch {
+        return undefined;
+    }
+};
+export const resolveDocdexBrowserInfo = async (options = {}) => {
+    const setupHint = "Run `docdex setup` to install Playwright and at least one browser.";
+    try {
+        const check = await readDocdexCheck(options);
+        const browserCheck = check.checks?.find((c) => c.name === "browser");
+        if (!browserCheck || browserCheck.status !== "ok") {
+            return {
+                ok: false,
+                message: `${browserCheck?.message ?? "Docdex browser check failed."} ${setupHint}`,
+            };
+        }
+        const details = browserCheck.details ?? {};
+        const playwright = details.playwright ?? {};
+        const browsers = Array.isArray(playwright.browsers) ? playwright.browsers : [];
+        if (!browsers.length) {
+            return {
+                ok: false,
+                message: `Docdex has no Playwright browsers configured. ${setupHint}`,
+            };
+        }
+        const browsersPath = typeof playwright.browsers_path === "string" ? playwright.browsers_path : undefined;
+        return {
+            ok: true,
+            browsersPath,
+            browsers,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: `Docdex check failed: ${error.message}. ${setupHint}`,
+        };
+    }
+};

package/dist/qa/ChromiumQaAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChromiumQaAdapter.d.ts","sourceRoot":"","sources":["../../src/qa/ChromiumQaAdapter.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAOtE,qBAAa,iBAAkB,YAAW,SAAS;IACjD,OAAO,CAAC,UAAU;IASZ,eAAe,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC;YAiBpE,WAAW;IAYnB,MAAM,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;CAqCvE"}
+{"version":3,"file":"ChromiumQaAdapter.d.ts","sourceRoot":"","sources":["../../src/qa/ChromiumQaAdapter.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAQtE,qBAAa,iBAAkB,YAAW,SAAS;IACjD,OAAO,CAAC,UAAU;IASZ,eAAe,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC;YAqBpE,WAAW;IAYnB,MAAM,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;CA8CvE"}

package/dist/qa/ChromiumQaAdapter.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { exec as execCb } from 'node:child_process';
 import { promisify } from 'node:util';
 import fs from 'node:fs/promises';
+import { resolveDocdexBrowserInfo, resolvePlaywrightCli } from '../docdex/DocdexRuntime.js';
 const exec = promisify(execCb);
 const shouldSkipInstall = (ctx) => process.env.MCODA_QA_SKIP_INSTALL === '1' || ctx.env?.MCODA_QA_SKIP_INSTALL === '1';
 export class ChromiumQaAdapter {
@@ -17,20 +18,21 @@ export class ChromiumQaAdapter {
         if (shouldSkipInstall(ctx))
             return { ok: true, details: { skipped: true } };
         const cwd = this.resolveCwd(profile, ctx);
-        try {
-            await exec('npx playwright --version', { cwd, env: { ...process.env, ...profile.env, ...ctx.env } });
-            return { ok: true };
-        }
-        catch (versionError) {
-            const installCommand = profile.install_command ?? 'npx playwright install chromium';
-            try {
-                await exec(installCommand, { cwd, env: { ...process.env, ...profile.env, ...ctx.env } });
-                return { ok: true, details: { installedVia: installCommand } };
-            }
-            catch (error) {
-                return { ok: false, message: error?.message ?? versionError?.message ?? 'Chromium QA install failed' };
-            }
+        const browserInfo = await resolveDocdexBrowserInfo({ cwd });
+        if (!browserInfo.ok) {
+            return {
+                ok: false,
+                message: browserInfo.message ??
+                    'Playwright browsers not installed. Run `docdex setup` and install Playwright with at least one browser.',
+            };
         }
+        return {
+            ok: true,
+            details: {
+                playwrightBrowsersPath: browserInfo.browsersPath,
+                browsers: browserInfo.browsers,
+            },
+        };
     }
     async persistLogs(ctx, stdout, stderr) {
         const artifacts = [];
@@ -45,13 +47,22 @@ export class ChromiumQaAdapter {
         return artifacts;
     }
     async invoke(profile, ctx) {
-        const command = ctx.testCommandOverride ?? profile.test_command ?? 'npx playwright test --reporter=list';
+        const playwrightCli = resolvePlaywrightCli();
+        const defaultCommand = playwrightCli
+            ? `node ${playwrightCli} test --reporter=list`
+            : 'npx playwright test --reporter=list';
+        const command = ctx.testCommandOverride ?? profile.test_command ?? defaultCommand;
         const startedAt = new Date().toISOString();
         const cwd = this.resolveCwd(profile, ctx);
         try {
             const { stdout, stderr } = await exec(command, {
                 cwd,
-                env: { ...process.env, ...profile.env, ...ctx.env },
+                env: {
+                    ...process.env,
+                    ...profile.env,
+                    ...ctx.env,
+                    PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD ?? '1',
+                },
             });
             const finishedAt = new Date().toISOString();
             const artifacts = await this.persistLogs(ctx, stdout, stderr);

package/dist/vcs/VcsClient.d.ts

@@ -17,12 +17,13 @@ export declare class VcsClient {
         noGpgSign?: boolean;
     }): Promise<void>;
     merge(cwd: string, source: string, target: string, ensureClean?: boolean): Promise<void>;
+    abortMerge(cwd: string): Promise<void>;
     push(cwd: string, remote: string, branch: string): Promise<void>;
     pull(cwd: string, remote: string, branch: string, ffOnly?: boolean): Promise<void>;
     status(cwd: string): Promise<string>;
     dirtyPaths(cwd: string): Promise<string[]>;
     conflictPaths(cwd: string): Promise<string[]>;
-    ensureClean(cwd: string, ignoreDotMcoda?: boolean): Promise<void>;
+    ensureClean(cwd: string, ignoreDotMcoda?: boolean, ignorePaths?: string[]): Promise<void>;
     lastCommitSha(cwd: string): Promise<string>;
     diff(cwd: string, base: string, head: string, paths?: string[]): Promise<string>;
 }

package/dist/vcs/VcsClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VcsClient.d.ts","sourceRoot":"","sources":["../../src/vcs/VcsClient.ts"],"names":[],"mappings":"AAQA,qBAAa,SAAS;YACN,MAAM;YAKN,YAAY;IASpB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASxC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IASlD,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;YASnD,UAAU;YASV,gBAAgB;IAaxB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY1D,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1D,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQhF,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBrD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,MAAM,CACV,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAO,GACxD,OAAO,CAAC,IAAI,CAAC;IAOV,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAQtF,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,UAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/E,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKpC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAsB1C,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAS7C,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,UAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9D,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK3C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;CAQvF"}
+{"version":3,"file":"VcsClient.d.ts","sourceRoot":"","sources":["../../src/vcs/VcsClient.ts"],"names":[],"mappings":"AAQA,qBAAa,SAAS;YACN,MAAM;YAKN,YAAY;IASpB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASxC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IASlD,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;YASnD,UAAU;YASV,gBAAgB;IAaxB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY1D,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1D,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQhF,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBrD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,MAAM,CACV,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAO,GACxD,OAAO,CAAC,IAAI,CAAC;IAOV,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAQtF,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQtC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,UAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/E,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKpC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAsB1C,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAS7C,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,UAAO,EAAE,WAAW,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAW1F,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK3C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;CAQvF"}

package/dist/vcs/VcsClient.js

@@ -103,14 +103,22 @@ export class VcsClient {
             return;
         }
         catch (error) {
-            // If the patch is already applied, a reverse --check succeeds; treat that as a no-op.
-            const reverseCheckCmd = `cat <<'__PATCH__' | git apply --reverse --check --whitespace=nowarn\n${patch}\n__PATCH__`;
+            // Retry with 3-way merge for drifted files.
+            const apply3wayCmd = `cat <<'__PATCH__' | git apply --3way --whitespace=nowarn\n${patch}\n__PATCH__`;
             try {
-                await exec(reverseCheckCmd, opts);
+                await exec(apply3wayCmd, opts);
                 return;
             }
             catch {
-                throw error;
+                // If the patch is already applied, a reverse --check succeeds; treat that as a no-op.
+                const reverseCheckCmd = `cat <<'__PATCH__' | git apply --reverse --check --whitespace=nowarn\n${patch}\n__PATCH__`;
+                try {
+                    await exec(reverseCheckCmd, opts);
+                    return;
+                }
+                catch {
+                    throw error;
+                }
             }
         }
     }
@@ -132,6 +140,14 @@ export class VcsClient {
         }
         await this.runGit(cwd, ["merge", "--no-edit", source]);
     }
+    async abortMerge(cwd) {
+        try {
+            await this.runGit(cwd, ["merge", "--abort"]);
+        }
+        catch {
+            // Ignore when no merge is in progress.
+        }
+    }
     async push(cwd, remote, branch) {
         await this.runGit(cwd, ["push", remote, branch]);
     }
@@ -179,9 +195,13 @@ export class VcsClient {
             return [];
         }
     }
-    async ensureClean(cwd, ignoreDotMcoda = true) {
+    async ensureClean(cwd, ignoreDotMcoda = true, ignorePaths = []) {
         const dirty = await this.dirtyPaths(cwd);
-        const filtered = ignoreDotMcoda ? dirty.filter((p) => !p.startsWith(".mcoda")) : dirty;
+        const filtered = dirty.filter((p) => {
+            if (ignoreDotMcoda && p.startsWith(".mcoda"))
+                return false;
+            return !ignorePaths.some((prefix) => p.startsWith(prefix));
+        });
         if (filtered.length) {
             throw new Error(`Working tree dirty: ${filtered.join(", ")}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcoda/integrations",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "External integrations for mcoda (vcs, QA, telemetry).",
   "type": "module",
   "main": "dist/index.js",
@@ -37,7 +37,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@mcoda/shared": "0.1.8"
+    "docdex": "^0.2.22",
+    "@mcoda/shared": "0.1.9"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",