@mcp-consultant-tools/azure-devops 30.0.0-beta.9 → 31.0.0-beta.2

package/build/sync/image-handler.js

@@ -0,0 +1,135 @@
+/**
+ * Image Reference Handler
+ *
+ * Detects and rewrites image references in ADO work item content.
+ *
+ * Two source forms are recognised:
+ *   - HTML <img src="..."> (raw HTML, typically pre-conversion)
+ *   - Markdown ![alt](src) (post Turndown conversion or hand-written)
+ *
+ * Each <img>/![] reference is parsed; if the URL points at an ADO work item
+ * attachment (`_apis/wit/attachments/{guid}`), we extract the GUID, fileName,
+ * and project GUID. Callers can then download the file and rewrite the source
+ * to a local relative path — or, on push, walk the manifest and rewrite local
+ * paths back to the original ADO URL.
+ */
+/**
+ * Parse an ADO work item attachment URL.
+ *
+ * Recognised patterns:
+ *   https://dev.azure.com/{org}/{projectGuid}/_apis/wit/attachments/{guid}?fileName=image.png&...
+ *   https://dev.azure.com/{org}/_apis/wit/attachments/{guid}?fileName=image.png&...
+ *
+ * Returns null when the URL is not an ADO attachment URL.
+ */
+export function parseAdoAttachmentUrl(url) {
+    // Match _apis/wit/attachments/{guid} anywhere in the URL.
+    // GUID = 8-4-4-4-12 hex chars
+    const guidPattern = /\/_apis\/wit\/attachments\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})(?:[/?#]|$)/i;
+    const guidMatch = url.match(guidPattern);
+    if (!guidMatch)
+        return null;
+    const guid = guidMatch[1];
+    // Try to extract project GUID (segment between org and _apis).
+    // dev.azure.com/{org}/{projectGuid}/_apis/...
+    let projectGuid;
+    const projectGuidPattern = /dev\.azure\.com\/[^/]+\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\/_apis\//i;
+    const projectMatch = url.match(projectGuidPattern);
+    if (projectMatch) {
+        projectGuid = projectMatch[1];
+    }
+    // Extract fileName from query string; fall back to a sensible default.
+    let fileName = 'attachment.bin';
+    try {
+        const u = new URL(url);
+        const qsName = u.searchParams.get('fileName');
+        if (qsName)
+            fileName = qsName;
+    }
+    catch {
+        const qsMatch = url.match(/[?&]fileName=([^&#]+)/);
+        if (qsMatch) {
+            try {
+                fileName = decodeURIComponent(qsMatch[1]);
+            }
+            catch {
+                fileName = qsMatch[1];
+            }
+        }
+    }
+    return { guid, fileName, projectGuid, originalUrl: url };
+}
+/**
+ * Extract every image reference from a string of HTML or markdown content.
+ *
+ * Returns refs in source order. Both HTML <img> tags and markdown ![]() are
+ * detected. Refs whose URL parses as an ADO attachment have `adoAttachment`
+ * populated.
+ */
+export function extractImageRefs(content) {
+    if (!content)
+        return [];
+    const refs = [];
+    // HTML <img src="..."> — handles both " and ' delimiters and self-closing
+    const htmlRegex = /<img[^>]*\bsrc\s*=\s*(?:"([^"]+)"|'([^']+)')[^>]*\/?>/gi;
+    let m;
+    while ((m = htmlRegex.exec(content)) !== null) {
+        const src = m[1] || m[2];
+        if (!src)
+            continue;
+        refs.push({
+            originalSrc: src,
+            isHtmlTag: true,
+            index: m.index,
+            length: m[0].length,
+            adoAttachment: parseAdoAttachmentUrl(src) ?? undefined,
+        });
+    }
+    // Markdown ![alt](url) — url terminates at whitespace or close paren
+    const mdRegex = /!\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+    while ((m = mdRegex.exec(content)) !== null) {
+        const src = m[1];
+        if (!src)
+            continue;
+        refs.push({
+            originalSrc: src,
+            isHtmlTag: false,
+            index: m.index,
+            length: m[0].length,
+            adoAttachment: parseAdoAttachmentUrl(src) ?? undefined,
+        });
+    }
+    return refs.sort((a, b) => a.index - b.index);
+}
+/**
+ * Rewrite image src/url values in content using a mapper function.
+ *
+ * The mapper receives the original src and the parsed ADO attachment (if any)
+ * and returns the new src to substitute. Returning null/undefined leaves the
+ * original src in place.
+ *
+ * Both HTML <img src="..."> and markdown ![](src) forms are rewritten.
+ */
+export function rewriteImageSrcs(content, mapper) {
+    if (!content)
+        return content;
+    // Rewrite HTML <img src="...">
+    let result = content.replace(/(<img[^>]*\bsrc\s*=\s*)(?:"([^"]+)"|'([^']+)')([^>]*\/?>)/gi, (_match, before, dq, sq, after) => {
+        const src = dq ?? sq;
+        const ado = parseAdoAttachmentUrl(src) ?? undefined;
+        const newSrc = mapper(src, ado);
+        const finalSrc = newSrc ?? src;
+        // Preserve the original quote style
+        const quote = dq !== undefined ? '"' : "'";
+        return `${before}${quote}${finalSrc}${quote}${after}`;
+    });
+    // Rewrite markdown ![alt](url "optional title")
+    result = result.replace(/(!\[[^\]]*\]\()([^)\s]+)((?:\s+"[^"]*")?\))/g, (_match, before, src, after) => {
+        const ado = parseAdoAttachmentUrl(src) ?? undefined;
+        const newSrc = mapper(src, ado);
+        const finalSrc = newSrc ?? src;
+        return `${before}${finalSrc}${after}`;
+    });
+    return result;
+}
+//# sourceMappingURL=image-handler.js.map

