@popoverai/dotrequirements 0.27.4 → 0.28.0

package/dist/sync/compare.js

@@ -0,0 +1,285 @@
+/**
+ * The repo/cloud comparator (DIFF-*). A pure function of two snapshots: it
+ * reads no disk and makes no network calls. `dotreq diff` renders its result,
+ * `dotreq sync` acts on it, CI asserts on it.
+ */
+import { normalizeProse, requirementUnitMap, segmentBody, } from "./segment.js";
+/** Whitespace-only normalization for the fast-path body equality check. */
+function normalizeBody(body) {
+    return normalizeProse(body);
+}
+/** Do the single-valued document attributes diverge? A changed title or prefix
+ * is never an "addition" (both sides always have one), so it forces a conflict.
+ * A prefix present on one side only is treated as no divergence — omission is
+ * filled by inference (DOC-HEADER-11), not a genuine disagreement. */
+function attributesDiverge(local, cloud) {
+    if ((local.title ?? "") !== cloud.title)
+        return true;
+    if (local.defaultPrefix &&
+        cloud.defaultPrefix &&
+        local.defaultPrefix !== cloud.defaultPrefix) {
+        return true;
+    }
+    return false;
+}
+/** Compare two requirement blocks by their position-path unit maps. */
+function compareRequirementBlocks(repoBlock, cloudBlock) {
+    let repoMap;
+    let cloudMap;
+    try {
+        repoMap = requirementUnitMap(repoBlock);
+        cloudMap = requirementUnitMap(cloudBlock);
+    }
+    catch {
+        // A block that won't parse here can't be classified — treat as diverged so
+        // it flags rather than silently syncing. (Both sides are pre-validated in
+        // practice, so this is a guard, not a live path.)
+        return {
+            result: "diverged",
+            repoOnlyPositions: [],
+            cloudOnlyPositions: [],
+        };
+    }
+    const cloudSubsetOfRepo = [...cloudMap].every(([id, v]) => repoMap.get(id) === v);
+    const repoSubsetOfCloud = [...repoMap].every(([id, v]) => cloudMap.get(id) === v);
+    const toPosition = (id) => id.replace(/^[^.]*/, "").replace(/^\./, "") || "(root)";
+    const repoOnlyPositions = [...repoMap.keys()]
+        .filter((id) => repoMap.get(id) !== cloudMap.get(id))
+        .map(toPosition);
+    const cloudOnlyPositions = [...cloudMap.keys()]
+        .filter((id) => cloudMap.get(id) !== repoMap.get(id))
+        .map(toPosition);
+    let result;
+    if (cloudSubsetOfRepo && repoSubsetOfCloud)
+        result = "equal";
+    else if (cloudSubsetOfRepo)
+        result = "repo_extends";
+    else if (repoSubsetOfCloud)
+        result = "cloud_extends";
+    else
+        result = "diverged";
+    return { result, repoOnlyPositions, cloudOnlyPositions };
+}
+/** Classify a paired document's bodies structurally (DIFF-4). */
+function classifyBodies(repoBody, cloudBody) {
+    const repoUnits = segmentBody(repoBody);
+    const cloudUnits = segmentBody(cloudBody);
+    const details = [];
+    // Requirements match by key; index each side.
+    const repoReqs = new Map();
+    const cloudReqs = new Map();
+    for (const u of repoUnits)
+        if (u.kind === "requirement")
+            repoReqs.set(u.key, u.blockContent);
+    for (const u of cloudUnits)
+        if (u.kind === "requirement")
+            cloudReqs.set(u.key, u.blockContent);
+    let anyRepoExtra = false; // repo has something cloud lacks
+    let anyCloudExtra = false; // cloud has something repo lacks
+    // Matched requirement pairs.
+    for (const [key, repoBlock] of repoReqs) {
+        const cloudBlock = cloudReqs.get(key);
+        if (cloudBlock === undefined) {
+            anyRepoExtra = true;
+            details.push({ unit: key, verdict: "additions_in_repo" });
+            continue;
+        }
+        const { result, repoOnlyPositions, cloudOnlyPositions } = compareRequirementBlocks(repoBlock, cloudBlock);
+        if (result === "repo_extends") {
+            anyRepoExtra = true;
+            details.push({
+                unit: key,
+                verdict: "additions_in_repo",
+                positions: repoOnlyPositions,
+            });
+        }
+        else if (result === "cloud_extends") {
+            anyCloudExtra = true;
+            details.push({
+                unit: key,
+                verdict: "additions_in_cloud",
+                positions: cloudOnlyPositions,
+            });
+        }
+        else if (result === "diverged") {
+            anyRepoExtra = true;
+            anyCloudExtra = true;
+            details.push({
+                unit: key,
+                verdict: "conflict",
+                positions: [...new Set([...repoOnlyPositions, ...cloudOnlyPositions])],
+            });
+        }
+    }
+    // Cloud-only requirement keys.
+    for (const key of cloudReqs.keys()) {
+        if (!repoReqs.has(key)) {
+            anyCloudExtra = true;
+            details.push({ unit: key, verdict: "additions_in_cloud" });
+        }
+    }
+    // Prose: match by exact normalized text (multiset). Unmatched prose on either
+    // side is extra material — a reworded passage is unmatched on both.
+    const cloudProse = cloudUnits.filter((u) => u.kind === "prose");
+    const cloudProseUsed = new Array(cloudProse.length).fill(false);
+    for (const u of repoUnits) {
+        if (u.kind !== "prose")
+            continue;
+        const idx = cloudProse.findIndex((c, i) => !cloudProseUsed[i] && c.text === u.text);
+        if (idx === -1) {
+            anyRepoExtra = true;
+            details.push({
+                unit: proseLabel(u.text),
+                verdict: "additions_in_repo",
+                note: "prose",
+            });
+        }
+        else {
+            cloudProseUsed[idx] = true;
+        }
+    }
+    cloudProse.forEach((c, i) => {
+        if (!cloudProseUsed[i]) {
+            anyCloudExtra = true;
+            details.push({
+                unit: proseLabel(c.text),
+                verdict: "additions_in_cloud",
+                note: "prose",
+            });
+        }
+    });
+    // Order of the units common to both sides must agree; a reorder is a conflict.
+    const orderPreserved = matchedOrderAgrees(repoUnits, cloudUnits);
+    if (!orderPreserved) {
+        anyRepoExtra = true;
+        anyCloudExtra = true;
+    }
+    let verdict;
+    if (!anyRepoExtra && !anyCloudExtra)
+        verdict = "in_sync";
+    else if (anyRepoExtra && !anyCloudExtra)
+        verdict = "additions_in_repo";
+    else if (anyCloudExtra && !anyRepoExtra)
+        verdict = "additions_in_cloud";
+    else
+        verdict = "conflict";
+    return { verdict, details };
+}
+/** The subsequence of unit identities present on both sides must appear in the
+ * same relative order. Identity: requirement key, or prose text. */
+function matchedOrderAgrees(repoUnits, cloudUnits) {
+    const identity = (u) => u.kind === "requirement" ? `R:${u.key}` : `P:${u.text}`;
+    const repoIds = repoUnits.map(identity);
+    const cloudIds = cloudUnits.map(identity);
+    const cloudIdSet = new Set(cloudIds);
+    const common = new Set(repoIds.filter((id) => cloudIdSet.has(id)));
+    const repoSeq = repoIds.filter((id) => common.has(id));
+    const cloudSeq = cloudIds.filter((id) => common.has(id));
+    return (repoSeq.length === cloudSeq.length &&
+        repoSeq.every((id, i) => id === cloudSeq[i]));
+}
+function proseLabel(text) {
+    const firstLine = text.split("\n")[0].trim();
+    return firstLine.length > 40
+        ? `${firstLine.slice(0, 40)}…`
+        : firstLine || "(prose)";
+}
+/** Compare one document across surfaces. */
+function compareDocument(local, cloud) {
+    const base = {
+        filePath: local.filePath,
+        documentId: cloud.documentId,
+        title: cloud.title,
+        verdict: "in_sync",
+    };
+    const diverges = attributesDiverge(local, cloud);
+    const body = local.body ?? "";
+    // Fast path: whitespace-identical bodies with matching attributes.
+    if (!diverges && normalizeBody(body) === normalizeBody(cloud.body)) {
+        return { ...base, verdict: "in_sync" };
+    }
+    const { verdict: bodyVerdict, details } = classifyBodies(body, cloud.body);
+    let verdict;
+    if (diverges) {
+        // A changed single-valued attribute is never additive → conflict.
+        verdict = "conflict";
+    }
+    else {
+        verdict = bodyVerdict;
+    }
+    return {
+        ...base,
+        verdict,
+        details: verdict === "in_sync" ? undefined : details,
+    };
+}
+/**
+ * Two local files carrying the same document id would both pair to one cloud
+ * document and both try to write it — last writer wins, silently destroying the
+ * first (SYNC-FAIL-3). Return the offending ids with their file paths so the
+ * caller can abort before any write.
+ */
+export function duplicateLocalDocumentIds(local) {
+    const byId = new Map();
+    for (const doc of local.documents) {
+        if (!doc.documentId)
+            continue;
+        const paths = byId.get(doc.documentId) ?? [];
+        paths.push(doc.filePath);
+        byId.set(doc.documentId, paths);
+    }
+    return [...byId.entries()]
+        .filter(([, paths]) => paths.length > 1)
+        .map(([documentId, filePaths]) => ({ documentId, filePaths }));
+}
+/**
+ * Compare the whole repo against the whole cloud, pairing documents by id.
+ */
+export function compareSnapshots(local, cloud) {
+    const cloudById = new Map(cloud.documents.map((d) => [d.documentId, d]));
+    const matchedCloudIds = new Set();
+    const documents = [];
+    for (const doc of local.documents) {
+        if (doc.parseError) {
+            // An invalid file that still names its document id claims the cloud
+            // counterpart: without this, the cloud doc would re-emit as
+            // "only_in_cloud" and a sync would write a duplicate local file beside
+            // the broken one (then hard-abort every later run on the duplicate id).
+            if (doc.documentId)
+                matchedCloudIds.add(doc.documentId);
+            documents.push({
+                filePath: doc.filePath,
+                documentId: doc.documentId,
+                title: doc.title ?? doc.filePath,
+                verdict: "invalid_file",
+                error: doc.parseError,
+            });
+            continue;
+        }
+        const cloudDoc = doc.documentId ? cloudById.get(doc.documentId) : undefined;
+        if (!cloudDoc) {
+            // No id, or an id the cloud doesn't have (deleted in cloud, or a stale
+            // link) — the document lives only in the repo (SYNC-WEB-DELETE-1.0).
+            documents.push({
+                filePath: doc.filePath,
+                documentId: doc.documentId,
+                title: doc.title ?? doc.filePath,
+                verdict: "only_in_repo",
+            });
+            continue;
+        }
+        matchedCloudIds.add(cloudDoc.documentId);
+        documents.push(compareDocument(doc, cloudDoc));
+    }
+    for (const cloudDoc of cloud.documents) {
+        if (!matchedCloudIds.has(cloudDoc.documentId)) {
+            documents.push({
+                documentId: cloudDoc.documentId,
+                title: cloudDoc.title,
+                verdict: "only_in_cloud",
+            });
+        }
+    }
+    return { documents };
+}
+//# sourceMappingURL=compare.js.map

