sdx-cli 0.2.1

package/dist/lib/publishContracts.js

@@ -0,0 +1,876 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishNotices = publishNotices;
+exports.publishSync = publishSync;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const constants_1 = require("./constants");
+const contractChanges_1 = require("./contractChanges");
+const fs_1 = require("./fs");
+const githubPublish_1 = require("./githubPublish");
+const repoRegistry_1 = require("./repoRegistry");
+const scope_1 = require("./scope");
+const serviceNoticePlan_1 = require("./serviceNoticePlan");
+const SERVICE_NOTICE_CHANGE_TYPE = 'service_added';
+function nowIso() {
+    return new Date().toISOString();
+}
+function today() {
+    return nowIso().slice(0, 10);
+}
+function fileStamp() {
+    return nowIso().replace(/[:.]/g, '-');
+}
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+function normalizeRepoRef(value) {
+    const raw = value.trim();
+    if (!raw) {
+        return '';
+    }
+    const withoutProtocol = raw.replace(/^https?:\/\/github\.com\//i, '');
+    return withoutProtocol.replace(/\.git$/i, '').replace(/\/+$/, '');
+}
+function repoParts(record) {
+    const fullName = record.fullName.includes('/') ? record.fullName : `${record.org}/${record.name}`;
+    const [owner, repo] = fullName.split('/', 2);
+    return { owner, repo, fullName };
+}
+function toContractSuffix(contractChangeId) {
+    if (!contractChangeId) {
+        return 'batch';
+    }
+    return slugify(contractChangeId) || 'single';
+}
+function createTargetBranch(contractChangeId, targetRepoName) {
+    return `sdx/spec-notice/${slugify(contractChangeId)}-${slugify(targetRepoName)}`.slice(0, 120);
+}
+function createSourceSyncBranch(contractChangeId) {
+    return `sdx/source-sync/${slugify(contractChangeId)}`.slice(0, 120);
+}
+function splitRepoOwnerAndName(value) {
+    const normalized = normalizeRepoRef(value);
+    const parts = normalized.split('/');
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+        return null;
+    }
+    return {
+        owner: parts[0],
+        repo: parts[1],
+    };
+}
+function parseAliasTokens(raw) {
+    const value = raw.trim();
+    if (!value) {
+        return [];
+    }
+    if (value.startsWith('[') && value.endsWith(']')) {
+        try {
+            const parsed = JSON.parse(value);
+            if (Array.isArray(parsed)) {
+                return parsed.map((entry) => String(entry).trim()).filter(Boolean);
+            }
+        }
+        catch {
+            // Fall through to delimiter parsing.
+        }
+    }
+    return value
+        .replace(/^\[/, '')
+        .replace(/\]$/, '')
+        .split(',')
+        .map((entry) => entry.replace(/^"|"$/g, '').trim())
+        .filter(Boolean);
+}
+function mergeAliasTokens(existing, additions) {
+    const merged = [...parseAliasTokens(existing), ...additions];
+    const unique = [...new Set(merged)].sort((a, b) => a.localeCompare(b));
+    return unique.join(', ');
+}
+function sourceAliasTokens(source, sourceContractId) {
+    return [`source_repo:${source.fullName}`, `source_cc:${sourceContractId}`];
+}
+function resolveRepoFromScope(inputRepo, ownerHint, scopedRepos, allRepos) {
+    const normalized = normalizeRepoRef(inputRepo);
+    if (!normalized) {
+        return { error: 'Repository value is empty.' };
+    }
+    const fullMatch = splitRepoOwnerAndName(normalized);
+    if (fullMatch) {
+        const scoped = scopedRepos.filter((repo) => {
+            const parts = repoParts(repo);
+            return parts.owner.toLowerCase() === fullMatch.owner.toLowerCase() && parts.repo.toLowerCase() === fullMatch.repo.toLowerCase();
+        });
+        if (scoped.length === 1) {
+            return { record: scoped[0] };
+        }
+        const allMatches = allRepos.filter((repo) => {
+            const parts = repoParts(repo);
+            return parts.owner.toLowerCase() === fullMatch.owner.toLowerCase() && parts.repo.toLowerCase() === fullMatch.repo.toLowerCase();
+        });
+        if (allMatches.length > 0) {
+            return { error: `Repository '${normalized}' is outside the active map scope.` };
+        }
+        return { error: `Repository '${normalized}' was not found in the repo registry.` };
+    }
+    let matches = scopedRepos.filter((repo) => repo.name.toLowerCase() === normalized.toLowerCase());
+    if (matches.length > 1 && ownerHint) {
+        const ownerNormalized = ownerHint.trim().toLowerCase();
+        const hinted = matches.filter((repo) => repoParts(repo).owner.toLowerCase() === ownerNormalized);
+        if (hinted.length === 1) {
+            matches = hinted;
+        }
+    }
+    if (matches.length === 1) {
+        return { record: matches[0] };
+    }
+    if (matches.length > 1) {
+        return {
+            error: `Repository '${inputRepo}' is ambiguous in the current scope: ${matches
+                .map((repo) => repoParts(repo).fullName)
+                .join(', ')}`,
+        };
+    }
+    const outOfScope = allRepos.some((repo) => repo.name.toLowerCase() === normalized.toLowerCase());
+    if (outOfScope) {
+        return { error: `Repository '${inputRepo}' is outside the active map scope.` };
+    }
+    return { error: `Repository '${inputRepo}' was not found in the repo registry.` };
+}
+function createPublishContext(input, requireOps) {
+    const cwd = input.cwd ?? process.cwd();
+    const scope = (0, scope_1.loadScopeManifest)(input.mapId, cwd);
+    const allRepos = (0, repoRegistry_1.listAllRepos)(input.db);
+    const scopeSet = new Set(scope.effective);
+    const scopedRepos = allRepos.filter((repo) => scopeSet.has(repo.name));
+    const sourceResolution = resolveRepoFromScope(input.sourceRepo, undefined, scopedRepos, allRepos);
+    if (!sourceResolution.record) {
+        throw new Error(sourceResolution.error ?? `Unable to resolve source repo '${input.sourceRepo}'.`);
+    }
+    const sourceRepoRecord = sourceResolution.record;
+    if (!sourceRepoRecord.localPath) {
+        throw new Error(`Source repository '${repoParts(sourceRepoRecord).fullName}' is missing local path metadata. Register it with 'sdx repo add --name ${sourceRepoRecord.name} --path <local-path>'.`);
+    }
+    const indexPath = node_path_1.default.join(sourceRepoRecord.localPath, 'docs', 'CONTRACT_CHANGES.md');
+    if (!node_fs_1.default.existsSync(indexPath)) {
+        throw new Error(`Source repository '${repoParts(sourceRepoRecord).fullName}' is missing docs/CONTRACT_CHANGES.md. spec-system not instantiated (or invalid).`);
+    }
+    const indexBody = node_fs_1.default.readFileSync(indexPath, 'utf8');
+    if (!(0, contractChanges_1.hasContractChangeIndexShape)(indexBody)) {
+        throw new Error(`Source repository '${repoParts(sourceRepoRecord).fullName}' has invalid docs/CONTRACT_CHANGES.md. spec-system not instantiated (or invalid).`);
+    }
+    const { meta, rows } = (0, contractChanges_1.parseContractChangeIndexText)(indexBody);
+    const ops = input.githubOps ?? (input.githubToken ? (0, githubPublish_1.createGithubPublishOps)(input.githubToken) : undefined);
+    if (requireOps && !ops) {
+        throw new Error('GitHub token is required for this command. Set GITHUB_TOKEN (or configured token env).');
+    }
+    return {
+        cwd,
+        scopeMapId: input.mapId,
+        scopedRepos,
+        allRepos,
+        sourceRepoParts: repoParts(sourceRepoRecord),
+        sourceRepoPath: sourceRepoRecord.localPath,
+        indexMeta: meta,
+        indexRows: rows,
+        ops,
+    };
+}
+function ensureArtifactPaths(baseDir, category, mapId, contractChangeId) {
+    const stamp = fileStamp();
+    const suffix = toContractSuffix(contractChangeId);
+    const jsonPath = node_path_1.default.join(baseDir, 'publish', category, `${stamp}-${slugify(mapId)}-${suffix}.json`);
+    const markdownPath = node_path_1.default.join(baseDir, 'publish', category, `${stamp}-${slugify(mapId)}-${suffix}.md`);
+    return { jsonPath, markdownPath };
+}
+function contractFilePath(contractChangeId, name) {
+    return `contracts/${contractChangeId}-${slugify(name) || slugify(contractChangeId)}.md`;
+}
+function buildTargetContractDoc(source, sourceDoc, targetContractChangeId, targetOwner) {
+    return {
+        contractChangeId: targetContractChangeId,
+        name: `Respond to ${sourceDoc.contractChangeId}: ${sourceDoc.name}`,
+        status: 'draft',
+        changeType: sourceDoc.changeType || 'api_contract_changed',
+        owner: targetOwner || sourceDoc.owner,
+        lastUpdated: today(),
+        absolutePath: '',
+        relativePath: `docs/${contractFilePath(targetContractChangeId, sourceDoc.name)}`,
+        sections: {
+            summary: [
+                `This contract change was generated by SDX from source contract change ${sourceDoc.contractChangeId}.`,
+                '',
+                `Source repository: ${source.fullName}`,
+                '',
+                sourceDoc.sections.summary.trim() || '_No summary provided._',
+            ].join('\n'),
+            contractSurface: sourceDoc.sections.contractSurface.trim() || '_No contract surface details provided._',
+            changeDetails: [
+                sourceDoc.sections.changeDetails.trim() || '_No change details provided._',
+                '',
+                `Source reference: ${source.fullName} / ${sourceDoc.contractChangeId}`,
+            ].join('\n'),
+            compatibilityAndMigrationGuidance: sourceDoc.sections.compatibilityAndMigrationGuidance.trim() || '_No migration guidance provided._',
+        },
+        targets: [],
+    };
+}
+function buildTargetPrBody(source, sourceDoc, targetContext, targetContractChangeId) {
+    return [
+        `## SDX Contract Change Assignment: ${targetContractChangeId}`,
+        '',
+        `Source repository: ${source.fullName}`,
+        `Source contract change: ${sourceDoc.contractChangeId}`,
+        `Change type: ${sourceDoc.changeType}`,
+        '',
+        '### Summary',
+        sourceDoc.sections.summary.trim() || '_No summary provided._',
+        '',
+        '### Contract Surface',
+        sourceDoc.sections.contractSurface.trim() || '_No contract surface details provided._',
+        '',
+        '### Migration Guidance',
+        sourceDoc.sections.compatibilityAndMigrationGuidance.trim() || '_No migration guidance provided._',
+        '',
+        '### Target Context',
+        targetContext,
+        '',
+        '### Required Response',
+        '- [ ] Confirm impact on this repository.',
+        '- [ ] Implement required code or contract adjustments.',
+        '- [ ] Add tests and rollout notes.',
+        '- [ ] Update CC status in this repo as work progresses.',
+        '',
+    ].join('\n');
+}
+function buildSourceSyncPrBody(doc) {
+    return [
+        `## Source Sync for ${doc.contractChangeId}`,
+        '',
+        'This PR updates source contract change artifacts with downstream target PR links and states.',
+        '',
+        '### Updated Files',
+        '- docs/CONTRACT_CHANGES.md',
+        `- ${doc.relativePath}`,
+        '',
+    ].join('\n');
+}
+function updateIndexRowFromDoc(row, doc) {
+    row.status = doc.status;
+    row.name = doc.name;
+    row.changeType = doc.changeType;
+    row.owner = doc.owner;
+    if (!row.path.trim()) {
+        row.path = doc.relativePath.replace(/^docs\//, '');
+    }
+}
+function findIndexRowById(rows, id) {
+    const rowIndex = rows.findIndex((row) => row.contractChangeId === id);
+    if (rowIndex === -1) {
+        return undefined;
+    }
+    return { row: rows[rowIndex], rowIndex };
+}
+function findIndexRowByAlias(rows, aliasToken) {
+    const rowIndex = rows.findIndex((row) => parseAliasTokens(row.aliases).includes(aliasToken));
+    if (rowIndex === -1) {
+        return undefined;
+    }
+    return { row: rows[rowIndex], rowIndex };
+}
+function loadContractModeContracts(context, contractChangeId) {
+    const selectedRows = context.indexRows
+        .map((row, rowIndex) => ({ row, rowIndex }))
+        .filter((entry) => (contractChangeId ? entry.row.contractChangeId === contractChangeId : true))
+        .sort((a, b) => a.row.contractChangeId.localeCompare(b.row.contractChangeId));
+    if (contractChangeId && selectedRows.length === 0) {
+        throw new Error(`Contract change '${contractChangeId}' was not found in docs/CONTRACT_CHANGES.md.`);
+    }
+    return selectedRows.map((entry) => {
+        try {
+            const doc = (0, contractChanges_1.readContractChangeDoc)(context.sourceRepoPath, entry.row);
+            return { row: entry.row, rowIndex: entry.rowIndex, doc, sourceChanged: false };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { row: entry.row, rowIndex: entry.rowIndex, loadError: message, sourceChanged: false };
+        }
+    });
+}
+function buildSourceDocFromServicePlan(context, input) {
+    if (!input.planPath) {
+        throw new Error('`--plan <file>` is required when --notice-type service is used.');
+    }
+    const planPath = node_path_1.default.resolve(context.cwd, input.planPath);
+    if (!node_fs_1.default.existsSync(planPath)) {
+        throw new Error(`Service plan file not found: ${planPath}`);
+    }
+    const planText = node_fs_1.default.readFileSync(planPath, 'utf8');
+    const plan = (0, serviceNoticePlan_1.parseServiceNoticePlan)(planText);
+    const serviceAlias = `service:${plan.serviceId}`;
+    let selected = input.contractChangeId
+        ? findIndexRowById(context.indexRows, input.contractChangeId)
+        : findIndexRowByAlias(context.indexRows, serviceAlias);
+    if (!selected && input.contractChangeId) {
+        if (!/^CC-\d{3}$/.test(input.contractChangeId)) {
+            throw new Error(`Invalid --contract-change-id '${input.contractChangeId}'. Expected format CC-###.`);
+        }
+        const newRow = {
+            contractChangeId: input.contractChangeId,
+            name: `${plan.name} onboarding`,
+            status: 'approved',
+            changeType: SERVICE_NOTICE_CHANGE_TYPE,
+            owner: context.sourceRepoParts.owner,
+            path: contractFilePath(input.contractChangeId, plan.name),
+            aliases: serviceAlias,
+        };
+        context.indexRows.push(newRow);
+        selected = { row: newRow, rowIndex: context.indexRows.length - 1 };
+    }
+    if (!selected) {
+        const sourceContractId = (0, contractChanges_1.nextContractChangeId)(context.indexRows);
+        const newRow = {
+            contractChangeId: sourceContractId,
+            name: `${plan.name} onboarding`,
+            status: 'approved',
+            changeType: SERVICE_NOTICE_CHANGE_TYPE,
+            owner: context.sourceRepoParts.owner,
+            path: contractFilePath(sourceContractId, plan.name),
+            aliases: serviceAlias,
+        };
+        context.indexRows.push(newRow);
+        selected = { row: newRow, rowIndex: context.indexRows.length - 1 };
+    }
+    const existingRow = selected.row;
+    const existingTargetsByRepo = new Map();
+    try {
+        const existingDoc = (0, contractChanges_1.readContractChangeDoc)(context.sourceRepoPath, existingRow);
+        for (const target of existingDoc.targets) {
+            existingTargetsByRepo.set(normalizeRepoRef(target.repo), target);
+        }
+    }
+    catch {
+        // No existing source doc yet.
+    }
+    const nextTargets = plan.targets.map((target) => {
+        const preserved = existingTargetsByRepo.get(normalizeRepoRef(target.repo));
+        return {
+            repo: target.repo,
+            owner: target.owner,
+            context: target.context,
+            prUrl: preserved?.prUrl ?? '',
+            state: preserved?.state ?? 'pending',
+        };
+    });
+    existingRow.name = `${plan.name} onboarding`;
+    existingRow.changeType = SERVICE_NOTICE_CHANGE_TYPE;
+    existingRow.owner = context.sourceRepoParts.owner;
+    existingRow.path = existingRow.path || contractFilePath(existingRow.contractChangeId, plan.name);
+    existingRow.aliases = mergeAliasTokens(existingRow.aliases, [serviceAlias]);
+    existingRow.status = existingRow.status === 'draft' ? 'approved' : existingRow.status;
+    const doc = {
+        contractChangeId: existingRow.contractChangeId,
+        name: existingRow.name,
+        status: existingRow.status,
+        changeType: existingRow.changeType,
+        owner: existingRow.owner,
+        lastUpdated: today(),
+        absolutePath: node_path_1.default.join(context.sourceRepoPath, 'docs', existingRow.path),
+        relativePath: `docs/${existingRow.path}`,
+        sections: {
+            summary: plan.summary,
+            contractSurface: plan.contractSurface,
+            changeDetails: plan.changeDetails,
+            compatibilityAndMigrationGuidance: plan.migrationGuidance,
+        },
+        targets: nextTargets,
+    };
+    return {
+        row: existingRow,
+        rowIndex: selected.rowIndex,
+        doc,
+        sourceChanged: true,
+    };
+}
+function buildNoticeContracts(context, input) {
+    if (input.noticeType === 'service') {
+        return [buildSourceDocFromServicePlan(context, input)];
+    }
+    return loadContractModeContracts(context, input.contractChangeId);
+}
+async function upsertSourceSync(context, doc, ready) {
+    if (!context.ops) {
+        throw new Error('GitHub publish operations are not configured.');
+    }
+    const branch = createSourceSyncBranch(doc.contractChangeId);
+    await context.ops.ensureBranch(context.sourceRepoParts.owner, context.sourceRepoParts.repo, branch);
+    const sourceDocPath = doc.relativePath.startsWith('docs/') ? doc.relativePath : `docs/${doc.relativePath}`;
+    await context.ops.upsertTextFile(context.sourceRepoParts.owner, context.sourceRepoParts.repo, branch, sourceDocPath, (0, contractChanges_1.renderContractChangeDoc)(doc), `chore(sdx): sync ${doc.contractChangeId} downstream state`);
+    await context.ops.upsertTextFile(context.sourceRepoParts.owner, context.sourceRepoParts.repo, branch, 'docs/CONTRACT_CHANGES.md', (0, contractChanges_1.renderContractChangeIndex)(context.indexRows, context.indexMeta), `chore(sdx): refresh contract index for ${doc.contractChangeId}`);
+    const pr = await context.ops.upsertPullRequest({
+        owner: context.sourceRepoParts.owner,
+        repo: context.sourceRepoParts.repo,
+        branch,
+        title: `chore(sdx): sync ${doc.contractChangeId} downstream state`,
+        body: buildSourceSyncPrBody(doc),
+        draft: !ready,
+    });
+    return pr.url;
+}
+function findExistingTargetRow(rows, source, sourceDoc) {
+    const markers = sourceAliasTokens(source, sourceDoc.contractChangeId);
+    return rows.find((row) => {
+        const aliases = parseAliasTokens(row.aliases);
+        return markers.every((marker) => aliases.includes(marker));
+    });
+}
+async function publishTargetContractChange(context, sourceDoc, target, targetRepo, ready) {
+    if (!context.ops) {
+        throw new Error('GitHub publish operations are not configured.');
+    }
+    const branch = createTargetBranch(sourceDoc.contractChangeId, targetRepo.repo);
+    await context.ops.ensureBranch(targetRepo.owner, targetRepo.repo, branch);
+    const indexPath = 'docs/CONTRACT_CHANGES.md';
+    const indexBody = await context.ops.readTextFile(targetRepo.owner, targetRepo.repo, indexPath, branch);
+    if (!indexBody || !(0, contractChanges_1.hasContractChangeIndexShape)(indexBody)) {
+        throw new Error('spec-system not instantiated (or invalid): missing or invalid docs/CONTRACT_CHANGES.md');
+    }
+    const parsed = (0, contractChanges_1.parseContractChangeIndexText)(indexBody);
+    const existingTargetRow = findExistingTargetRow(parsed.rows, context.sourceRepoParts, sourceDoc);
+    const targetContractChangeId = existingTargetRow
+        ? existingTargetRow.contractChangeId
+        : (0, contractChanges_1.nextContractChangeId)(parsed.rows);
+    const sourceAliases = sourceAliasTokens(context.sourceRepoParts, sourceDoc.contractChangeId);
+    const targetRow = {
+        contractChangeId: targetContractChangeId,
+        name: `Respond to ${sourceDoc.contractChangeId}: ${sourceDoc.name}`,
+        status: 'draft',
+        changeType: sourceDoc.changeType || 'api_contract_changed',
+        owner: target.owner,
+        path: existingTargetRow?.path || contractFilePath(targetContractChangeId, sourceDoc.name),
+        aliases: mergeAliasTokens(existingTargetRow?.aliases ?? '', sourceAliases),
+    };
+    const rowIndex = parsed.rows.findIndex((row) => row.contractChangeId === targetRow.contractChangeId);
+    if (rowIndex === -1) {
+        parsed.rows.push(targetRow);
+    }
+    else {
+        parsed.rows[rowIndex] = targetRow;
+    }
+    parsed.rows.sort((a, b) => a.contractChangeId.localeCompare(b.contractChangeId));
+    const targetDoc = buildTargetContractDoc(context.sourceRepoParts, sourceDoc, targetContractChangeId, target.owner);
+    const targetDocPath = `docs/${targetRow.path.replace(/^docs\//, '')}`;
+    await context.ops.upsertTextFile(targetRepo.owner, targetRepo.repo, branch, indexPath, (0, contractChanges_1.renderContractChangeIndex)(parsed.rows, parsed.meta), `chore(sdx): register ${targetContractChangeId} from ${sourceDoc.contractChangeId}`);
+    await context.ops.upsertTextFile(targetRepo.owner, targetRepo.repo, branch, targetDocPath, (0, contractChanges_1.renderContractChangeDoc)(targetDoc), `chore(sdx): add ${targetContractChangeId} from ${sourceDoc.contractChangeId}`);
+    const pr = await context.ops.upsertPullRequest({
+        owner: targetRepo.owner,
+        repo: targetRepo.repo,
+        branch,
+        title: `chore(contract-change): ${targetContractChangeId} for ${sourceDoc.contractChangeId}`,
+        body: buildTargetPrBody(context.sourceRepoParts, sourceDoc, target.context, targetContractChangeId),
+        draft: !ready,
+    });
+    return {
+        prUrl: pr.url,
+        created: pr.created,
+        targetContractChangeId,
+    };
+}
+function buildNoticesArtifactMarkdown(result) {
+    const lines = [
+        '# Publish Notices Run',
+        '',
+        `- Generated: ${result.generatedAt}`,
+        `- Map: ${result.mapId}`,
+        `- Source Repo: ${result.sourceRepo}`,
+        `- Notice Type: ${result.noticeType}`,
+        `- Dry Run: ${result.dryRun ? 'yes' : 'no'}`,
+        `- Draft Mode: ${result.ready ? 'ready PRs' : 'draft PRs'}`,
+        ...(result.planPath ? [`- Plan Path: ${result.planPath}`] : []),
+        ...(result.failFastStoppedAt ? [`- Fail Fast Stop: ${result.failFastStoppedAt}`] : []),
+        '',
+        `Totals: created=${result.totals.created}, updated=${result.totals.updated}, skipped=${result.totals.skipped}, failed=${result.totals.failed}`,
+        '',
+    ];
+    for (const contract of result.contracts) {
+        lines.push(`## ${contract.contractChangeId}: ${contract.name}`);
+        lines.push(`- Eligible: ${contract.eligible ? 'yes' : 'no'}`);
+        lines.push(`- Status: ${contract.sourceStatusBefore} -> ${contract.sourceStatusAfter}`);
+        lines.push(`- Source Sync PR: ${contract.sourceSyncPrUrl ?? '-'}`);
+        lines.push('');
+        lines.push('| Target | Target CC | Result | State | PR | Notes |');
+        lines.push('|---|---|---|---|---|---|');
+        if (contract.targetResults.length === 0) {
+            lines.push('| - | - | skipped | - | - | No target rows processed |');
+        }
+        else {
+            for (const target of contract.targetResults) {
+                lines.push(`| ${target.targetRepoInput} | ${target.targetContractChangeId ?? '-'} | ${target.status} | ${target.stateBefore} -> ${target.stateAfter} | ${target.prUrl ?? '-'} | ${target.reason ?? '-'} |`);
+            }
+        }
+        lines.push('');
+    }
+    return `${lines.join('\n')}\n`;
+}
+function buildSyncArtifactMarkdown(result) {
+    const lines = [
+        '# Publish Sync Run',
+        '',
+        `- Generated: ${result.generatedAt}`,
+        `- Map: ${result.mapId}`,
+        `- Source Repo: ${result.sourceRepo}`,
+        `- Dry Run: ${result.dryRun ? 'yes' : 'no'}`,
+        '',
+        `Totals: updated=${result.totals.updated}, skipped=${result.totals.skipped}, failed=${result.totals.failed}`,
+        '',
+    ];
+    for (const contract of result.contracts) {
+        lines.push(`## ${contract.contractChangeId}: ${contract.name}`);
+        lines.push(`- Status: ${contract.sourceStatusBefore} -> ${contract.sourceStatusAfter}`);
+        lines.push(`- Source Sync PR: ${contract.sourceSyncPrUrl ?? '-'}`);
+        lines.push('');
+        lines.push('| Target | Result | State | PR | Notes |');
+        lines.push('|---|---|---|---|---|');
+        if (contract.targetResults.length === 0) {
+            lines.push('| - | skipped | - | - | No target rows processed |');
+        }
+        else {
+            for (const target of contract.targetResults) {
+                lines.push(`| ${target.repo} | ${target.status} | ${target.stateBefore} -> ${target.stateAfter} | ${target.prUrl || '-'} | ${target.reason ?? '-'} |`);
+            }
+        }
+        lines.push('');
+    }
+    return `${lines.join('\n')}\n`;
+}
+function totalsForNotice(result) {
+    const totals = { created: 0, updated: 0, skipped: 0, failed: 0 };
+    for (const contract of result) {
+        for (const target of contract.targetResults) {
+            totals[target.status] += 1;
+        }
+    }
+    return totals;
+}
+function totalsForSync(result) {
+    const totals = { updated: 0, skipped: 0, failed: 0 };
+    for (const contract of result) {
+        for (const target of contract.targetResults) {
+            totals[target.status] += 1;
+        }
+    }
+    return totals;
+}
+function lifecycleToTargetState(value) {
+    if (value === 'merged') {
+        return 'merged';
+    }
+    if (value === 'blocked') {
+        return 'blocked';
+    }
+    return 'opened';
+}
+function formatError(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+async function publishNotices(input) {
+    const noticeType = input.noticeType ?? 'contract';
+    const dryRun = Boolean(input.dryRun);
+    const ready = Boolean(input.ready);
+    const maxTargets = input.maxTargets && input.maxTargets > 0 ? input.maxTargets : undefined;
+    const context = createPublishContext(input, !dryRun);
+    const sourceSyncPrUrls = new Set();
+    let remainingTargets = maxTargets ?? Number.POSITIVE_INFINITY;
+    let stopReason;
+    const contractsToProcess = buildNoticeContracts(context, input);
+    const contracts = [];
+    for (const loaded of contractsToProcess) {
+        const fallbackName = loaded.row.name;
+        if (!loaded.doc) {
+            contracts.push({
+                contractChangeId: loaded.row.contractChangeId,
+                name: fallbackName,
+                sourceStatusBefore: loaded.row.status,
+                sourceStatusAfter: loaded.row.status,
+                eligible: false,
+                targetResults: [
+                    {
+                        contractChangeId: loaded.row.contractChangeId,
+                        targetRepoInput: '-',
+                        owner: '-',
+                        stateBefore: '-',
+                        stateAfter: '-',
+                        status: 'failed',
+                        reason: loaded.loadError ?? 'Unable to load source contract change artifact.',
+                    },
+                ],
+            });
+            stopReason = contracts[contracts.length - 1].targetResults[0].reason;
+            break;
+        }
+        const doc = loaded.doc;
+        const contractResult = {
+            contractChangeId: doc.contractChangeId,
+            name: doc.name,
+            sourceStatusBefore: doc.status,
+            sourceStatusAfter: doc.status,
+            eligible: (0, contractChanges_1.isNotifiableContractStatus)(doc.status),
+            targetResults: [],
+        };
+        if (!contractResult.eligible) {
+            contractResult.targetResults.push({
+                contractChangeId: doc.contractChangeId,
+                targetRepoInput: '-',
+                owner: '-',
+                stateBefore: '-',
+                stateAfter: '-',
+                status: 'skipped',
+                reason: `Status '${doc.status}' is not eligible. Expected approved or published.`,
+            });
+            contracts.push(contractResult);
+            continue;
+        }
+        for (const target of doc.targets) {
+            const targetResult = {
+                contractChangeId: doc.contractChangeId,
+                targetRepoInput: target.repo,
+                owner: target.owner,
+                stateBefore: target.state,
+                stateAfter: target.state,
+                status: 'skipped',
+            };
+            if (target.state !== 'pending') {
+                targetResult.reason = `Target state is '${target.state}', only pending targets are publishable.`;
+                contractResult.targetResults.push(targetResult);
+                continue;
+            }
+            if (!(0, contractChanges_1.hasRequiredTargetContext)(target)) {
+                targetResult.status = 'failed';
+                targetResult.reason = 'Target row is missing required repo/owner/context values.';
+                contractResult.targetResults.push(targetResult);
+                stopReason = targetResult.reason;
+                break;
+            }
+            if (remainingTargets <= 0) {
+                targetResult.reason = `Skipped due to --max-targets=${maxTargets}.`;
+                contractResult.targetResults.push(targetResult);
+                continue;
+            }
+            const resolution = resolveRepoFromScope(target.repo, target.owner, context.scopedRepos, context.allRepos);
+            if (!resolution.record) {
+                targetResult.status = 'failed';
+                targetResult.reason = resolution.error;
+                contractResult.targetResults.push(targetResult);
+                stopReason = targetResult.reason;
+                break;
+            }
+            const targetRepo = repoParts(resolution.record);
+            targetResult.targetRepoResolved = targetRepo.fullName;
+            if (dryRun) {
+                targetResult.reason = 'Dry run: would create/update target spec-system contract change PR.';
+                contractResult.targetResults.push(targetResult);
+                remainingTargets -= 1;
+                continue;
+            }
+            try {
+                const published = await publishTargetContractChange(context, doc, target, targetRepo, ready);
+                target.prUrl = published.prUrl;
+                target.state = 'opened';
+                targetResult.stateAfter = 'opened';
+                targetResult.prUrl = published.prUrl;
+                targetResult.targetContractChangeId = published.targetContractChangeId;
+                targetResult.status = published.created ? 'created' : 'updated';
+                loaded.sourceChanged = true;
+            }
+            catch (error) {
+                targetResult.status = 'failed';
+                targetResult.reason = formatError(error);
+                stopReason = targetResult.reason;
+            }
+            contractResult.targetResults.push(targetResult);
+            remainingTargets -= 1;
+            if (targetResult.status === 'failed') {
+                break;
+            }
+        }
+        doc.status = (0, contractChanges_1.computeContractChangeStatus)(doc.status, doc.targets);
+        contractResult.sourceStatusAfter = doc.status;
+        updateIndexRowFromDoc(loaded.row, doc);
+        if (!dryRun && loaded.sourceChanged) {
+            try {
+                const sourceSyncPrUrl = await upsertSourceSync(context, doc, ready);
+                contractResult.sourceSyncPrUrl = sourceSyncPrUrl;
+                sourceSyncPrUrls.add(sourceSyncPrUrl);
+            }
+            catch (error) {
+                const syncFailure = {
+                    contractChangeId: doc.contractChangeId,
+                    targetRepoInput: context.sourceRepoParts.fullName,
+                    owner: context.sourceRepoParts.owner,
+                    stateBefore: contractResult.sourceStatusBefore,
+                    stateAfter: contractResult.sourceStatusAfter,
+                    status: 'failed',
+                    reason: `Source sync failed: ${formatError(error)}`,
+                };
+                contractResult.targetResults.push(syncFailure);
+                stopReason = syncFailure.reason;
+            }
+        }
+        contracts.push(contractResult);
+        if (stopReason) {
+            break;
+        }
+    }
+    const artifactPaths = ensureArtifactPaths(context.cwd, 'notices', input.mapId, input.contractChangeId);
+    const result = {
+        schemaVersion: constants_1.SCHEMA_VERSION,
+        generatedAt: nowIso(),
+        mapId: input.mapId,
+        sourceRepo: context.sourceRepoParts.fullName,
+        contractChangeId: input.contractChangeId,
+        noticeType,
+        planPath: input.planPath ? node_path_1.default.resolve(context.cwd, input.planPath) : undefined,
+        dryRun,
+        ready,
+        maxTargets,
+        failFastStoppedAt: stopReason,
+        totals: totalsForNotice(contracts),
+        contracts,
+        sourceSyncPrUrls: [...sourceSyncPrUrls].sort((a, b) => a.localeCompare(b)),
+        artifactJsonPath: artifactPaths.jsonPath,
+        artifactMarkdownPath: artifactPaths.markdownPath,
+    };
+    (0, fs_1.writeJsonFile)(result.artifactJsonPath, result);
+    (0, fs_1.writeTextFile)(result.artifactMarkdownPath, buildNoticesArtifactMarkdown(result));
+    return result;
+}
+async function publishSync(input) {
+    const dryRun = Boolean(input.dryRun);
+    const context = createPublishContext(input, !dryRun);
+    const sourceSyncPrUrls = new Set();
+    const contractsToProcess = loadContractModeContracts(context, input.contractChangeId);
+    const contracts = [];
+    for (const loaded of contractsToProcess) {
+        if (!loaded.doc) {
+            contracts.push({
+                contractChangeId: loaded.row.contractChangeId,
+                name: loaded.row.name,
+                sourceStatusBefore: loaded.row.status,
+                sourceStatusAfter: loaded.row.status,
+                targetResults: [
+                    {
+                        contractChangeId: loaded.row.contractChangeId,
+                        repo: '-',
+                        prUrl: '',
+                        stateBefore: '-',
+                        stateAfter: '-',
+                        status: 'failed',
+                        reason: loaded.loadError ?? 'Unable to load source contract change artifact.',
+                    },
+                ],
+            });
+            continue;
+        }
+        const doc = loaded.doc;
+        const contractResult = {
+            contractChangeId: doc.contractChangeId,
+            name: doc.name,
+            sourceStatusBefore: doc.status,
+            sourceStatusAfter: doc.status,
+            targetResults: [],
+        };
+        for (const target of doc.targets) {
+            const targetResult = {
+                contractChangeId: doc.contractChangeId,
+                repo: target.repo,
+                prUrl: target.prUrl,
+                stateBefore: target.state,
+                stateAfter: target.state,
+                status: 'skipped',
+            };
+            if (!target.prUrl.trim()) {
+                targetResult.reason = 'No pr_url set.';
+                contractResult.targetResults.push(targetResult);
+                continue;
+            }
+            if (dryRun) {
+                targetResult.reason = 'Dry run: would refresh PR lifecycle state.';
+                contractResult.targetResults.push(targetResult);
+                continue;
+            }
+            if (!context.ops) {
+                targetResult.status = 'failed';
+                targetResult.reason = 'GitHub token not available; cannot refresh PR lifecycle.';
+                contractResult.targetResults.push(targetResult);
+                continue;
+            }
+            try {
+                const lifecycle = await context.ops.getPullLifecycle(target.prUrl);
+                const nextState = lifecycleToTargetState(lifecycle);
+                target.state = nextState;
+                targetResult.stateAfter = nextState;
+                targetResult.status = nextState === targetResult.stateBefore ? 'skipped' : 'updated';
+                if (targetResult.status === 'skipped') {
+                    targetResult.reason = 'State unchanged after lifecycle lookup.';
+                }
+                else {
+                    loaded.sourceChanged = true;
+                }
+            }
+            catch (error) {
+                targetResult.status = 'failed';
+                targetResult.reason = formatError(error);
+            }
+            contractResult.targetResults.push(targetResult);
+        }
+        doc.status = (0, contractChanges_1.computeContractChangeStatus)(doc.status, doc.targets);
+        contractResult.sourceStatusAfter = doc.status;
+        updateIndexRowFromDoc(loaded.row, doc);
+        if (!dryRun && loaded.sourceChanged) {
+            try {
+                const sourceSyncPrUrl = await upsertSourceSync(context, doc, false);
+                contractResult.sourceSyncPrUrl = sourceSyncPrUrl;
+                sourceSyncPrUrls.add(sourceSyncPrUrl);
+            }
+            catch (error) {
+                contractResult.targetResults.push({
+                    contractChangeId: doc.contractChangeId,
+                    repo: context.sourceRepoParts.fullName,
+                    prUrl: '',
+                    stateBefore: contractResult.sourceStatusBefore,
+                    stateAfter: contractResult.sourceStatusAfter,
+                    status: 'failed',
+                    reason: `Source sync failed: ${formatError(error)}`,
+                });
+            }
+        }
+        contracts.push(contractResult);
+    }
+    const artifactPaths = ensureArtifactPaths(context.cwd, 'sync', input.mapId, input.contractChangeId);
+    const result = {
+        schemaVersion: constants_1.SCHEMA_VERSION,
+        generatedAt: nowIso(),
+        mapId: input.mapId,
+        sourceRepo: context.sourceRepoParts.fullName,
+        contractChangeId: input.contractChangeId,
+        dryRun,
+        totals: totalsForSync(contracts),
+        contracts,
+        sourceSyncPrUrls: [...sourceSyncPrUrls].sort((a, b) => a.localeCompare(b)),
+        artifactJsonPath: artifactPaths.jsonPath,
+        artifactMarkdownPath: artifactPaths.markdownPath,
+    };
+    (0, fs_1.writeJsonFile)(result.artifactJsonPath, result);
+    (0, fs_1.writeTextFile)(result.artifactMarkdownPath, buildSyncArtifactMarkdown(result));
+    return result;
+}