package/build/sync/image-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-handler.js","sourceRoot":"","sources":["../../src/sync/image-handler.ts"],"names":[],"mappings":"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"}

package/build/sync/image-manifest.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Image Attachment Manifest
+ *
+ * Per-work-item record of attachment files synced between local disk and ADO.
+ * Stored at `{syncFolder}/{workItemId}/.attachments.json`.
+ *
+ * The manifest is the source of truth for "is this image already on ADO?":
+ *   - On pull: each downloaded ADO attachment is recorded with `source: "ado-pull"`.
+ *   - On push: when a local image src matches a manifest entry, the original
+ *     ADO URL is reused (no re-upload). When it doesn't match, the file is
+ *     uploaded as a new attachment and added with `source: "local-uploaded"`.
+ */
+export type AttachmentSource = 'ado-pull' | 'local-uploaded';
+export interface AttachmentManifestEntry {
+    /** ADO attachment GUID */
+    guid: string;
+    /** Original filename as stored in ADO */
+    fileName: string;
+    /** Path relative to the work item folder (e.g. "attachments/{guid}-image.png") */
+    localPath: string;
+    /** Original ADO attachment URL (used to re-reference on push) */
+    originalUrl: string;
+    /** Where the entry came from */
+    source: AttachmentSource;
+    /** ADO field reference name where the image was first seen (informational) */
+    field?: string;
+    /** ISO timestamp of upload (for local-uploaded entries) */
+    uploadedAt?: string;
+}
+export interface AttachmentManifest {
+    workItemId: number;
+    lastSyncedAt: string;
+    attachments: AttachmentManifestEntry[];
+}
+/** Folder for a work item's attachments + manifest. */
+export declare function getWorkItemAttachmentDir(syncFolder: string, workItemId: number): string;
+/** Folder where the binary attachment files live. */
+export declare function getAttachmentsBinDir(syncFolder: string, workItemId: number): string;
+/** Path to the manifest JSON file. */
+export declare function getManifestPath(syncFolder: string, workItemId: number): string;
+/**
+ * Build the local relative path for a downloaded attachment.
+ * Example: `attachments/5e5c125f-...-image.png`.
+ *
+ * The GUID prefix keeps filenames unique even when ADO returns generic names
+ * like "image.png" for many different attachments.
+ */
+export declare function buildLocalAttachmentPath(guid: string, fileName: string): string;
+/** Read manifest from disk. Returns an empty manifest if the file is missing. */
+export declare function readManifest(syncFolder: string, workItemId: number): Promise<AttachmentManifest>;
+/** Write manifest to disk, creating the parent directory if needed. */
+export declare function writeManifest(syncFolder: string, manifest: AttachmentManifest): Promise<void>;
+/**
+ * Add (or replace) an entry in the manifest. Lookup is by `guid` — the same
+ * attachment is never recorded twice. Returns the manifest unchanged when an
+ * existing entry has the same guid AND localPath, otherwise replaces it.
+ */
+export declare function upsertEntry(manifest: AttachmentManifest, entry: AttachmentManifestEntry): AttachmentManifest;
+/**
+ * Look up a manifest entry by its local path (relative to the work item folder).
+ * Used on push to recognise images that came from ADO and avoid re-uploading.
+ */
+export declare function findEntryByLocalPath(manifest: AttachmentManifest, localPath: string): AttachmentManifestEntry | undefined;
+/** Look up an entry by its original ADO URL. */
+export declare function findEntryByAdoUrl(manifest: AttachmentManifest, url: string): AttachmentManifestEntry | undefined;
+//# sourceMappingURL=image-manifest.d.ts.map