package/dist/sync/execute.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Executing a sync plan: cloud writes/deletes and local writes/deletes.
+ *
+ * Cloud writes reuse the push machinery (parse → saveWithRequirements →
+ * frontmatter write-back) so document-header/import-provenance fidelity is
+ * identical to a repo→cloud push. Local writes reuse local-files.ts.
+ */
+import type { PlannedAction } from "./plan.js";
+import type { CloudAuth } from "./snapshot.js";
+import type { CloudSnapshot, DocumentComparison } from "./types.js";
+export interface SyncOutcome {
+    cloudCreated: number;
+    cloudUpdated: number;
+    cloudDeleted: number;
+    localWritten: number;
+    localDeleted: number;
+    conflicts: DocumentComparison[];
+    invalid: DocumentComparison[];
+    errors: Array<{
+        name: string;
+        error: string;
+    }>;
+    /** Synced-to-cloud documents with their web URLs (SYNC-LAND-1). */
+    synced: Array<{
+        name: string;
+        url: string;
+    }>;
+    /** SYNC-FAIL-2: cloud save succeeded but the local write-back failed. The
+     * document is synced; the warning carries the re-link recovery step. */
+    writeBackWarnings: Array<{
+        name: string;
+        filePath: string;
+        documentId: string;
+        error: string;
+    }>;
+    /** IMPORT-3: run-marker failures — loud, never fatal, never silent. */
+    importWarnings: Array<{
+        name: string;
+        status: string;
+    }>;
+}
+/**
+ * Execute a plan. `cloud` provides bodies for local writes (keyed by id). Cloud
+ * writes require a project slug in `auth`; a read-only share run has none and
+ * its plan carries no cloud-writing actions.
+ */
+export declare function executePlan(plan: PlannedAction[], cloud: CloudSnapshot, auth: CloudAuth, workspaceRoot: string): Promise<SyncOutcome>;
+//# sourceMappingURL=execute.d.ts.map

