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

package/build/sync/image-sync.js

@@ -0,0 +1,274 @@
+/**
+ * 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 * as path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { extractImageRefs, rewriteImageSrcs, parseAdoAttachmentUrl, } from './image-handler.js';
+import { readManifest, writeManifest, upsertEntry, findEntryByLocalPath, buildLocalAttachmentPath, getAttachmentsBinDir, getWorkItemAttachmentDir, } from './image-manifest.js';
+/**
+ * Append `?fileName=...` (or `&fileName=...`) to an attachment URL only when
+ * one isn't already present. ADO's upload response sometimes already includes
+ * the param; appending unconditionally produces duplicate `fileName=` entries.
+ */
+function appendFileNameParam(url, fileName) {
+    if (/[?&]fileName=/i.test(url))
+        return url;
+    const sep = url.includes('?') ? '&' : '?';
+    return `${url}${sep}fileName=${encodeURIComponent(fileName)}`;
+}
+/**
+ * Scan an arbitrary HTML/markdown string for ADO attachment refs, download
+ * each missing binary, and rewrite the srcs to local relative paths.
+ *
+ * Returns the rewritten content, plus updates the manifest in-place.
+ */
+async function processFieldImages(content, fieldName, project, workItemId, syncFolder, service, manifest, result) {
+    if (!content)
+        return content;
+    const refs = extractImageRefs(content);
+    const adoRefs = refs.filter(r => r.adoAttachment);
+    if (adoRefs.length === 0)
+        return content;
+    const binDir = getAttachmentsBinDir(syncFolder, workItemId);
+    // Build a URL → localPath map by ensuring each ADO attachment is on disk.
+    const urlToLocalPath = new Map();
+    for (const ref of adoRefs) {
+        const ado = ref.adoAttachment;
+        const existing = manifest.attachments.find(a => a.guid === ado.guid);
+        const localRelPath = buildLocalAttachmentPath(ado.guid, ado.fileName);
+        const localAbsPath = path.join(getWorkItemAttachmentDir(syncFolder, workItemId), localRelPath);
+        let onDisk = false;
+        try {
+            await fs.access(localAbsPath);
+            onDisk = true;
+        }
+        catch { /* not on disk */ }
+        if (existing && onDisk) {
+            result.reused++;
+            urlToLocalPath.set(ref.originalSrc, `./${localRelPath}`);
+            continue;
+        }
+        try {
+            await service.downloadAttachment(project, ado.guid, ado.fileName, binDir, `${ado.guid}-${ado.fileName}`);
+            result.downloaded++;
+            const entry = {
+                guid: ado.guid,
+                fileName: ado.fileName,
+                localPath: localRelPath,
+                originalUrl: ado.originalUrl,
+                source: 'ado-pull',
+                field: fieldName,
+            };
+            upsertEntry(manifest, entry);
+            urlToLocalPath.set(ref.originalSrc, `./${localRelPath}`);
+        }
+        catch (err) {
+            result.failed.push({ guid: ado.guid, fileName: ado.fileName, error: err.message });
+        }
+    }
+    // Rewrite srcs in one pass using the map we built.
+    return rewriteImageSrcs(content, (src, _ado) => urlToLocalPath.get(src) ?? null);
+}
+/**
+ * Process all string fields on a work item, downloading attachments and
+ * rewriting srcs. Mutates `workItem.fields` in place. Persists the manifest.
+ */
+export async function pullWorkItemImages(workItem, project, syncFolder, service) {
+    const workItemId = workItem.id;
+    const manifest = await readManifest(syncFolder, workItemId);
+    const result = { downloaded: 0, reused: 0, failed: [], manifest };
+    const fields = workItem.fields || {};
+    for (const [fieldName, value] of Object.entries(fields)) {
+        if (typeof value !== 'string')
+            continue;
+        const newContent = await processFieldImages(value, fieldName, project, workItemId, syncFolder, service, manifest, result);
+        if (newContent !== value) {
+            fields[fieldName] = newContent;
+        }
+    }
+    if (result.downloaded > 0 || result.reused > 0 || manifest.attachments.length > 0) {
+        await writeManifest(syncFolder, manifest);
+    }
+    return result;
+}
+/**
+ * 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 async function pullCommentImages(workItemId, comments, project, syncFolder, service) {
+    const manifest = await readManifest(syncFolder, workItemId);
+    const result = { downloaded: 0, reused: 0, failed: [], manifest };
+    for (let i = 0; i < comments.length; i++) {
+        const c = comments[i];
+        const body = c.text ?? c.content ?? '';
+        if (typeof body !== 'string' || !body)
+            continue;
+        const newBody = await processFieldImages(body, `Comment#${i + 1}`, project, workItemId, syncFolder, service, manifest, result);
+        if (newBody !== body) {
+            if (c.text !== undefined)
+                c.text = newBody;
+            else
+                c.content = newBody;
+        }
+    }
+    if (result.downloaded > 0 || result.reused > 0) {
+        await writeManifest(syncFolder, manifest);
+    }
+    return result;
+}
+/**
+ * Resolve a markdown image src against the work-item attachment folder.
+ * Returns an absolute path that may or may not exist.
+ *
+ * Accepted forms:
+ *   - "./attachments/foo.png"
+ *   - "attachments/foo.png"
+ *   - "{workItemId}/attachments/foo.png"  (relative to the sync folder)
+ *   - any absolute path
+ */
+function resolveLocalImagePath(src, syncFolder, workItemId) {
+    // Skip remote URLs and data URIs
+    if (/^(https?:|data:|file:)/i.test(src))
+        return null;
+    const workItemDir = getWorkItemAttachmentDir(syncFolder, workItemId);
+    if (path.isAbsolute(src)) {
+        return {
+            absolute: src,
+            relativeToWorkItem: path.relative(workItemDir, src).replace(/\\/g, '/'),
+        };
+    }
+    // Strip leading ./
+    const stripped = src.replace(/^\.\//, '');
+    // If src starts with the work item ID, treat as syncFolder-relative
+    const idPrefix = `${workItemId}/`;
+    const candidate = stripped.startsWith(idPrefix)
+        ? path.join(syncFolder, stripped)
+        : path.join(workItemDir, stripped);
+    return {
+        absolute: candidate,
+        relativeToWorkItem: path.relative(workItemDir, candidate).replace(/\\/g, '/'),
+    };
+}
+/**
+ * Rewrite a content string for push:
+ *   - ADO URL → leave alone
+ *   - local path matching manifest → swap to original ADO URL
+ *   - local path NOT in manifest → upload, add to manifest, swap to new URL
+ *   - anything else (relative URL we can't find) → leave alone, log
+ */
+async function processFieldImagesForPush(content, fieldName, project, workItemId, syncFolder, service, manifest, result) {
+    if (!content)
+        return content;
+    const refs = extractImageRefs(content);
+    if (refs.length === 0)
+        return content;
+    // Resolve each ref upfront (uploads need to happen before we rewrite).
+    const srcToFinalUrl = new Map();
+    for (const ref of refs) {
+        const src = ref.originalSrc;
+        // Already an ADO URL — keep as-is
+        if (parseAdoAttachmentUrl(src)) {
+            continue;
+        }
+        const resolved = resolveLocalImagePath(src, syncFolder, workItemId);
+        if (!resolved)
+            continue; // remote/non-local URL we don't manage
+        // Manifest hit?
+        const entry = findEntryByLocalPath(manifest, resolved.relativeToWorkItem);
+        if (entry) {
+            srcToFinalUrl.set(src, entry.originalUrl);
+            result.reused++;
+            continue;
+        }
+        // Not in manifest — try to upload as new attachment.
+        try {
+            await fs.access(resolved.absolute);
+        }
+        catch {
+            result.failed.push({ src, error: `Local file not found: ${resolved.absolute}` });
+            continue;
+        }
+        try {
+            const uploaded = await service.uploadAttachment(project, resolved.absolute);
+            const finalUrl = appendFileNameParam(uploaded.url, uploaded.fileName);
+            const entryFromUpload = {
+                guid: uploaded.id,
+                fileName: uploaded.fileName,
+                localPath: resolved.relativeToWorkItem,
+                originalUrl: finalUrl,
+                source: 'local-uploaded',
+                field: fieldName,
+                uploadedAt: new Date().toISOString(),
+            };
+            upsertEntry(manifest, entryFromUpload);
+            srcToFinalUrl.set(src, finalUrl);
+            result.uploaded++;
+        }
+        catch (err) {
+            result.failed.push({ src, error: err.message });
+        }
+    }
+    if (srcToFinalUrl.size === 0)
+        return content;
+    return rewriteImageSrcs(content, (src, _ado) => srcToFinalUrl.get(src) ?? null);
+}
+/**
+ * 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 async function pushWorkItemImages(parsed, workItemId, project, syncFolder, service) {
+    const manifest = await readManifest(syncFolder, workItemId);
+    const result = { uploaded: 0, reused: 0, failed: [], manifest };
+    for (const [refname, value] of Object.entries(parsed.bodyFieldMap)) {
+        if (typeof value !== 'string' || !value)
+            continue;
+        parsed.bodyFieldMap[refname] = await processFieldImagesForPush(value, refname, project, workItemId, syncFolder, service, manifest, result);
+    }
+    // Keep the legacy convenience slots in sync with bodyFieldMap so downstream
+    // consumers that still read them (logs, diffs) see the updated content.
+    if (parsed.description !== undefined) {
+        parsed.description = parsed.bodyFieldMap['System.Description'] ?? '';
+    }
+    if (parsed.reproSteps !== undefined) {
+        parsed.reproSteps = parsed.bodyFieldMap['Microsoft.VSTS.TCM.ReproSteps'] ?? '';
+    }
+    if (parsed.acceptanceCriteria !== undefined) {
+        parsed.acceptanceCriteria = parsed.bodyFieldMap['Microsoft.VSTS.Common.AcceptanceCriteria'] ?? '';
+    }
+    if (result.uploaded > 0 || result.reused > 0 || manifest.attachments.length > 0) {
+        await writeManifest(syncFolder, manifest);
+    }
+    return result;
+}
+/**
+ * Append a manually-uploaded attachment to a work item's manifest.
+ * Used by the standalone `upload-work-item-attachment` tool.
+ */
+export async function recordExternalUpload(syncFolder, workItemId, uploaded, localPath) {
+    const manifest = await readManifest(syncFolder, workItemId);
+    const finalUrl = appendFileNameParam(uploaded.url, uploaded.fileName);
+    upsertEntry(manifest, {
+        guid: uploaded.id,
+        fileName: uploaded.fileName,
+        localPath,
+        originalUrl: finalUrl,
+        source: 'local-uploaded',
+        uploadedAt: new Date().toISOString(),
+    });
+    await writeManifest(syncFolder, manifest);
+}
+//# sourceMappingURL=image-sync.js.map

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

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

package/build/sync/index.d.ts

@@ -5,8 +5,15 @@
  */
 export * from './html-detection.js';
 export * from './html-converter.js';
+export * from './field-aliases.js';
+export * from './annotation-parser.js';
+export * from './legacy-mappings.js';
+export * from './template-loader.js';
 export * from './markdown-serializer.js';
 export * from './file-utils.js';
 export * from './git-utils.js';
 export * from './task-serializer.js';
+export * from './image-handler.js';
+export * from './image-manifest.js';
+export * from './image-sync.js';
 //# sourceMappingURL=index.d.ts.map

package/build/sync/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC"}

package/build/sync/index.js

@@ -5,8 +5,15 @@
  */
 export * from './html-detection.js';
 export * from './html-converter.js';
+export * from './field-aliases.js';
+export * from './annotation-parser.js';
+export * from './legacy-mappings.js';
+export * from './template-loader.js';
 export * from './markdown-serializer.js';
 export * from './file-utils.js';
 export * from './git-utils.js';
 export * from './task-serializer.js';
+export * from './image-handler.js';
+export * from './image-manifest.js';
+export * from './image-sync.js';
 //# sourceMappingURL=index.js.map

package/build/sync/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC"}

package/build/sync/legacy-mappings.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Backwards-compatibility mapping for pre-annotation synced files.
+ *
+ * Files generated before the annotation-driven sync format have `#`-level
+ * section headings with no `<!-- ado-field: ... -->` comment. We can still
+ * parse them by matching known headings against a fixed refname table.
+ *
+ * Type-aware: Bug work items historically used `# Description` for what is
+ * semantically Repro Steps. After upgrade, a Bug's `# Description` section
+ * maps to `Microsoft.VSTS.TCM.ReproSteps`, not `System.Description`.
+ */
+export interface LegacyHeadingRule {
+    heading: string;
+    refname: string;
+    /** Optional type filter — if set, only applies when workItemType matches. */
+    typeFilter?: string;
+}
+/**
+ * Ordered list of legacy heading → refname rules.
+ * First matching rule wins.
+ *
+ * Evaluated in order — bug-specific rules come before generic rules for
+ * the same heading.
+ */
+export declare const LEGACY_HEADING_RULES: LegacyHeadingRule[];
+/**
+ * Resolve a legacy heading to an ADO refname given the work item type.
+ * Returns null if the heading has no known mapping (section stays local-only).
+ */
+export declare function resolveLegacyHeading(heading: string, workItemType: string): string | null;
+/**
+ * Override the default custom-field refnames from env vars. Preserved so that
+ * existing installs relying on `AZUREDEVOPS_SYNC_FIELD_*` env vars still parse
+ * their legacy files correctly. New installs should use templates instead.
+ */
+export declare function applyLegacyEnvOverrides(): void;
+//# sourceMappingURL=legacy-mappings.d.ts.map

package/build/sync/legacy-mappings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-mappings.d.ts","sourceRoot":"","sources":["../../src/sync/legacy-mappings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,iBAAiB,EAkBnD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQzF;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAY9C"}

package/build/sync/legacy-mappings.js

@@ -0,0 +1,75 @@
+/**
+ * Backwards-compatibility mapping for pre-annotation synced files.
+ *
+ * Files generated before the annotation-driven sync format have `#`-level
+ * section headings with no `<!-- ado-field: ... -->` comment. We can still
+ * parse them by matching known headings against a fixed refname table.
+ *
+ * Type-aware: Bug work items historically used `# Description` for what is
+ * semantically Repro Steps. After upgrade, a Bug's `# Description` section
+ * maps to `Microsoft.VSTS.TCM.ReproSteps`, not `System.Description`.
+ */
+/**
+ * Ordered list of legacy heading → refname rules.
+ * First matching rule wins.
+ *
+ * Evaluated in order — bug-specific rules come before generic rules for
+ * the same heading.
+ */
+export const LEGACY_HEADING_RULES = [
+    // Bug-specific: legacy bug files wrote repro steps under `# Description`.
+    { heading: 'Description', refname: 'Microsoft.VSTS.TCM.ReproSteps', typeFilter: 'Bug' },
+    // Generic
+    { heading: 'Description', refname: 'System.Description' },
+    { heading: 'Repro Steps', refname: 'Microsoft.VSTS.TCM.ReproSteps' },
+    { heading: 'Acceptance Criteria', refname: 'Microsoft.VSTS.Common.AcceptanceCriteria' },
+    // Deprecated custom fields — historically configurable via env vars
+    { heading: 'How to Test', refname: 'Custom.Howtotest' },
+    { heading: 'Deployment Information', refname: 'Custom.Deploymentinformation' },
+    {
+        heading: 'Predeployment Steps',
+        refname: 'Custom.7519d1bc-5305-4905-822b-2b380e61b154',
+    },
+    {
+        heading: 'Postdeployment Steps',
+        refname: 'Custom.abd6763f-a242-4938-85ed-bda419e34e7e',
+    },
+];
+/**
+ * Resolve a legacy heading to an ADO refname given the work item type.
+ * Returns null if the heading has no known mapping (section stays local-only).
+ */
+export function resolveLegacyHeading(heading, workItemType) {
+    const normalized = heading.trim();
+    for (const rule of LEGACY_HEADING_RULES) {
+        if (rule.heading !== normalized)
+            continue;
+        if (rule.typeFilter && rule.typeFilter !== workItemType)
+            continue;
+        return rule.refname;
+    }
+    return null;
+}
+/**
+ * Override the default custom-field refnames from env vars. Preserved so that
+ * existing installs relying on `AZUREDEVOPS_SYNC_FIELD_*` env vars still parse
+ * their legacy files correctly. New installs should use templates instead.
+ */
+export function applyLegacyEnvOverrides() {
+    const overrides = [
+        ['How to Test', process.env.AZUREDEVOPS_SYNC_FIELD_HOW_TO_TEST],
+        ['Deployment Information', process.env.AZUREDEVOPS_SYNC_FIELD_DEPLOYMENT_INFO],
+        ['Predeployment Steps', process.env.AZUREDEVOPS_SYNC_FIELD_PREDEPLOY],
+        ['Postdeployment Steps', process.env.AZUREDEVOPS_SYNC_FIELD_POSTDEPLOY],
+    ];
+    for (const [heading, envValue] of overrides) {
+        if (!envValue)
+            continue;
+        const rule = LEGACY_HEADING_RULES.find((r) => r.heading === heading && !r.typeFilter);
+        if (rule)
+            rule.refname = envValue;
+    }
+}
+// Apply env overrides once at module load.
+applyLegacyEnvOverrides();
+//# sourceMappingURL=legacy-mappings.js.map

package/build/sync/legacy-mappings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-mappings.js","sourceRoot":"","sources":["../../src/sync/legacy-mappings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAwB;IACvD,0EAA0E;IAC1E,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,+BAA+B,EAAE,UAAU,EAAE,KAAK,EAAE;IACvF,UAAU;IACV,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,oBAAoB,EAAE;IACzD,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,+BAA+B,EAAE;IACpE,EAAE,OAAO,EAAE,qBAAqB,EAAE,OAAO,EAAE,0CAA0C,EAAE;IACvF,oEAAoE;IACpE,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,kBAAkB,EAAE;IACvD,EAAE,OAAO,EAAE,wBAAwB,EAAE,OAAO,EAAE,8BAA8B,EAAE;IAC9E;QACE,OAAO,EAAE,qBAAqB;QAC9B,OAAO,EAAE,6CAA6C;KACvD;IACD;QACE,OAAO,EAAE,sBAAsB;QAC/B,OAAO,EAAE,6CAA6C;KACvD;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe,EAAE,YAAoB;IACxE,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,oBAAoB,EAAE,CAAC;QACxC,IAAI,IAAI,CAAC,OAAO,KAAK,UAAU;YAAE,SAAS;QAC1C,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,KAAK,YAAY;YAAE,SAAS;QAClE,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB;IACrC,MAAM,SAAS,GAAwC;QACrD,CAAC,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC;QAC/D,CAAC,wBAAwB,EAAE,OAAO,CAAC,GAAG,CAAC,sCAAsC,CAAC;QAC9E,CAAC,qBAAqB,EAAE,OAAO,CAAC,GAAG,CAAC,gCAAgC,CAAC;QACrE,CAAC,sBAAsB,EAAE,OAAO,CAAC,GAAG,CAAC,iCAAiC,CAAC;KACxE,CAAC;IACF,KAAK,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,SAAS,EAAE,CAAC;QAC5C,IAAI,CAAC,QAAQ;YAAE,SAAS;QACxB,MAAM,IAAI,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QACtF,IAAI,IAAI;YAAE,IAAI,CAAC,OAAO,GAAG,QAAQ,CAAC;IACpC,CAAC;AACH,CAAC;AAED,2CAA2C;AAC3C,uBAAuB,EAAE,CAAC"}

package/build/sync/markdown-serializer.d.ts

@@ -2,7 +2,22 @@
  * Markdown Serialization Utilities
  *
  * Convert between ADO work items and local markdown files.
- * Uses YAML frontmatter for metadata and markdown sections for content.
+ *
+ * Files use YAML frontmatter (scalar fields — ADO refnames or friendly
+ * aliases) + body sections (long text fields tagged with
+ * `<!-- ado-field: REFNAME -->` comments). The sync engine is generic:
+ * any field named in the file is pushed to ADO, any field not named is
+ * left alone.
+ *
+ * Legacy files (pre-annotation) are detected and parsed via a
+ * legacy-mappings fallback table. They auto-upgrade to the annotated
+ * format on the next pull.
+ */
+import { type LocalOnlySection } from './annotation-parser.js';
+/**
+ * Subset of frontmatter values used by downstream services (sync-service,
+ * file-utils) via stable friendly names. Always populated on parse by
+ * pulling the corresponding refname out of `fieldMap`.
  */
 export interface WorkItemFrontmatter {
     id: number;
@@ -20,6 +35,11 @@ export interface WorkItemFrontmatter {
     lastSyncedRevision: number;
     lastSyncedAt: string;
 }
+/**
+ * Legacy slot for the four historically-supported custom fields. Retained
+ * so that pre-annotation callers (and reports) keep working. New-style
+ * consumers should read `bodyFieldMap` instead.
+ */
 export interface AdditionalFields {
     howToTest?: string;
     deploymentInformation?: string;
@@ -27,12 +47,23 @@ export interface AdditionalFields {
     postdeploymentSteps?: string;
 }
 export interface ParsedWorkItemFile {
+    /** Friendly-name frontmatter view for back-compat. */
     frontmatter: WorkItemFrontmatter;
+    /** All scalar ADO fields from frontmatter, keyed by refname. */
+    fieldMap: Record<string, FieldValue>;
+    /** All body text fields (from annotated sections OR legacy headings), keyed by refname. */
+    bodyFieldMap: Record<string, string>;
+    /** Sections with no ADO-field annotation — preserved in the file but not pushed. */
+    localOnlySections: LocalOnlySection[];
+    /** Work item type (mirrors frontmatter.type). */
+    workItemType: string;
     description: string;
+    reproSteps: string;
     acceptanceCriteria: string;
     additionalFields: AdditionalFields;
     rawContent: string;
 }
+export type FieldValue = string | number | boolean | string[];
 export interface CommentsFrontmatter {
     id: number;
     title: string;
@@ -44,50 +75,25 @@ export interface ParsedComment {
     date: string;
     content: string;
 }
-/**
- * Result of converting work item to markdown
- */
 export interface WorkItemToMarkdownResult {
     content: string;
     skippedFields: string[];
 }
 /**
- * Convert an ADO work item to markdown file content
+ * Serialize an ADO work item to an annotated markdown file.
  *
- * @param workItem - The work item from ADO API
- * @param revision - The revision number
- * @returns Object with markdown content and list of skipped fields (if any were HTML)
+ * Follows the template for `fields['System.WorkItemType']`. Frontmatter
+ * order and body-section order come from the template. Fields the ADO
+ * response carries but the template doesn't mention are appended to the
+ * frontmatter with a discovery comment (see D4 in the design plan).
  */
 export declare function workItemToMarkdown(workItem: any, revision: number): WorkItemToMarkdownResult;
-/**
- * Parse a markdown file to extract frontmatter and content sections
- */
 export declare function parseWorkItemMarkdown(content: string): ParsedWorkItemFile;
-/**
- * Convert ADO comments to a read-only markdown file
- */
-export declare function commentsToMarkdown(workItem: any, comments: any[]): string;
-/**
- * Build ADO patch operations from parsed markdown changes
- * Only updates fields that have actually changed.
- * Auto-converts HTML fields to markdown format unless skipAutoConvert is true.
- *
- * @param parsed - Parsed work item file
- * @param currentWorkItem - Current work item from ADO
- * @param skipAutoConvert - Skip automatic HTML-to-markdown conversion (default: false)
- */
 export declare function buildPatchOperations(parsed: ParsedWorkItemFile, currentWorkItem: any, skipAutoConvert?: boolean): {
     operations: any[];
     skippedFields: string[];
     convertedFields: string[];
 };
-/**
- * Update the lastSyncedRevision in a markdown file content
- */
-export declare function updateSyncRevision(content: string, newRevision: number): string;
-/**
- * Frontmatter for new work items (before they have an ID)
- */
 export interface NewWorkItemFrontmatter {
     title: string;
     type: string;
@@ -100,52 +106,40 @@ export interface NewWorkItemFrontmatter {
     areaPath?: string;
     iterationPath?: string;
 }
-/**
- * Parsed new work item file structure
- */
 export interface ParsedNewWorkItemFile {
     frontmatter: NewWorkItemFrontmatter;
+    fieldMap: Record<string, FieldValue>;
+    bodyFieldMap: Record<string, string>;
+    localOnlySections: LocalOnlySection[];
+    workItemType: string;
     description: string;
+    reproSteps: string;
     acceptanceCriteria: string;
     additionalFields: AdditionalFields;
     rawContent: string;
 }
-/**
- * Check if a work item frontmatter indicates a new (not yet created) work item
- * New work items don't have an 'id' field
- */
 export declare function isNewWorkItem(frontmatter: Record<string, any>): boolean;
-/**
- * Parse a markdown file for a NEW work item (no id required)
- */
 export declare function parseNewWorkItemMarkdown(content: string): ParsedNewWorkItemFile;
 /**
- * Result of building new work item fields, split into standard and custom.
- * Custom fields (MoSCoW, HowToTest, Deployment fields) cannot be set during
- * ADO work item creation — they must be set via a follow-up update.
+ * Split new-work-item fields into standard (safe for creation) and custom
+ * (must be set via a follow-up update because ADO rejects custom fields
+ * during creation).
+ *
+ * Standard = refname starts with `System.*` or `Microsoft.VSTS.*`.
+ * Custom   = everything else (conventionally `Custom.*`).
  */
 export interface NewWorkItemFieldSplit {
-    /** Standard ADO fields safe for creation */
     standardFields: Record<string, any>;
-    /** Custom fields that must be set via update after creation */
     customFields: Record<string, any>;
 }
-/**
- * Build ADO fields object for creating a new work item
- * Inherits areaPath and iterationPath from parent work item when available
- *
- * Returns fields split into standard (safe for creation) and custom (require
- * a follow-up update) because ADO rejects custom fields during work item creation.
- */
 export declare function buildNewWorkItemFields(parsed: ParsedNewWorkItemFile, parentWorkItem?: any): NewWorkItemFieldSplit;
-/**
- * Generate a new work item template markdown file
- * When parentId is undefined, creates a standalone work item template
- */
 export declare function generateNewWorkItemTemplate(parentId: number | undefined, parentTitle: string, project: string, workItemType?: string): string;
+export declare function commentsToMarkdown(workItem: any, comments: any[]): string;
+export declare function updateSyncRevision(content: string, newRevision: number): string;
+export declare function convertNewFileToSynced(content: string, workItemId: number, revision: number, url: string): string;
 /**
- * Update a new work item file after creation with the assigned ID
- * Converts it from a "new" file to a synced file with proper frontmatter
+ * Return the list of large-text (body) refnames that should be HTML-checked
+ * for a given work-item type. Driven by the loaded template.
  */
-export declare function convertNewFileToSynced(content: string, workItemId: number, revision: number, url: string): string;
+export declare function templateBodyRefnamesForType(workItemType: string): string[];
 //# sourceMappingURL=markdown-serializer.d.ts.map