package/build/sync/image-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-manifest.d.ts","sourceRoot":"","sources":["../../src/sync/image-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,gBAAgB,CAAC;AAE7D,MAAM,WAAW,uBAAuB;IACtC,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,MAAM,EAAE,gBAAgB,CAAC;IACzB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,uBAAuB,EAAE,CAAC;CACxC;AAKD,uDAAuD;AACvD,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEvF;AAED,qDAAqD;AACrD,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEnF;AAED,sCAAsC;AACtC,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,iFAAiF;AACjF,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAiBtG;AAED,uEAAuE;AACvE,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMnG;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,kBAAkB,EAAE,KAAK,EAAE,uBAAuB,GAAG,kBAAkB,CAQ5G;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS,CAKzH;AAED,gDAAgD;AAChD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS,CAEhH"}

package/build/sync/image-manifest.js

@@ -0,0 +1,96 @@
+/**
+ * Image Attachment Manifest
+ *
+ * Per-work-item record of attachment files synced between local disk and ADO.
+ * Stored at `{syncFolder}/{workItemId}/.attachments.json`.
+ *
+ * The manifest is the source of truth for "is this image already on ADO?":
+ *   - On pull: each downloaded ADO attachment is recorded with `source: "ado-pull"`.
+ *   - On push: when a local image src matches a manifest entry, the original
+ *     ADO URL is reused (no re-upload). When it doesn't match, the file is
+ *     uploaded as a new attachment and added with `source: "local-uploaded"`.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+const MANIFEST_FILENAME = '.attachments.json';
+const ATTACHMENTS_SUBDIR = 'attachments';
+/** Folder for a work item's attachments + manifest. */
+export function getWorkItemAttachmentDir(syncFolder, workItemId) {
+    return path.join(syncFolder, String(workItemId));
+}
+/** Folder where the binary attachment files live. */
+export function getAttachmentsBinDir(syncFolder, workItemId) {
+    return path.join(getWorkItemAttachmentDir(syncFolder, workItemId), ATTACHMENTS_SUBDIR);
+}
+/** Path to the manifest JSON file. */
+export function getManifestPath(syncFolder, workItemId) {
+    return path.join(getWorkItemAttachmentDir(syncFolder, workItemId), MANIFEST_FILENAME);
+}
+/**
+ * Build the local relative path for a downloaded attachment.
+ * Example: `attachments/5e5c125f-...-image.png`.
+ *
+ * The GUID prefix keeps filenames unique even when ADO returns generic names
+ * like "image.png" for many different attachments.
+ */
+export function buildLocalAttachmentPath(guid, fileName) {
+    return path.posix.join(ATTACHMENTS_SUBDIR, `${guid}-${fileName}`);
+}
+/** Read manifest from disk. Returns an empty manifest if the file is missing. */
+export async function readManifest(syncFolder, workItemId) {
+    const manifestPath = getManifestPath(syncFolder, workItemId);
+    try {
+        const raw = await fs.readFile(manifestPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null || !Array.isArray(parsed.attachments)) {
+            throw new Error('Malformed manifest');
+        }
+        return parsed;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return { workItemId, lastSyncedAt: new Date().toISOString(), attachments: [] };
+        }
+        // Corrupted manifest — start fresh rather than failing the sync.
+        console.error(`Warning: could not parse ${manifestPath}: ${err.message}. Starting fresh.`);
+        return { workItemId, lastSyncedAt: new Date().toISOString(), attachments: [] };
+    }
+}
+/** Write manifest to disk, creating the parent directory if needed. */
+export async function writeManifest(syncFolder, manifest) {
+    const dir = getWorkItemAttachmentDir(syncFolder, manifest.workItemId);
+    await fs.mkdir(dir, { recursive: true });
+    const manifestPath = getManifestPath(syncFolder, manifest.workItemId);
+    manifest.lastSyncedAt = new Date().toISOString();
+    await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2), 'utf-8');
+}
+/**
+ * Add (or replace) an entry in the manifest. Lookup is by `guid` — the same
+ * attachment is never recorded twice. Returns the manifest unchanged when an
+ * existing entry has the same guid AND localPath, otherwise replaces it.
+ */
+export function upsertEntry(manifest, entry) {
+    const existing = manifest.attachments.findIndex(a => a.guid === entry.guid);
+    if (existing >= 0) {
+        manifest.attachments[existing] = { ...manifest.attachments[existing], ...entry };
+    }
+    else {
+        manifest.attachments.push(entry);
+    }
+    return manifest;
+}
+/**
+ * Look up a manifest entry by its local path (relative to the work item folder).
+ * Used on push to recognise images that came from ADO and avoid re-uploading.
+ */
+export function findEntryByLocalPath(manifest, localPath) {
+    // Normalise both sides: strip leading `./` and convert backslashes.
+    const normalise = (p) => p.replace(/\\/g, '/').replace(/^\.\//, '');
+    const target = normalise(localPath);
+    return manifest.attachments.find(a => normalise(a.localPath) === target);
+}
+/** Look up an entry by its original ADO URL. */
+export function findEntryByAdoUrl(manifest, url) {
+    return manifest.attachments.find(a => a.originalUrl === url);
+}
+//# sourceMappingURL=image-manifest.js.map

package/build/sync/image-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-manifest.js","sourceRoot":"","sources":["../../src/sync/image-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AA2BlC,MAAM,iBAAiB,GAAG,mBAAmB,CAAC;AAC9C,MAAM,kBAAkB,GAAG,aAAa,CAAC;AAEzC,uDAAuD;AACvD,MAAM,UAAU,wBAAwB,CAAC,UAAkB,EAAE,UAAkB;IAC7E,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;AACnD,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,oBAAoB,CAAC,UAAkB,EAAE,UAAkB;IACzE,OAAO,IAAI,CAAC,IAAI,CAAC,wBAAwB,CAAC,UAAU,EAAE,UAAU,CAAC,EAAE,kBAAkB,CAAC,CAAC;AACzF,CAAC;AAED,sCAAsC;AACtC,MAAM,UAAU,eAAe,CAAC,UAAkB,EAAE,UAAkB;IACpE,OAAO,IAAI,CAAC,IAAI,CAAC,wBAAwB,CAAC,UAAU,EAAE,UAAU,CAAC,EAAE,iBAAiB,CAAC,CAAC;AACxF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAY,EAAE,QAAgB;IACrE,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,kBAAkB,EAAE,GAAG,IAAI,IAAI,QAAQ,EAAE,CAAC,CAAC;AACpE,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,UAAkB,EAAE,UAAkB;IACvE,MAAM,YAAY,GAAG,eAAe,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IAC7D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACrD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;YACxF,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;QACxC,CAAC;QACD,OAAO,MAA4B,CAAC;IACtC,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC1B,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;QACjF,CAAC;QACD,iEAAiE;QACjE,OAAO,CAAC,KAAK,CAAC,4BAA4B,YAAY,KAAK,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC;QAC3F,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;IACjF,CAAC;AACH,CAAC;AAED,uEAAuE;AACvE,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,UAAkB,EAAE,QAA4B;IAClF,MAAM,GAAG,GAAG,wBAAwB,CAAC,UAAU,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IACtE,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,MAAM,YAAY,GAAG,eAAe,CAAC,UAAU,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IACtE,QAAQ,CAAC,YAAY,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACjD,MAAM,EAAE,CAAC,SAAS,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AAC/E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,QAA4B,EAAE,KAA8B;IACtF,MAAM,QAAQ,GAAG,QAAQ,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5E,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;QAClB,QAAQ,CAAC,WAAW,CAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC;IACnF,CAAC;SAAM,CAAC;QACN,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAA4B,EAAE,SAAiB;IAClF,oEAAoE;IACpE,MAAM,SAAS,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC5E,MAAM,MAAM,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;IACpC,OAAO,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,MAAM,CAAC,CAAC;AAC3E,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,iBAAiB,CAAC,QAA4B,EAAE,GAAW;IACzE,OAAO,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,KAAK,GAAG,CAAC,CAAC;AAC/D,CAAC"}

package/build/sync/image-sync.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Image Sync Orchestration
+ *
+ * Hooks `image-handler` + `image-manifest` + `WorkItemService.downloadAttachment`
+ * into the work-item pull/push pipelines.
+ *
+ *  - On pull: scan all string fields + comment bodies for ADO attachment <img>
+ *    refs, download each binary into `{folder}/{id}/attachments/`, rewrite the
+ *    src to the local relative path, and write the manifest.
+ *
+ *  - On push: read the manifest, scan content for image refs, rewrite local
+ *    paths back to original ADO URLs, upload any new local files, append to
+ *    the manifest.
+ */
+import { type AttachmentManifest } from './image-manifest.js';
+interface ImageDownloadService {
+    downloadAttachment(project: string, attachmentGuid: string, urlFileName: string, outputDir: string, outputFileName?: string): Promise<{
+        filePath: string;
+        fileName: string;
+        size: number;
+        guid: string;
+    }>;
+}
+interface ImageUploadService {
+    uploadAttachment(project: string, filePath: string, fileName?: string): Promise<{
+        id: string;
+        url: string;
+        fileName: string;
+        size: number;
+    }>;
+}
+export interface PullImageResult {
+    downloaded: number;
+    reused: number;
+    failed: Array<{
+        guid: string;
+        fileName: string;
+        error: string;
+    }>;
+    manifest: AttachmentManifest;
+}
+/**
+ * Process all string fields on a work item, downloading attachments and
+ * rewriting srcs. Mutates `workItem.fields` in place. Persists the manifest.
+ */
+export declare function pullWorkItemImages(workItem: any, project: string, syncFolder: string, service: ImageDownloadService): Promise<PullImageResult>;
+/**
+ * Process comment bodies for image refs. Mutates `comments[i].text` in place.
+ * Uses the same manifest as the parent work item so attachments are tracked
+ * together. Returns aggregated counts.
+ */
+export declare function pullCommentImages(workItemId: number, comments: Array<{
+    text?: string;
+    content?: string;
+}>, project: string, syncFolder: string, service: ImageDownloadService): Promise<PullImageResult>;
+export interface PushImageResult {
+    uploaded: number;
+    reused: number;
+    failed: Array<{
+        src: string;
+        error: string;
+    }>;
+    manifest: AttachmentManifest;
+}
+/**
+ * Apply image push processing to a parsed work item file's body fields.
+ * Iterates every refname in `bodyFieldMap`, so custom body fields (not just
+ * the historical Description/ReproSteps/AC/custom-four) get image handling.
+ * Mutates the parsed object in-place and persists the manifest.
+ */
+export declare function pushWorkItemImages(parsed: {
+    bodyFieldMap: Record<string, string>;
+    description?: string;
+    reproSteps?: string;
+    acceptanceCriteria?: string;
+    additionalFields?: any;
+}, workItemId: number, project: string, syncFolder: string, service: ImageUploadService): Promise<PushImageResult>;
+/**
+ * Append a manually-uploaded attachment to a work item's manifest.
+ * Used by the standalone `upload-work-item-attachment` tool.
+ */
+export declare function recordExternalUpload(syncFolder: string, workItemId: number, uploaded: {
+    id: string;
+    url: string;
+    fileName: string;
+}, localPath: string): Promise<void>;
+export {};
+//# sourceMappingURL=image-sync.d.ts.map

package/build/sync/image-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-sync.d.ts","sourceRoot":"","sources":["../../src/sync/image-sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAUH,OAAO,EAQL,KAAK,kBAAkB,EAExB,MAAM,qBAAqB,CAAC;AAa7B,UAAU,oBAAoB;IAC5B,kBAAkB,CAChB,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChF;AAED,UAAU,kBAAkB;IAC1B,gBAAgB,CACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACzE;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjE,QAAQ,EAAE,kBAAkB,CAAC;CAC9B;AAwED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,GAAG,EACb,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,eAAe,CAAC,CAqB1B;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,KAAK,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EACpD,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,eAAe,CAAC,CAsB1B;AAMD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9C,QAAQ,EAAE,kBAAkB,CAAC;CAC9B;AAwHD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE;IACN,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,gBAAgB,CAAC,EAAE,GAAG,CAAC;CACxB,EACD,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,eAAe,CAAC,CA2B1B;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EACvD,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAYf"}