package/dist/sync/execute.js

@@ -0,0 +1,186 @@
+/**
+ * Executing a sync plan: cloud writes/deletes and local writes/deletes.
+ *
+ * Cloud writes reuse the push machinery (parse → saveWithRequirements →
+ * frontmatter write-back) so document-header/import-provenance fidelity is
+ * identical to a repo→cloud push. Local writes reuse local-files.ts.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ConvexHttpClient } from "convex/browser";
+import { getConvexUrl } from "../config.js";
+import { api } from "../convex.js";
+import { mergeMetadataWithRawFrontmatter, parseFilesForPushIndividually, WEB_APP_URL, } from "../push/core.js";
+import { buildRequirementsFile } from "../schema/index.js";
+import { resolveLocalPath, writeLocalDocument } from "./local-files.js";
+function emptyOutcome() {
+    return {
+        cloudCreated: 0,
+        cloudUpdated: 0,
+        cloudDeleted: 0,
+        localWritten: 0,
+        localDeleted: 0,
+        conflicts: [],
+        invalid: [],
+        errors: [],
+        synced: [],
+        writeBackWarnings: [],
+        importWarnings: [],
+    };
+}
+/**
+ * Execute a plan. `cloud` provides bodies for local writes (keyed by id). Cloud
+ * writes require a project slug in `auth`; a read-only share run has none and
+ * its plan carries no cloud-writing actions.
+ */
+export async function executePlan(plan, cloud, auth, workspaceRoot) {
+    const outcome = emptyOutcome();
+    const client = new ConvexHttpClient(getConvexUrl());
+    const cloudById = new Map(cloud.documents.map((d) => [d.documentId, d]));
+    const requirementsDir = path.join(workspaceRoot, ".requirements");
+    const usedPaths = new Set();
+    for (const { doc, action } of plan) {
+        const name = doc.filePath ? path.basename(doc.filePath) : doc.title;
+        try {
+            switch (action) {
+                case "skip":
+                    break;
+                case "skip_conflict":
+                    outcome.conflicts.push(doc);
+                    break;
+                case "invalid":
+                    outcome.invalid.push(doc);
+                    break;
+                case "cloud_write":
+                    await cloudWrite(client, auth, doc, outcome);
+                    break;
+                case "cloud_delete":
+                    await cloudDelete(client, auth, doc, outcome);
+                    break;
+                case "local_write":
+                    localWrite(doc, cloudById, usedPaths, requirementsDir, outcome);
+                    break;
+                case "local_delete":
+                    localDelete(doc, outcome);
+                    break;
+            }
+        }
+        catch (err) {
+            outcome.errors.push({ name, error: errorDisplayMessage(err) });
+        }
+    }
+    return outcome;
+}
+/**
+ * Servers throw ConvexError({kind, message}) for expected failures; production
+ * redacts the Error message to "Server Error" but preserves error.data.
+ * Surface the human-readable message rather than the blob.
+ */
+function errorDisplayMessage(err) {
+    const data = err.data;
+    if (data && typeof data.message === "string")
+        return data.message;
+    return err instanceof Error ? err.message : String(err);
+}
+async function cloudWrite(client, auth, doc, outcome) {
+    if (!auth.projectSlug || !doc.filePath) {
+        throw new Error("Cannot write to the cloud without project credentials.");
+    }
+    const { parsedFiles } = parseFilesForPushIndividually([doc.filePath]);
+    const parsed = parsedFiles[0];
+    if (!parsed)
+        throw new Error(`Could not parse ${path.basename(doc.filePath)}`);
+    const meta = parsed.metadata.document;
+    const saveResult = (await client.mutation(api.documents.saveWithRequirements.saveWithRequirements, {
+        projectAuth: {
+            projectSlug: auth.projectSlug,
+            projectSecret: auth.projectSecret,
+        },
+        target: { type: "project", slug: auth.projectSlug },
+        documentId: meta?.id,
+        title: meta?.title ?? path.basename(doc.filePath),
+        markdownContent: parsed.markdownContent,
+        defaultPrefix: meta?.defaultPrefix,
+        runMarker: parsed.metadata.ctsRun,
+        dryRun: false,
+    }));
+    const documentId = typeof saveResult === "string" ? saveResult : saveResult.documentId;
+    // IMPORT-3.3: marker failure is never silent — surface the statuses the
+    // server reports as warnings.
+    if (typeof saveResult !== "string" && saveResult.importStatus) {
+        const status = saveResult.importStatus;
+        if (status === "invalid_marker" ||
+            status === "unsupported_version" ||
+            status === "already_used") {
+            outcome.importWarnings.push({
+                name: path.basename(doc.filePath),
+                status,
+            });
+        }
+    }
+    // Created vs updated is decided by the cloud, not the frontmatter: a stale
+    // id (document deleted in cloud) makes the save mint a fresh document.
+    const wasCreate = documentId !== meta?.id;
+    if (wasCreate)
+        outcome.cloudCreated++;
+    else
+        outcome.cloudUpdated++;
+    outcome.synced.push({
+        name: path.basename(doc.filePath),
+        url: `${WEB_APP_URL}/documents/${documentId}`,
+    });
+    // SYNC-FAIL-2: the cloud document already exists at this point. A write-back
+    // failure is a warning on a synced document, never a sync failure (which
+    // would invite a retry that mints a duplicate).
+    try {
+        if (parsed.metadata.document)
+            parsed.metadata.document.id = documentId;
+        parsed.metadata.pulledAt = new Date().toISOString();
+        parsed.metadata.version = (parsed.metadata.version ?? 0) + 1;
+        const content = buildRequirementsFile(mergeMetadataWithRawFrontmatter(parsed.metadata, parsed.rawFrontmatter), parsed.markdownContent);
+        fs.writeFileSync(doc.filePath, content, "utf-8");
+    }
+    catch (writeErr) {
+        outcome.writeBackWarnings.push({
+            name: path.basename(doc.filePath),
+            filePath: doc.filePath,
+            documentId,
+            error: writeErr instanceof Error ? writeErr.message : String(writeErr),
+        });
+    }
+}
+async function cloudDelete(client, auth, doc, outcome) {
+    if (!auth.projectSlug || !doc.documentId) {
+        throw new Error("Cannot delete from the cloud without project credentials.");
+    }
+    await client.mutation(api.documents.mutations.deleteForCli, {
+        projectAuth: {
+            projectSlug: auth.projectSlug,
+            projectSecret: auth.projectSecret,
+        },
+        target: { type: "project", slug: auth.projectSlug },
+        documentId: doc.documentId,
+    });
+    outcome.cloudDeleted++;
+}
+function localWrite(doc, cloudById, usedPaths, requirementsDir, outcome) {
+    const cloudDoc = doc.documentId ? cloudById.get(doc.documentId) : undefined;
+    if (!cloudDoc)
+        throw new Error(`No cloud content for ${doc.title}`);
+    if (!fs.existsSync(requirementsDir))
+        fs.mkdirSync(requirementsDir, { recursive: true });
+    const filePath = resolveLocalPath(cloudDoc, doc.filePath, usedPaths, requirementsDir);
+    usedPaths.add(filePath);
+    const changed = writeLocalDocument(filePath, cloudDoc);
+    if (changed)
+        outcome.localWritten++;
+}
+function localDelete(doc, outcome) {
+    if (!doc.filePath)
+        return;
+    if (fs.existsSync(doc.filePath)) {
+        fs.unlinkSync(doc.filePath);
+        outcome.localDeleted++;
+    }
+}
+//# sourceMappingURL=execute.js.map

