@captain_z/zsk 1.8.1 → 1.8.2

package/dist/core/prepare-sync.js

@@ -0,0 +1,1499 @@
+import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
+import { copyFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { DESIGN_LOCAL_FILE_ORIGIN_KEYS, JIRA_LOCAL_FILE_ORIGIN_KEYS, flattenProjectSources, resolveSourceSnapshot, } from "./config.js";
+import { inferSourceOrigin } from "./origin-detection.js";
+import { describeResource, updateRawIndexes, updateRawManifest } from "./raw-manifest.js";
+import { getWorkspacePath } from "./workspace-layout.js";
+export function resolvePrepareSyncArtifacts(target, config, runId) {
+    const dir = resolve(target, getWorkspacePath(config, "evidenceRoot"), "prepare", runId);
+    const authDir = resolve(target, getWorkspacePath(config, "playwrightRoot"), ".auth");
+    return {
+        runId,
+        dir,
+        adapterResultsDir: join(dir, "adapter-results"),
+        authCheckPath: join(dir, "auth-check.json"),
+        downstreamImpactPath: join(dir, "downstream-impact.md"),
+        authScriptPath: join(authDir, "login.mjs"),
+        authStatePath: join(authDir, "user_data.json"),
+        migrationPlanPath: join(dir, "raws-migration-plan.md"),
+    };
+}
+export async function syncPrepareSources(target, config, opts = {}) {
+    const runId = opts.runId ?? createSyncRunId();
+    const artifacts = resolvePrepareSyncArtifacts(target, config, runId);
+    const entries = flattenProjectSources(config.sources);
+    const selected = new Set(selectSourceEntries(entries, opts));
+    const results = [];
+    await mkdir(artifacts.adapterResultsDir, { recursive: true });
+    for (const entry of entries) {
+        if (!selected.has(entry))
+            continue;
+        const result = await syncEntry(target, config, entry, opts);
+        results.push(result);
+        await writeFile(join(artifacts.adapterResultsDir, `${safeFileName(entry.id)}.json`), `${JSON.stringify(result, null, 2)}\n`, "utf8");
+    }
+    if (!opts.dryRun) {
+        const records = [];
+        for (const entry of entries) {
+            records.push(await describeResource(target, entry.provider, { ...entry.source, snapshot: resolveSourceSnapshot(config, entry) }, { role: entry.rawLane, sourcePath: entry.path }));
+        }
+        await updateRawManifest(resolve(target, getWorkspacePath(config, "resourcesManifest")), records);
+        await updateRawIndexes(target, getWorkspacePath(config, "resourcesRoot"), records);
+    }
+    const downstreamImpact = renderDownstreamImpact(results);
+    await mkdir(dirname(artifacts.downstreamImpactPath), { recursive: true });
+    await writeFile(artifacts.downstreamImpactPath, downstreamImpact, "utf8");
+    return {
+        artifacts,
+        results,
+        downstreamImpact,
+    };
+}
+export async function writeAuthLoginHelper(target, config, opts = {}) {
+    const artifacts = resolvePrepareSyncArtifacts(target, config, opts.runId ?? createSyncRunId());
+    const statePath = opts.out ? resolve(target, opts.out) : resolveAuthProfilePath(target, config, opts.profile);
+    const authRoot = dirname(artifacts.authScriptPath);
+    if (!isInside(authRoot, statePath)) {
+        throw new Error(`Playwright storageState output must stay under ${authRoot}`);
+    }
+    const script = [
+        `import { chromium } from "playwright";`,
+        ``,
+        `const targetUrl = process.env.ZSK_PREPARE_AUTH_URL ?? ${JSON.stringify(opts.url ?? "about:blank")};`,
+        `const storageStatePath = process.env.ZSK_PLAYWRIGHT_STORAGE_STATE ?? ${JSON.stringify(statePath)};`,
+        `const browser = await chromium.launch({ headless: false });`,
+        `const context = await browser.newContext();`,
+        `const page = await context.newPage();`,
+        `await page.goto(targetUrl, { waitUntil: "domcontentloaded" });`,
+        `console.log("Complete login in the opened browser, then press Enter here to save storageState.");`,
+        `await new Promise((resolve) => process.stdin.once("data", resolve));`,
+        `await context.storageState({ path: storageStatePath });`,
+        `console.log(\`Saved Playwright storageState to ${"${storageStatePath}"}\`);`,
+        `await browser.close();`,
+        ``,
+    ].join("\n");
+    await mkdir(dirname(artifacts.authScriptPath), { recursive: true });
+    await writeFile(artifacts.authScriptPath, script, "utf8");
+    return { ...artifacts, authStatePath: statePath };
+}
+export async function checkPrepareAuth(target, config, opts = {}) {
+    const runId = opts.runId ?? createSyncRunId();
+    const artifacts = resolvePrepareSyncArtifacts(target, config, runId);
+    const entries = selectSourceEntries(flattenProjectSources(config.sources), opts);
+    const authStatePath = resolveSelectedAuthStatePath(target, config, opts);
+    const results = [];
+    for (const entry of entries) {
+        results.push(await checkAuthEntry(entry, authStatePath, opts));
+    }
+    await mkdir(dirname(artifacts.authCheckPath), { recursive: true });
+    await writeFile(artifacts.authCheckPath, `${JSON.stringify({ runId, results }, null, 2)}\n`, "utf8");
+    return { artifacts, results };
+}
+export async function buildRawMigrationPlan(target, config, runId = createSyncRunId()) {
+    const artifacts = resolvePrepareSyncArtifacts(target, config, runId);
+    const prepareRoot = resolve(target, getWorkspacePath(config, "resourcesRoot"), "prepare");
+    const staleNames = new Set([
+        "qa-engineer",
+        "test-engineer",
+        "backend-engineer",
+        "frontend-engineer",
+        "product-manager",
+        "designer",
+        "jira",
+        "confluence",
+        "figma",
+        "modao",
+        "manual",
+        "provider",
+        "version",
+    ]);
+    const entries = await safeReadDir(prepareRoot);
+    const findings = entries
+        .filter((entry) => entry.isDirectory() && isMigrationLaneCandidate(entry.name, staleNames))
+        .map((entry) => ({
+        path: join(".zsk/raws/prepare", entry.name),
+        action: "dry-run only; keep readable, require explicit migration before rewriting references",
+    }));
+    const content = [
+        "# Raw Migration Plan",
+        "",
+        "Dry-run report only. No files were moved, deleted, or rewritten.",
+        "",
+        findings.length === 0
+            ? "No stale provider/method/version prepare lanes were found."
+            : findings.map((item) => `- \`${item.path}\`: ${item.action}`).join("\n"),
+        "",
+    ].join("\n");
+    await mkdir(dirname(artifacts.migrationPlanPath), { recursive: true });
+    await writeFile(artifacts.migrationPlanPath, content, "utf8");
+    return { artifacts, content };
+}
+function selectSourceEntries(entries, opts) {
+    if (opts.all || !opts.source)
+        return entries;
+    const selector = opts.source;
+    const exact = entries.filter((entry) => entry.id === selector || entry.path === selector || entry.segments.join(".") === selector);
+    if (exact.length > 0)
+        return exact;
+    const alias = entries.filter((entry) => entry.provider === selector);
+    if (alias.length > 1) {
+        const matches = alias.map((entry) => `${entry.path} (${entry.id})`).join(", ");
+        throw new Error(`source selector "${selector}" matched multiple configured sources: ${matches}. Use a source path or path-scoped id.`);
+    }
+    return alias;
+}
+async function checkAuthEntry(entry, authStatePath, opts) {
+    const origin = inferSourceOrigin(entry.source);
+    const base = {
+        sourceKey: entry.id,
+        sourcePath: entry.path,
+        rawLane: entry.rawLane,
+        provider: origin.provider,
+        origin: origin.ref,
+        method: origin.method,
+    };
+    const url = origin.ref;
+    if (!url || origin.method !== "url") {
+        return {
+            ...base,
+            status: "source-gap",
+            authSources: [],
+            directAuthAvailable: false,
+            networkAttempted: false,
+            reason: "auth-check only validates URL origins; configure origin.url before checking runtime credentials",
+            validation: { urlOrigin: "fail", secretValuesHidden: "pass" },
+        };
+    }
+    const { headers, authSources } = await headersForSource(entry.source, url, authStatePath);
+    const directAuthAvailable = Boolean(headers.authorization || headers.cookie);
+    if (!opts.allowNetwork) {
+        return {
+            ...base,
+            status: directAuthAvailable ? "ready" : "missing-auth",
+            authSources,
+            directAuthAvailable,
+            networkAttempted: false,
+            reason: directAuthAvailable
+                ? "runtime credential source is available; rerun with --allow-network to validate reachability without writing snapshots"
+                : "no source-bound runtime credential was found; configure origin.auth env names with exported values or create a Playwright auth profile",
+            validation: {
+                runtimeAuth: directAuthAvailable ? "pass" : "fail",
+                networkSkipped: "pass",
+                secretValuesHidden: "pass",
+            },
+        };
+    }
+    try {
+        const response = await fetch(url, { headers });
+        const contentType = response.headers.get("content-type") ?? "";
+        const body = await response.text();
+        if (!response.ok) {
+            return {
+                ...base,
+                status: response.status === 401 || response.status === 403 ? "blocked-auth" : "failed",
+                authSources,
+                directAuthAvailable,
+                networkAttempted: true,
+                httpStatus: response.status,
+                contentType,
+                reason: `auth-check fetch returned HTTP ${response.status}`,
+                validation: { httpOk: "fail", secretValuesHidden: "pass" },
+            };
+        }
+        if (looksLikeLoginPage(body, response.url)) {
+            return {
+                ...base,
+                status: "blocked-auth",
+                authSources,
+                directAuthAvailable,
+                networkAttempted: true,
+                httpStatus: response.status,
+                contentType,
+                reason: "auth-check fetch resolved to login/chrome content",
+                validation: { httpOk: "pass", loginPageRejected: "fail", secretValuesHidden: "pass" },
+            };
+        }
+        const content = extractRemoteContent(contentType, body);
+        if (!hasMaterialContent(content)) {
+            return {
+                ...base,
+                status: "source-gap",
+                authSources,
+                directAuthAvailable,
+                networkAttempted: true,
+                httpStatus: response.status,
+                contentType,
+                reason: "auth-check fetch produced no material body content",
+                validation: { httpOk: "pass", bodyContent: "fail", secretValuesHidden: "pass" },
+            };
+        }
+        return {
+            ...base,
+            status: "reachable",
+            authSources,
+            directAuthAvailable,
+            networkAttempted: true,
+            httpStatus: response.status,
+            contentType,
+            reason: "auth-check reached material content without writing a snapshot",
+            validation: { httpOk: "pass", loginPageRejected: "pass", bodyContent: "pass", secretValuesHidden: "pass" },
+        };
+    }
+    catch (error) {
+        return {
+            ...base,
+            status: "failed",
+            authSources,
+            directAuthAvailable,
+            networkAttempted: true,
+            reason: `auth-check fetch failed: ${error instanceof Error ? error.message : String(error)}`,
+            validation: { httpOk: "fail", secretValuesHidden: "pass" },
+        };
+    }
+}
+async function syncEntry(target, config, entry, opts) {
+    const source = entry.source;
+    const origin = inferSourceOrigin(source);
+    const snapshot = resolveSourceSnapshot(config, entry);
+    const snapshotPath = resolve(target, snapshot);
+    const previousSnapshotHash = await hashIfExists(snapshotPath);
+    const base = {
+        envelopeVersion: 1,
+        sourceKey: entry.id,
+        sourcePath: entry.path,
+        rawLane: entry.rawLane,
+        provider: origin.provider,
+        origin: origin.ref,
+        snapshot,
+        previousSnapshotHash,
+    };
+    if (opts.dryRun) {
+        return {
+            ...base,
+            strategy: chooseStrategy(origin.method),
+            status: "skipped",
+            changed: false,
+            reason: "dry-run requested; no snapshot was written",
+            validation: { dryRun: "pass" },
+        };
+    }
+    if (origin.method === "local") {
+        const sourcePath = source.origin?.path ?? source.path;
+        if (!sourcePath) {
+            return sourceGap(base, "configured local origin has no path");
+        }
+        const originPath = resolve(target, sourcePath);
+        if (!(await exists(originPath))) {
+            return sourceGap(base, "configured local origin path does not exist");
+        }
+        await mkdir(dirname(snapshotPath), { recursive: true });
+        if (shouldPreserveMachineReadable(source, originPath, snapshotPath)) {
+            await copyFile(originPath, snapshotPath);
+        }
+        else {
+            await writeFile(snapshotPath, await renderStructuredLocalMarkdown(target, entry, originPath), "utf8");
+        }
+        const snapshotHash = await sha256(snapshotPath);
+        return {
+            ...base,
+            strategy: "local-copy-structured-markdown",
+            status: "materialized",
+            snapshotHash,
+            changed: previousSnapshotHash !== snapshotHash,
+            reason: "local origin copied or materialized into configured snapshot",
+            validation: { sourceExists: "pass", bodyContent: "pass", snapshotWritten: "pass" },
+        };
+    }
+    const providerAdapter = selectProviderAdapter(source, origin);
+    if (providerAdapter) {
+        const authStatePath = resolveSelectedAuthStatePath(target, config, opts);
+        const adapterResult = await runProviderAdapter(providerAdapter, target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts);
+        if (adapterResult) {
+            if (adapterResult.status === "blocked-auth" && opts.browser && origin.method === "url") {
+                const browserResult = await fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
+                return {
+                    ...browserResult,
+                    adapter: `${providerAdapter}-browser-fallback`,
+                    metadata: cleanMetadata({ providerAdapter, fallbackFrom: adapterResult.strategy }),
+                };
+            }
+            return adapterResult;
+        }
+    }
+    if (origin.method === "repository") {
+        await mkdir(dirname(snapshotPath), { recursive: true });
+        const content = renderRepositoryMetadata(entry, origin.ref ?? "");
+        await writeFile(snapshotPath, content, "utf8");
+        const snapshotHash = await sha256(snapshotPath);
+        return {
+            ...base,
+            strategy: "repository-metadata-only",
+            status: "metadata-only",
+            snapshotHash,
+            changed: previousSnapshotHash !== snapshotHash,
+            reason: "repository origin recorded as metadata; configure contract paths or checkout policy before broad acquisition",
+            validation: { repositoryNotCrawled: "pass", snapshotWritten: "pass" },
+        };
+    }
+    if (origin.method === "url") {
+        if (!opts.allowNetwork) {
+            return {
+                ...base,
+                strategy: "playwright-auth-or-direct-fetch",
+                status: "blocked-auth",
+                changed: false,
+                reason: "remote URL requires --allow-network or a materialized snapshot; Playwright auth helper can create reusable storageState first",
+                validation: { networkAllowed: "fail", previousSnapshotPreserved: previousSnapshotHash ? "pass" : "skipped" },
+            };
+        }
+        const authStatePath = resolveSelectedAuthStatePath(target, config, opts);
+        if (opts.browser) {
+            if (origin.ref && await hasDirectRuntimeAuthForSource(source, origin.ref, authStatePath)) {
+                const direct = await fetchUrlSnapshot(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
+                if (direct.status === "materialized")
+                    return direct;
+            }
+            return fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
+        }
+        return fetchUrlSnapshot(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
+    }
+    return {
+        ...base,
+        strategy: "confirm-acquisition-method",
+        status: "blocked-auth",
+        changed: false,
+        reason: "provider-managed origin needs an explicit acquisition method or exported snapshot",
+        validation: { acquisitionMethodConfirmed: "fail", previousSnapshotPreserved: previousSnapshotHash ? "pass" : "skipped" },
+    };
+}
+function selectProviderAdapter(source, origin) {
+    const keys = [
+        origin.provider,
+        origin.kind,
+        source.origin?.provider,
+        source.origin?.kind,
+        source.kind,
+        source.type,
+    ].map((value) => normalizeAdapterKey(typeof value === "string" ? value : undefined));
+    if (keys.some((value) => value.includes("confluence")))
+        return "confluence";
+    if (keys.some((value) => value.includes("jira")))
+        return "jira";
+    if (keys.some((value) => value.includes("gitlab")))
+        return "gitlab";
+    if (keys.some((value) => ["figma", "modao", "mastergo", "design", "design-asset", "design-source"].includes(value))) {
+        return "design-source";
+    }
+    return undefined;
+}
+async function runProviderAdapter(adapter, target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts) {
+    if (adapter === "confluence") {
+        return runConfluenceAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts);
+    }
+    if (adapter === "jira") {
+        return runJiraAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts);
+    }
+    if (adapter === "gitlab") {
+        return runGitLabAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts);
+    }
+    return runDesignAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts);
+}
+async function runConfluenceAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts) {
+    const base = adapterBase(target, entry, snapshotPath, previousSnapshotHash, "confluence");
+    const url = firstOriginString(entry.source, "apiUrl", "restUrl", "url") ?? base.origin;
+    const strategy = "confluence-storage-rest";
+    if (!url)
+        return sourceGap(base, "confluence adapter needs origin.url, origin.apiUrl, or origin.restUrl");
+    if (!opts.allowNetwork) {
+        return blockedAdapter(base, strategy, "confluence source requires --allow-network and optional Playwright storageState before acquisition");
+    }
+    const fetched = await fetchAdapterBody(entry.source, url, authStatePath);
+    if (!fetched.ok)
+        return blockedAdapter(base, strategy, fetched.reason);
+    if (looksLikeLoginPage(fetched.body, fetched.resolvedOrigin)) {
+        return blockedAdapter(base, strategy, "confluence adapter resolved to login/chrome content; previous snapshot was preserved");
+    }
+    const parsed = parseJsonObject(fetched.body);
+    const title = parsed ? stringValue(parsed, "title") : undefined;
+    const pageId = parsed ? firstStringValue(parsed, "id", "pageId", "contentId") : undefined;
+    const version = parsed ? versionValue(parsed) : undefined;
+    const storageHtml = parsed ? confluenceBodyValue(parsed) : undefined;
+    const content = storageHtml
+        ? htmlToStructuredMarkdown(storageHtml)
+        : fetched.contentType.includes("html")
+            ? htmlToStructuredMarkdown(fetched.body)
+            : fencedBody(fetched.body, fetched.contentType);
+    if (!hasMaterialContent(content)) {
+        return blockedAdapter(base, strategy, "confluence adapter produced no material body content; previous snapshot was preserved");
+    }
+    return writeAdapterSnapshot(target, entry, snapshotPath, previousSnapshotHash, {
+        adapter: "confluence",
+        strategy,
+        resolvedOrigin: fetched.resolvedOrigin,
+        contentType: fetched.contentType,
+        content,
+        reason: "confluence source fetched and normalized into structured Markdown",
+        metadata: cleanMetadata({ title, pageId, version, runtimeAuth: fetched.authSources.join(", ") || undefined }),
+        validation: { httpOk: "pass", loginPageRejected: "pass", bodyContent: "pass", snapshotWritten: "pass" },
+    });
+}
+async function runJiraAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts) {
+    const base = adapterBase(target, entry, snapshotPath, previousSnapshotHash, "jira");
+    const csvPath = firstOriginString(entry.source, ...JIRA_LOCAL_FILE_ORIGIN_KEYS);
+    if (csvPath) {
+        const path = resolveAdapterLocalFilePath(target, csvPath);
+        if (!path)
+            return failed(base, "jira CSV fallback path must stay inside the target project");
+        if (!(await exists(path)))
+            return sourceGap(base, "jira CSV fallback path does not exist");
+        const csv = await readFile(path, "utf8");
+        const rows = parseCsvRows(csv);
+        const content = renderJiraCsvMarkdown(rows, csvPath);
+        if (!hasMaterialContent(content)) {
+            return blockedAdapter(base, "jira-csv-import", "jira CSV fallback produced no material issue content; previous snapshot was preserved");
+        }
+        return writeAdapterSnapshot(target, entry, snapshotPath, previousSnapshotHash, {
+            adapter: "jira",
+            strategy: "jira-csv-import",
+            resolvedOrigin: csvPath,
+            contentType: "text/csv",
+            content,
+            reason: "jira CSV export imported and normalized into structured Markdown",
+            metadata: cleanMetadata({ issueCount: rows.length, fallback: "csv" }),
+            validation: { sourceExists: "pass", bodyContent: "pass", snapshotWritten: "pass" },
+        });
+    }
+    const url = firstOriginString(entry.source, "apiUrl", "searchUrl", "url") ?? (base.origin?.startsWith("http") || base.origin?.startsWith("data:") ? base.origin : undefined);
+    if (!url)
+        return null;
+    const strategy = "jira-rest-search";
+    if (!opts.allowNetwork) {
+        return blockedAdapter(base, strategy, "jira REST source requires --allow-network and optional Playwright storageState before acquisition");
+    }
+    const fetched = await fetchAdapterBody(entry.source, url, authStatePath);
+    if (!fetched.ok)
+        return blockedAdapter(base, strategy, fetched.reason);
+    if (looksLikeLoginPage(fetched.body, fetched.resolvedOrigin)) {
+        return blockedAdapter(base, strategy, "jira adapter resolved to login/chrome content; previous snapshot was preserved");
+    }
+    const parsed = parseJsonObject(fetched.body);
+    const content = parsed ? renderJiraRestMarkdown(parsed) : fencedBody(fetched.body, fetched.contentType);
+    if (!hasMaterialContent(content)) {
+        return blockedAdapter(base, strategy, "jira adapter produced no material issue content; previous snapshot was preserved");
+    }
+    return writeAdapterSnapshot(target, entry, snapshotPath, previousSnapshotHash, {
+        adapter: "jira",
+        strategy,
+        resolvedOrigin: fetched.resolvedOrigin,
+        contentType: fetched.contentType,
+        content,
+        reason: "jira REST source fetched and normalized into structured Markdown",
+        metadata: cleanMetadata({ issueCount: jiraIssueCount(parsed), runtimeAuth: fetched.authSources.join(", ") || undefined }),
+        validation: { httpOk: "pass", loginPageRejected: "pass", bodyContent: "pass", snapshotWritten: "pass" },
+    });
+}
+async function runGitLabAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts) {
+    const base = adapterBase(target, entry, snapshotPath, previousSnapshotHash, "gitlab");
+    const url = firstOriginString(entry.source, "rawUrl", "apiUrl", "url");
+    if (!url)
+        return null;
+    const strategy = "gitlab-raw-or-file-api";
+    if (!opts.allowNetwork) {
+        return blockedAdapter(base, strategy, "gitlab source requires --allow-network and optional token/storageState before acquisition");
+    }
+    const fetched = await fetchAdapterBody(entry.source, url, authStatePath);
+    if (!fetched.ok)
+        return blockedAdapter(base, strategy, fetched.reason);
+    if (looksLikeLoginPage(fetched.body, fetched.resolvedOrigin)) {
+        return blockedAdapter(base, strategy, "gitlab adapter resolved to login/chrome content; previous snapshot was preserved");
+    }
+    const parsed = parseJsonObject(fetched.body);
+    const fileContent = parsed ? gitLabFileContent(parsed) : undefined;
+    const content = fileContent
+        ? fencedBody(fileContent.content, fileContent.contentType)
+        : fetched.contentType.includes("html")
+            ? htmlToStructuredMarkdown(fetched.body)
+            : fencedBody(fetched.body, fetched.contentType);
+    if (!hasMaterialContent(content)) {
+        return blockedAdapter(base, strategy, "gitlab adapter produced no material file content; previous snapshot was preserved");
+    }
+    return writeAdapterSnapshot(target, entry, snapshotPath, previousSnapshotHash, {
+        adapter: "gitlab",
+        strategy,
+        resolvedOrigin: fetched.resolvedOrigin,
+        contentType: fileContent?.contentType ?? fetched.contentType,
+        content,
+        reason: "gitlab file source fetched and normalized into structured Markdown",
+        metadata: cleanMetadata({
+            filePath: parsed ? firstStringValue(parsed, "file_path", "path", "name") : undefined,
+            ref: parsed ? firstStringValue(parsed, "ref", "branch") : undefined,
+            runtimeAuth: fetched.authSources.join(", ") || undefined,
+        }),
+        validation: { httpOk: "pass", loginPageRejected: "pass", bodyContent: "pass", snapshotWritten: "pass" },
+    });
+}
+async function runDesignAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts) {
+    const base = adapterBase(target, entry, snapshotPath, previousSnapshotHash, "design-source");
+    const exportPath = firstOriginString(entry.source, ...DESIGN_LOCAL_FILE_ORIGIN_KEYS);
+    if (exportPath) {
+        const path = resolveAdapterLocalFilePath(target, exportPath);
+        if (!path)
+            return failed(base, "design export path must stay inside the target project");
+        if (!(await exists(path)))
+            return sourceGap(base, "design export path does not exist");
+        const body = await readFile(path, "utf8");
+        const content = renderDesignMarkdown(body, `file:${exportPath}`, contentTypeForPath(exportPath));
+        if (!hasMaterialContent(content)) {
+            return blockedAdapter(base, "design-export-import", "design export produced no material content; previous snapshot was preserved");
+        }
+        return writeAdapterSnapshot(target, entry, snapshotPath, previousSnapshotHash, {
+            adapter: "design-source",
+            strategy: "design-export-import",
+            resolvedOrigin: exportPath,
+            contentType: contentTypeForPath(exportPath),
+            content,
+            reason: "design export imported and normalized into structured Markdown",
+            metadata: cleanMetadata({ provider: base.provider, fallback: "export" }),
+            validation: { sourceExists: "pass", bodyContent: "pass", snapshotWritten: "pass" },
+        });
+    }
+    const url = firstOriginString(entry.source, "apiUrl", "exportUrl", "url") ?? base.origin;
+    if (!url)
+        return null;
+    if (!opts.allowNetwork) {
+        return blockedAdapter(base, opts.browser ? "design-browser-render" : "design-api-or-browser", "design source requires --allow-network with token/export URL or --browser storageState acquisition");
+    }
+    const directRuntimeAuth = await hasDirectRuntimeAuthForSource(entry.source, url, authStatePath);
+    if (opts.browser && !directRuntimeAuth) {
+        const rendered = await fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
+        return {
+            ...rendered,
+            adapter: "design-source",
+            metadata: cleanMetadata({ provider: base.provider, acquisition: "browser" }),
+        };
+    }
+    const fetched = await fetchAdapterBody(entry.source, url, authStatePath);
+    if (!fetched.ok) {
+        if (opts.browser)
+            return fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
+        return blockedAdapter(base, "design-api-or-export", fetched.reason);
+    }
+    if (looksLikeLoginPage(fetched.body, fetched.resolvedOrigin)) {
+        if (opts.browser)
+            return fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
+        return blockedAdapter(base, "design-api-or-export", "design adapter resolved to login/chrome content; previous snapshot was preserved");
+    }
+    const content = renderDesignMarkdown(fetched.body, fetched.resolvedOrigin, fetched.contentType);
+    if (!hasMaterialContent(content)) {
+        if (opts.browser)
+            return fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
+        return blockedAdapter(base, "design-api-or-export", "design adapter produced no material design content; previous snapshot was preserved");
+    }
+    return writeAdapterSnapshot(target, entry, snapshotPath, previousSnapshotHash, {
+        adapter: "design-source",
+        strategy: "design-api-or-export",
+        resolvedOrigin: fetched.resolvedOrigin,
+        contentType: fetched.contentType,
+        content,
+        reason: "design source fetched and normalized into structured Markdown",
+        metadata: cleanMetadata({ provider: base.provider, runtimeAuth: fetched.authSources.join(", ") || undefined }),
+        validation: { httpOk: "pass", loginPageRejected: "pass", bodyContent: "pass", snapshotWritten: "pass" },
+    });
+}
+function adapterBase(target, entry, snapshotPath, previousSnapshotHash, adapter) {
+    const origin = inferSourceOrigin(entry.source);
+    return {
+        envelopeVersion: 1,
+        sourceKey: entry.id,
+        sourcePath: entry.path,
+        rawLane: entry.rawLane,
+        provider: origin.provider,
+        adapter,
+        origin: origin.ref,
+        snapshot: relative(target, snapshotPath),
+        previousSnapshotHash,
+    };
+}
+async function writeAdapterSnapshot(target, entry, snapshotPath, previousSnapshotHash, result) {
+    const origin = inferSourceOrigin(entry.source);
+    const markdown = renderAdapterMarkdown(entry, result.resolvedOrigin, result.contentType, result.content, result.strategy, result.adapter, result.metadata);
+    await mkdir(dirname(snapshotPath), { recursive: true });
+    await writeFile(snapshotPath, markdown, "utf8");
+    const snapshotHash = await sha256(snapshotPath);
+    return {
+        envelopeVersion: 1,
+        sourceKey: entry.id,
+        sourcePath: entry.path,
+        rawLane: entry.rawLane,
+        provider: origin.provider,
+        adapter: result.adapter,
+        strategy: result.strategy,
+        status: "materialized",
+        origin: origin.ref,
+        resolvedOrigin: result.resolvedOrigin,
+        contentType: result.contentType,
+        snapshot: relative(target, snapshotPath),
+        snapshotHash,
+        previousSnapshotHash,
+        metadata: result.metadata,
+        changed: previousSnapshotHash !== snapshotHash,
+        reason: result.reason,
+        validation: result.validation,
+    };
+}
+async function fetchAdapterBody(source, url, authStatePath) {
+    const { headers, cookieUsed, authSources } = await headersForSource(source, url, authStatePath);
+    try {
+        const response = await fetch(url, { headers });
+        const contentType = response.headers.get("content-type") ?? "";
+        const body = await response.text();
+        if (!response.ok)
+            return { ok: false, reason: `adapter fetch failed with HTTP ${response.status}` };
+        return { ok: true, resolvedOrigin: response.url, contentType, body, cookieUsed, authSources };
+    }
+    catch (error) {
+        return { ok: false, reason: `adapter fetch failed: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
+async function headersForSource(source, url, authStatePath) {
+    const headers = {};
+    const authSources = [];
+    const token = envValue(authStringList(source, "tokenEnv", "accessTokenEnv", "apiTokenEnv"));
+    if (token.value) {
+        const headerName = firstAuthString(source, "tokenHeader", "headerName") ?? "authorization";
+        const tokenScheme = firstAuthString(source, "tokenScheme", "scheme") ?? "Bearer";
+        headers[headerName] = headerName.toLowerCase() === "authorization" && tokenScheme
+            ? `${tokenScheme} ${token.value}`
+            : token.value;
+        authSources.push(`env:${token.name}`);
+    }
+    const envCookie = cookieHeaderFromEnvironment(source);
+    if (envCookie.source)
+        authSources.push(`env:${envCookie.source}`);
+    const storageCookie = authStatePath ? await cookieHeaderFromStorageState(authStatePath, url) : "";
+    if (storageCookie)
+        authSources.push("playwright-storage-state");
+    const cookie = mergeCookieHeaders(envCookie.value, storageCookie);
+    if (cookie)
+        headers.cookie = cookie;
+    return { headers, cookieUsed: Boolean(cookie), authSources };
+}
+async function hasDirectRuntimeAuthForSource(source, url, authStatePath) {
+    const { headers } = await headersForSource(source, url, authStatePath);
+    return Boolean(headers.authorization || headers.cookie);
+}
+async function fetchUrlSnapshot(target, entry, snapshotPath, previousSnapshotHash, authStatePath) {
+    const origin = inferSourceOrigin(entry.source);
+    const url = origin.ref;
+    const base = {
+        envelopeVersion: 1,
+        sourceKey: entry.id,
+        sourcePath: entry.path,
+        rawLane: entry.rawLane,
+        provider: origin.provider,
+        adapter: "generic-http",
+        origin: url,
+        snapshot: relative(target, snapshotPath),
+        previousSnapshotHash,
+    };
+    if (!url) {
+        return sourceGap(base, "remote URL origin is missing");
+    }
+    const { headers, authSources } = await headersForSource(entry.source, url, authStatePath);
+    try {
+        const response = await fetch(url, { headers });
+        const contentType = response.headers.get("content-type") ?? "";
+        const body = await response.text();
+        if (!response.ok) {
+            return blocked(base, `remote fetch failed with HTTP ${response.status}`);
+        }
+        if (looksLikeLoginPage(body, response.url)) {
+            return blocked(base, "remote fetch resolved to login/chrome content; previous snapshot was preserved");
+        }
+        const content = extractRemoteContent(contentType, body);
+        if (!hasMaterialContent(content)) {
+            return blocked(base, "remote fetch produced no material body content; previous snapshot was preserved");
+        }
+        const markdown = renderRemoteMarkdown(entry, response.url, contentType, content);
+        await mkdir(dirname(snapshotPath), { recursive: true });
+        await writeFile(snapshotPath, markdown, "utf8");
+        const snapshotHash = await sha256(snapshotPath);
+        return {
+            ...base,
+            strategy: authSources.length > 0 ? "runtime-auth-direct-fetch" : "direct-fetch-structured-markdown",
+            status: "materialized",
+            resolvedOrigin: response.url,
+            contentType,
+            snapshotHash,
+            changed: previousSnapshotHash !== snapshotHash,
+            reason: "remote URL fetched and normalized into structured Markdown",
+            metadata: cleanMetadata({ runtimeAuth: authSources.join(", ") || undefined }),
+            validation: { httpOk: "pass", loginPageRejected: "pass", bodyContent: "pass", snapshotWritten: "pass" },
+        };
+    }
+    catch (error) {
+        return blocked(base, `remote fetch failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+async function fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath) {
+    const origin = inferSourceOrigin(entry.source);
+    const url = origin.ref;
+    const base = {
+        envelopeVersion: 1,
+        sourceKey: entry.id,
+        sourcePath: entry.path,
+        rawLane: entry.rawLane,
+        provider: origin.provider,
+        adapter: "generic-browser",
+        origin: url,
+        snapshot: relative(target, snapshotPath),
+        previousSnapshotHash,
+    };
+    if (!url) {
+        return sourceGap(base, "remote URL origin is missing");
+    }
+    let browser = null;
+    try {
+        const playwright = await loadProjectPlaywright(target);
+        browser = await playwright.chromium.launch({ headless: true });
+        const context = await browser.newContext(authStatePath ? { storageState: authStatePath } : {});
+        try {
+            const page = await context.newPage();
+            await page.goto(url, { waitUntil: "networkidle", timeout: 60_000 });
+            const resolvedUrl = page.url();
+            const body = await page.content();
+            if (looksLikeLoginPage(body, resolvedUrl)) {
+                return blocked(base, "browser acquisition resolved to login/chrome content; previous snapshot was preserved");
+            }
+            const content = htmlToStructuredMarkdown(body);
+            if (!hasMaterialContent(content)) {
+                return blocked(base, "browser acquisition produced no material body content; previous snapshot was preserved");
+            }
+            const markdown = renderRemoteMarkdown(entry, resolvedUrl, "text/html; rendered=playwright", content, "playwright-headless-browser");
+            await mkdir(dirname(snapshotPath), { recursive: true });
+            await writeFile(snapshotPath, markdown, "utf8");
+            const snapshotHash = await sha256(snapshotPath);
+            return {
+                ...base,
+                strategy: "playwright-headless-browser",
+                status: "materialized",
+                resolvedOrigin: resolvedUrl,
+                contentType: "text/html; rendered=playwright",
+                snapshotHash,
+                changed: previousSnapshotHash !== snapshotHash,
+                reason: "remote URL rendered through Playwright and normalized into structured Markdown",
+                validation: { browserRendered: "pass", loginPageRejected: "pass", bodyContent: "pass", snapshotWritten: "pass" },
+            };
+        }
+        finally {
+            await context.close().catch(() => undefined);
+        }
+    }
+    catch (error) {
+        return failed(base, `browser acquisition failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        await browser?.close().catch(() => undefined);
+    }
+}
+async function renderStructuredLocalMarkdown(target, entry, originPath) {
+    const raw = await readFile(originPath, "utf8");
+    return [
+        "---",
+        `sourceKey: ${JSON.stringify(entry.id)}`,
+        `sourcePath: ${JSON.stringify(entry.path)}`,
+        entry.provider !== entry.id ? `sourceAlias: ${JSON.stringify(entry.provider)}` : undefined,
+        `origin: ${JSON.stringify(relative(target, originPath))}`,
+        `extractionMethod: "local-file-copy"`,
+        `extractedAt: ${JSON.stringify(new Date().toISOString())}`,
+        `snapshotStatus: "materialized-page"`,
+        "---",
+        "",
+        "# Source Snapshot",
+        "",
+        "## Provenance",
+        "",
+        `- Source key: \`${entry.id}\``,
+        entry.provider !== entry.id ? `- Source alias: \`${entry.provider}\`` : undefined,
+        `- Origin: \`${relative(target, originPath)}\``,
+        "- Method: local-file-copy",
+        "",
+        "## Content",
+        "",
+        raw.trimEnd(),
+        "",
+    ].filter((line) => typeof line === "string").join("\n");
+}
+function renderRemoteMarkdown(entry, resolvedUrl, contentType, content, extractionMethod = "direct-fetch") {
+    return [
+        "---",
+        `sourceKey: ${JSON.stringify(entry.id)}`,
+        `sourcePath: ${JSON.stringify(entry.path)}`,
+        entry.provider !== entry.id ? `sourceAlias: ${JSON.stringify(entry.provider)}` : undefined,
+        `origin: ${JSON.stringify(resolvedUrl)}`,
+        `contentType: ${JSON.stringify(contentType)}`,
+        `extractionMethod: ${JSON.stringify(extractionMethod)}`,
+        `extractedAt: ${JSON.stringify(new Date().toISOString())}`,
+        `snapshotStatus: "materialized-page"`,
+        "---",
+        "",
+        "# Source Snapshot",
+        "",
+        "## Provenance",
+        "",
+        `- Source key: \`${entry.id}\``,
+        entry.provider !== entry.id ? `- Source alias: \`${entry.provider}\`` : undefined,
+        `- Resolved URL: \`${resolvedUrl}\``,
+        `- Method: ${extractionMethod}`,
+        "",
+        "## Content",
+        "",
+        content.trimEnd(),
+        "",
+    ].filter((line) => typeof line === "string").join("\n");
+}
+function renderAdapterMarkdown(entry, resolvedOrigin, contentType, content, extractionMethod, adapter, metadata) {
+    const metadataLines = metadata && Object.keys(metadata).length > 0
+        ? [
+            "## Adapter Metadata",
+            "",
+            ...Object.entries(metadata).map(([key, value]) => `- ${key}: \`${String(value)}\``),
+            "",
+        ]
+        : [];
+    return [
+        "---",
+        `sourceKey: ${JSON.stringify(entry.id)}`,
+        `sourcePath: ${JSON.stringify(entry.path)}`,
+        entry.provider !== entry.id ? `sourceAlias: ${JSON.stringify(entry.provider)}` : undefined,
+        `origin: ${JSON.stringify(resolvedOrigin)}`,
+        `contentType: ${JSON.stringify(contentType)}`,
+        `adapter: ${JSON.stringify(adapter)}`,
+        `extractionMethod: ${JSON.stringify(extractionMethod)}`,
+        `extractedAt: ${JSON.stringify(new Date().toISOString())}`,
+        `snapshotStatus: "materialized-page"`,
+        "---",
+        "",
+        "# Source Snapshot",
+        "",
+        "## Provenance",
+        "",
+        `- Source key: \`${entry.id}\``,
+        entry.provider !== entry.id ? `- Source alias: \`${entry.provider}\`` : undefined,
+        `- Resolved origin: \`${resolvedOrigin}\``,
+        `- Adapter: ${adapter}`,
+        `- Method: ${extractionMethod}`,
+        "",
+        ...metadataLines,
+        "## Content",
+        "",
+        content.trimEnd(),
+        "",
+    ].filter((line) => typeof line === "string").join("\n");
+}
+function extractRemoteContent(contentType, body) {
+    return contentType.includes("html") ? htmlToStructuredMarkdown(body) : fencedBody(body, contentType);
+}
+function confluenceBodyValue(value) {
+    const body = recordValue(value, "body");
+    const storage = recordValue(body, "storage");
+    const view = recordValue(body, "view");
+    return stringValue(storage, "value") ?? stringValue(view, "value") ?? stringValue(value, "content") ?? stringValue(value, "value");
+}
+function versionValue(value) {
+    const version = recordValue(value, "version");
+    const number = version?.number;
+    if (typeof number === "number" || typeof number === "string")
+        return String(number);
+    return firstStringValue(value, "version", "versionNumber");
+}
+function renderJiraCsvMarkdown(rows, origin) {
+    const issues = rows.map((row) => ({
+        key: firstCsvValue(row, "Key", "Issue key", "Issue Key", "key") ?? "",
+        summary: firstCsvValue(row, "Summary", "summary", "Title", "title") ?? "",
+        status: firstCsvValue(row, "Status", "status") ?? "",
+        assignee: firstCsvValue(row, "Assignee", "assignee") ?? "",
+        updated: firstCsvValue(row, "Updated", "updated", "Updated date") ?? "",
+    }));
+    return [
+        "# Jira Issue Export",
+        "",
+        "## Provenance",
+        "",
+        `- Origin: \`${origin}\``,
+        "- Method: jira-csv-import",
+        `- Issues: ${issues.length}`,
+        "",
+        "## Issues",
+        "",
+        "| Key | Status | Assignee | Updated | Summary |",
+        "| --- | --- | --- | --- | --- |",
+        ...issues.map((issue) => `| ${escapeTable(issue.key)} | ${escapeTable(issue.status)} | ${escapeTable(issue.assignee)} | ${escapeTable(issue.updated)} | ${escapeTable(issue.summary)} |`),
+        "",
+    ].join("\n");
+}
+function renderJiraRestMarkdown(value) {
+    const issues = jiraIssues(value);
+    if (issues.length === 0 && stringValue(value, "key")) {
+        issues.push(value);
+    }
+    return [
+        "# Jira Issue Snapshot",
+        "",
+        `Issue count: ${issues.length}`,
+        "",
+        ...issues.flatMap((issue) => renderJiraIssue(issue)),
+        issues.length === 0 ? fencedBody(JSON.stringify(value, null, 2), "application/json") : "",
+        "",
+    ].join("\n");
+}
+function renderJiraIssue(issue) {
+    const fields = recordValue(issue, "fields");
+    const status = recordValue(fields, "status");
+    const assignee = recordValue(fields, "assignee");
+    const key = stringValue(issue, "key") ?? "(unknown)";
+    const summary = stringValue(fields, "summary") ?? stringValue(issue, "summary") ?? "";
+    const description = jiraDescription(fields?.description);
+    return [
+        `## ${key}`,
+        "",
+        summary ? `- Summary: ${summary}` : undefined,
+        stringValue(status, "name") ? `- Status: ${stringValue(status, "name")}` : undefined,
+        stringValue(assignee, "displayName") ? `- Assignee: ${stringValue(assignee, "displayName")}` : undefined,
+        stringValue(fields, "updated") ? `- Updated: ${stringValue(fields, "updated")}` : undefined,
+        description ? "" : undefined,
+        description ? "### Description" : undefined,
+        description ? "" : undefined,
+        description,
+        "",
+    ].filter((line) => typeof line === "string");
+}
+function jiraIssues(value) {
+    const issues = value.issues;
+    return Array.isArray(issues) ? issues.filter(isRecord) : [];
+}
+function jiraIssueCount(value) {
+    if (!value)
+        return undefined;
+    const issues = jiraIssues(value);
+    if (issues.length > 0)
+        return issues.length;
+    return stringValue(value, "key") ? 1 : undefined;
+}
+function jiraDescription(value) {
+    if (typeof value === "string")
+        return value;
+    if (!value)
+        return undefined;
+    return JSON.stringify(value, null, 2);
+}
+function gitLabFileContent(value) {
+    const content = stringValue(value, "content");
+    if (!content)
+        return undefined;
+    const encoding = stringValue(value, "encoding");
+    if (encoding === "base64") {
+        return { content: Buffer.from(content, "base64").toString("utf8"), contentType: contentTypeForPath(firstStringValue(value, "file_path", "path", "name") ?? "") };
+    }
+    return { content, contentType: contentTypeForPath(firstStringValue(value, "file_path", "path", "name") ?? "") };
+}
+function renderDesignMarkdown(body, origin, contentType) {
+    const parsed = parseJsonObject(body);
+    if (!parsed) {
+        return contentType.includes("html") ? htmlToStructuredMarkdown(body) : fencedBody(body, contentType);
+    }
+    const name = firstStringValue(parsed, "name", "title", "fileName") ?? "Design Source";
+    const modified = firstStringValue(parsed, "lastModified", "updatedAt", "modifiedAt");
+    const nodes = designNodeNames(parsed).slice(0, 80);
+    return [
+        "# Design Source",
+        "",
+        `- Origin: \`${origin}\``,
+        `- Name: ${name}`,
+        modified ? `- Last modified: ${modified}` : undefined,
+        `- Indexed nodes: ${nodes.length}`,
+        "",
+        nodes.length > 0 ? "## Nodes" : undefined,
+        nodes.length > 0 ? "" : undefined,
+        ...nodes.map((node) => `- ${node}`),
+        "",
+        "## Raw Metadata",
+        "",
+        fencedBody(JSON.stringify(parsed, null, 2), "application/json"),
+        "",
+    ].filter((line) => typeof line === "string").join("\n");
+}
+function designNodeNames(value) {
+    if (Array.isArray(value))
+        return value.flatMap(designNodeNames);
+    if (!isRecord(value))
+        return [];
+    const current = stringValue(value, "name") ?? stringValue(value, "title");
+    const children = value.children;
+    const nested = Array.isArray(children) ? children.flatMap(designNodeNames) : [];
+    return current ? [current, ...nested] : nested;
+}
+function parseCsvRows(value) {
+    const rows = parseCsv(value).filter((row) => row.some((cell) => cell.trim().length > 0));
+    const headers = rows.shift() ?? [];
+    return rows.map((row) => {
+        const record = {};
+        headers.forEach((header, index) => {
+            if (header.trim())
+                record[header.trim()] = row[index]?.trim() ?? "";
+        });
+        return record;
+    });
+}
+function parseCsv(value) {
+    const rows = [];
+    let row = [];
+    let cell = "";
+    let quoted = false;
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index];
+        const next = value[index + 1];
+        if (char === "\"" && quoted && next === "\"") {
+            cell += "\"";
+            index += 1;
+            continue;
+        }
+        if (char === "\"") {
+            quoted = !quoted;
+            continue;
+        }
+        if (char === "," && !quoted) {
+            row.push(cell);
+            cell = "";
+            continue;
+        }
+        if ((char === "\n" || char === "\r") && !quoted) {
+            if (char === "\r" && next === "\n")
+                index += 1;
+            row.push(cell);
+            rows.push(row);
+            row = [];
+            cell = "";
+            continue;
+        }
+        cell += char ?? "";
+    }
+    row.push(cell);
+    rows.push(row);
+    return rows;
+}
+function parseJsonObject(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function recordValue(value, key) {
+    if (!isRecord(value))
+        return undefined;
+    const item = value[key];
+    return isRecord(item) ? item : undefined;
+}
+function stringValue(value, key) {
+    if (!isRecord(value))
+        return undefined;
+    const item = value[key];
+    return typeof item === "string" && item.trim().length > 0 ? item : undefined;
+}
+function firstStringValue(value, ...keys) {
+    for (const key of keys) {
+        const item = value[key];
+        if (typeof item === "string" && item.trim().length > 0)
+            return item;
+        if (typeof item === "number")
+            return String(item);
+    }
+    return undefined;
+}
+function firstCsvValue(row, ...keys) {
+    for (const key of keys) {
+        const value = row[key];
+        if (value && value.trim().length > 0)
+            return value.trim();
+    }
+    return undefined;
+}
+function firstOriginString(source, ...keys) {
+    const origin = source.origin;
+    if (!origin)
+        return undefined;
+    for (const key of keys) {
+        const value = origin[key];
+        if (typeof value === "string" && value.trim().length > 0)
+            return value.trim();
+    }
+    return undefined;
+}
+function firstAuthString(source, ...keys) {
+    const auth = authConfig(source);
+    for (const key of keys) {
+        const value = auth?.[key];
+        if (typeof value === "string" && value.trim().length > 0)
+            return value.trim();
+    }
+    return firstOriginString(source, ...keys);
+}
+function authStringList(source, ...keys) {
+    const values = [];
+    const auth = authConfig(source);
+    for (const key of keys) {
+        values.push(...stringListValue(auth?.[key]));
+    }
+    for (const key of keys) {
+        values.push(...stringListValue(source.origin?.[key]));
+    }
+    return Array.from(new Set(values));
+}
+function authCookieMap(source) {
+    const cookies = recordValue(authConfig(source), "cookies");
+    if (!cookies)
+        return {};
+    const result = {};
+    for (const [cookieName, envName] of Object.entries(cookies)) {
+        if (typeof envName === "string" && envName.trim().length > 0) {
+            result[cookieName] = envName.trim();
+        }
+    }
+    return result;
+}
+function authConfig(source) {
+    const auth = source.origin?.auth;
+    return isRecord(auth) ? auth : undefined;
+}
+function stringListValue(value) {
+    if (typeof value === "string" && value.trim().length > 0)
+        return [value.trim()];
+    if (Array.isArray(value)) {
+        return value.filter((item) => typeof item === "string" && item.trim().length > 0).map((item) => item.trim());
+    }
+    return [];
+}
+function envValue(names) {
+    for (const name of names) {
+        const value = process.env[name];
+        if (value && value.trim().length > 0)
+            return { name, value };
+    }
+    return {};
+}
+function cookieHeaderFromEnvironment(source) {
+    const parts = [];
+    const sources = [];
+    const rawCookie = envValue(authStringList(source, "cookieEnv", "sessionCookieEnv"));
+    if (rawCookie.value) {
+        parts.push(rawCookie.value);
+        if (rawCookie.name)
+            sources.push(rawCookie.name);
+    }
+    for (const [cookieName, envName] of Object.entries(authCookieMap(source))) {
+        const cookieValue = envValue([envName]);
+        if (!cookieValue.value)
+            continue;
+        parts.push(`${cookieName}=${encodeURIComponent(cookieValue.value)}`);
+        sources.push(envName);
+    }
+    return {
+        source: sources.join(", ") || undefined,
+        value: parts.join("; "),
+    };
+}
+function mergeCookieHeaders(...headers) {
+    const merged = new Map();
+    for (const header of headers) {
+        for (const part of header.split(";")) {
+            const trimmed = part.trim();
+            if (!trimmed)
+                continue;
+            const index = trimmed.indexOf("=");
+            if (index <= 0)
+                continue;
+            merged.set(trimmed.slice(0, index), trimmed.slice(index + 1));
+        }
+    }
+    return Array.from(merged, ([key, value]) => `${key}=${value}`).join("; ");
+}
+function cleanMetadata(value) {
+    const entries = Object.entries(value).filter(([, item]) => item !== undefined && item !== "");
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+function contentTypeForPath(path) {
+    const ext = extname(path).toLowerCase();
+    if (ext === ".json")
+        return "application/json";
+    if (ext === ".md" || ext === ".markdown")
+        return "text/markdown";
+    if (ext === ".yaml" || ext === ".yml")
+        return "application/yaml";
+    if (ext === ".csv")
+        return "text/csv";
+    if (ext === ".html" || ext === ".htm")
+        return "text/html";
+    return "text/plain";
+}
+function escapeTable(value) {
+    return value.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeAdapterKey(value) {
+    return value?.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") ?? "";
+}
+function renderRepositoryMetadata(entry, repository) {
+    return [
+        "---",
+        `sourceKey: ${JSON.stringify(entry.id)}`,
+        `sourcePath: ${JSON.stringify(entry.path)}`,
+        entry.provider !== entry.id ? `sourceAlias: ${JSON.stringify(entry.provider)}` : undefined,
+        `origin: ${JSON.stringify(repository)}`,
+        `extractionMethod: "repository-metadata-only"`,
+        `extractedAt: ${JSON.stringify(new Date().toISOString())}`,
+        `snapshotStatus: "metadata-only"`,
+        "---",
+        "",
+        "# Repository Source",
+        "",
+        "## Provenance",
+        "",
+        `- Source key: \`${entry.id}\``,
+        entry.provider !== entry.id ? `- Source alias: \`${entry.provider}\`` : undefined,
+        `- Repository: \`${repository}\``,
+        "- Method: repository-metadata-only",
+        "",
+        "## Acquisition Boundary",
+        "",
+        "Repository origins are not crawled or converted wholesale. Configure contract paths, refs, or a checkout policy before materializing repository content.",
+        "",
+    ].filter((line) => typeof line === "string").join("\n");
+}
+function htmlToStructuredMarkdown(value) {
+    const body = (value.match(/<body[^>]*>([\s\S]*?)<\/body>/i)?.[1] ?? value)
+        .replace(/<script[\s\S]*?<\/script>/gi, "")
+        .replace(/<style[\s\S]*?<\/style>/gi, "")
+        .replace(/<(nav|header|footer|aside)[^>]*>[\s\S]*?<\/\1>/gi, "");
+    return body
+        .replace(/<h1[^>]*>([\s\S]*?)<\/h1>/gi, "\n# $1\n")
+        .replace(/<h2[^>]*>([\s\S]*?)<\/h2>/gi, "\n## $1\n")
+        .replace(/<h3[^>]*>([\s\S]*?)<\/h3>/gi, "\n### $1\n")
+        .replace(/<h4[^>]*>([\s\S]*?)<\/h4>/gi, "\n#### $1\n")
+        .replace(/<li[^>]*>([\s\S]*?)<\/li>/gi, "\n- $1")
+        .replace(/<br\s*\/?>/gi, "\n")
+        .replace(/<\/(p|div|section|article|tr)>/gi, "\n")
+        .replace(/<a\b[^>]*href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi, "[$2]($1)")
+        .replace(/<[^>]+>/g, "")
+        .replace(/&nbsp;/g, " ")
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, "\"")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line, index, lines) => line.length > 0 || lines[index - 1]?.length)
+        .join("\n");
+}
+function fencedBody(body, contentType) {
+    const info = contentType.includes("json")
+        ? "json"
+        : contentType.includes("yaml") || contentType.includes("yml")
+            ? "yaml"
+            : "";
+    return ["```" + info, body.trimEnd(), "```"].join("\n");
+}
+function shouldPreserveMachineReadable(source, originPath, snapshotPath) {
+    const ext = extname(originPath).toLowerCase();
+    const snapshotExt = extname(snapshotPath).toLowerCase();
+    return (source.type === "api_contract" ||
+        ["backend_repo", "design_asset"].includes(source.type ?? "") ||
+        [".json", ".yaml", ".yml"].includes(ext) ||
+        [".json", ".yaml", ".yml"].includes(snapshotExt));
+}
+function chooseStrategy(method) {
+    if (method === "local")
+        return "local-copy-structured-markdown";
+    if (method === "repository")
+        return "repository-metadata-only";
+    if (method === "url")
+        return "playwright-auth-or-direct-fetch";
+    return "confirm-acquisition-method";
+}
+function renderDownstreamImpact(results) {
+    const changed = results.filter((result) => result.changed);
+    const blocked = results.filter((result) => ["blocked-auth", "source-gap", "failed"].includes(result.status));
+    return [
+        "# Downstream Impact",
+        "",
+        `Changed sources: ${changed.length}`,
+        `Blocked sources: ${blocked.length}`,
+        "",
+        changed.length === 0
+            ? "No downstream refresh is recommended from this sync run."
+            : changed.map((result) => `- \`${result.sourcePath}\`: snapshot changed; review dependent proposal/spec/design/tasks/tests before claiming freshness.`).join("\n"),
+        "",
+        blocked.length === 0
+            ? "No blocked sources."
+            : blocked.map((result) => `- \`${result.sourcePath}\` [${result.status}]: ${result.reason}`).join("\n"),
+        "",
+    ].join("\n");
+}
+async function cookieHeaderFromStorageState(storageStatePath, url) {
+    try {
+        const parsed = JSON.parse(await readFile(storageStatePath, "utf8"));
+        const host = new URL(url).hostname;
+        return (parsed.cookies ?? [])
+            .filter((cookie) => cookie.name && cookie.value && domainMatches(host, cookie.domain ?? ""))
+            .map((cookie) => `${cookie.name}=${cookie.value}`)
+            .join("; ");
+    }
+    catch {
+        return "";
+    }
+}
+function domainMatches(host, domain) {
+    const normalized = domain.replace(/^\./, "");
+    return host === normalized || host.endsWith(`.${normalized}`);
+}
+function looksLikeLoginPage(body, url) {
+    const lower = `${url}\n${body.slice(0, 5000)}`.toLowerCase();
+    return (lower.includes("login") ||
+        lower.includes("sign in") ||
+        lower.includes("signin") ||
+        lower.includes("log in") ||
+        lower.includes("password") ||
+        lower.includes("sso")) && !lower.includes("logout");
+}
+function hasMaterialContent(value) {
+    const body = value.replace(/^---[\s\S]*?---/, "").replace(/[#*\-[\]()`\s]/g, "");
+    return body.length >= 20;
+}
+function sourceGap(base, reason) {
+    return {
+        ...base,
+        strategy: "source-gap",
+        status: "source-gap",
+        changed: false,
+        reason,
+        validation: { sourceAvailable: "fail" },
+    };
+}
+function blocked(base, reason) {
+    return {
+        ...base,
+        strategy: "direct-fetch-structured-markdown",
+        status: "blocked-auth",
+        changed: false,
+        reason,
+        validation: { bodyContent: "fail", previousSnapshotPreserved: base.previousSnapshotHash ? "pass" : "skipped" },
+    };
+}
+function blockedAdapter(base, strategy, reason) {
+    return {
+        ...base,
+        strategy,
+        status: "blocked-auth",
+        changed: false,
+        reason,
+        validation: { bodyContent: "fail", previousSnapshotPreserved: base.previousSnapshotHash ? "pass" : "skipped" },
+    };
+}
+function failed(base, reason) {
+    return {
+        ...base,
+        strategy: "playwright-headless-browser",
+        status: "failed",
+        changed: false,
+        reason,
+        validation: { browserRendered: "fail", previousSnapshotPreserved: base.previousSnapshotHash ? "pass" : "skipped" },
+    };
+}
+async function loadProjectPlaywright(target) {
+    const requireFromTarget = createRequire(resolve(target, "package.json"));
+    let resolved;
+    try {
+        resolved = requireFromTarget.resolve("playwright");
+    }
+    catch {
+        throw new Error("Playwright browser acquisition requires the target project to install the `playwright` package");
+    }
+    return await import(resolved);
+}
+async function hashIfExists(path) {
+    try {
+        return await sha256(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function sha256(path) {
+    const content = await readFile(path);
+    return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function safeReadDir(path) {
+    try {
+        return await import("node:fs/promises").then((fs) => fs.readdir(path, { withFileTypes: true }));
+    }
+    catch {
+        return [];
+    }
+}
+function safeFileName(value) {
+    return value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "source";
+}
+function isMigrationLaneCandidate(value, staleNames) {
+    return (staleNames.has(value) ||
+        /^v?\d+(?:[._-]\d+)*$/i.test(value) ||
+        /^(sprint|iteration|release)[-_]?\d*/i.test(value));
+}
+function resolveAuthStatePath(target, config, authState) {
+    const statePath = resolve(target, authState);
+    const sharedAuthRoot = resolve(target, getWorkspacePath(config, "playwrightRoot"), ".auth");
+    const modulesRoot = resolve(target, getWorkspacePath(config, "modulesRoot"));
+    const pathParts = statePath.split(/[\\/]/);
+    const modulePrivate = isInside(modulesRoot, statePath) && pathParts.includes("_playwright") && pathParts.includes(".auth");
+    if (isInside(sharedAuthRoot, statePath) || modulePrivate)
+        return statePath;
+    throw new Error(`Playwright storageState input must stay under ${sharedAuthRoot} or a module _playwright/.auth directory`);
+}
+function resolveSelectedAuthStatePath(target, config, opts) {
+    if (opts.authState)
+        return resolveAuthStatePath(target, config, opts.authState);
+    if (opts.authProfile)
+        return resolveAuthProfilePath(target, config, opts.authProfile);
+    return undefined;
+}
+function resolveAuthProfilePath(target, config, profile) {
+    const authRoot = resolve(target, getWorkspacePath(config, "playwrightRoot"), ".auth");
+    const fileName = profile ? `${safeFileName(profile)}.json` : "user_data.json";
+    return join(authRoot, fileName);
+}
+function resolveAdapterLocalFilePath(target, value) {
+    const path = resolve(target, value);
+    return isInside(resolve(target), path) ? path : undefined;
+}
+function isInside(root, target) {
+    const rel = relative(root, target);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+export function createSyncRunId(now = new Date()) {
+    return now.toISOString().replace(/[:.]/g, "-");
+}
+//# sourceMappingURL=prepare-sync.js.map