package/dist/sync/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The sync module: one comparator (compare.ts) over two snapshots
+ * (snapshot.ts), consumed by `dotreq diff` and `dotreq sync`.
+ */
+import type { ComparisonResult, DocumentComparison } from "./types.js";
+export { compareSnapshots, duplicateLocalDocumentIds } from "./compare.js";
+export { displayName, formatUnitDetail, formatVerdictLine, resolutionHint, scopeToken, } from "./render.js";
+export { segmentBody } from "./segment.js";
+export { acquireCloudSnapshot, acquireLocalSnapshot, type CloudAuth, readLocalDocument, } from "./snapshot.js";
+export type { CloudDocument, CloudSnapshot, ComparisonResult, DocumentComparison, LocalDocument, LocalSnapshot, UnitDetail, Verdict, } from "./types.js";
+export { verdictLabel } from "./types.js";
+/**
+ * Restrict a comparison to the documents named by scope tokens. Returns the
+ * matched documents plus any tokens that matched nothing, so the caller can
+ * report an unrecognized scope rather than silently comparing zero documents.
+ */
+export declare function filterByScope(result: ComparisonResult, scope: string[], workspaceRoot: string): {
+    documents: DocumentComparison[];
+    unmatched: string[];
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/sync/index.js

@@ -0,0 +1,52 @@
+/**
+ * The sync module: one comparator (compare.ts) over two snapshots
+ * (snapshot.ts), consumed by `dotreq diff` and `dotreq sync`.
+ */
+import * as path from "node:path";
+export { compareSnapshots, duplicateLocalDocumentIds } from "./compare.js";
+export { displayName, formatUnitDetail, formatVerdictLine, resolutionHint, scopeToken, } from "./render.js";
+export { segmentBody } from "./segment.js";
+export { acquireCloudSnapshot, acquireLocalSnapshot, readLocalDocument, } from "./snapshot.js";
+export { verdictLabel } from "./types.js";
+/**
+ * Does a document match one scope token? A token may name a local file (path or
+ * basename), a cloud document id, or a title — scope resolves against the union
+ * of both surfaces (SYNC-SCOPE-1), since a cloud-only document has no path.
+ */
+function documentMatchesToken(doc, token, workspaceRoot) {
+    if (doc.documentId && doc.documentId === token)
+        return true;
+    if (doc.title.toLowerCase() === token.toLowerCase())
+        return true;
+    if (doc.filePath) {
+        if (doc.filePath === token)
+            return true;
+        if (path.resolve(workspaceRoot, token) === doc.filePath)
+            return true;
+        if (path.basename(doc.filePath) === token)
+            return true;
+        if (path.resolve(token) === doc.filePath)
+            return true;
+    }
+    return false;
+}
+/**
+ * Restrict a comparison to the documents named by scope tokens. Returns the
+ * matched documents plus any tokens that matched nothing, so the caller can
+ * report an unrecognized scope rather than silently comparing zero documents.
+ */
+export function filterByScope(result, scope, workspaceRoot) {
+    if (scope.length === 0)
+        return { documents: result.documents, unmatched: [] };
+    const matched = new Set();
+    const unmatched = [];
+    for (const token of scope) {
+        const hits = result.documents.filter((d) => documentMatchesToken(d, token, workspaceRoot));
+        if (hits.length === 0)
+            unmatched.push(token);
+        for (const hit of hits)
+            matched.add(hit);
+    }
+    return { documents: [...matched], unmatched };
+}
+//# sourceMappingURL=index.js.map

package/dist/sync/local-files.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Writing cloud content into local `.requirements/` files — the local half of
+ * sync. Shared filename/collision logic (SYNC-WEB-CREATE-2) and the frontmatter
+ * build (SYNC-WRITE-1) live here so pull and sync agree.
+ */
+import type { CloudDocument } from "./types.js";
+/** Sanitize a document title into a filename stem. */
+export declare function sanitizeFileName(title: string): string;
+/**
+ * Choose the path a cloud document is written to. An existing file linked by
+ * document ID keeps its path (SYNC-DISCOVERY-2.0); a new document lands in
+ * `.requirements/`, disambiguated by numeric suffix on collision and falling
+ * back to the document ID when the title sanitizes to nothing
+ * (SYNC-WEB-CREATE-2).
+ */
+export declare function resolveLocalPath(cloud: CloudDocument, existingPath: string | undefined, usedPaths: Set<string>, requirementsDir: string): string;
+/** Read the ctsRun marker from an existing file's frontmatter, if any (IMPORT-1). */
+export declare function readCtsRun(filePath: string): string | undefined;
+/**
+ * Write a cloud document to a local file. `pulledAt` records when this content
+ * arrived (SYNC-WRITE-1.1); an existing ctsRun marker is carried forward
+ * (IMPORT-1). Returns true when the file's bytes actually changed — sync only
+ * touches files whose content changed (SYNC-WRITE-1.0).
+ */
+export declare function writeLocalDocument(filePath: string, cloud: CloudDocument): boolean;
+//# sourceMappingURL=local-files.d.ts.map