@popoverai/dotrequirements 0.27.4 → 0.29.0

package/dist/sync/execute.js

@@ -0,0 +1,225 @@
+/**
+ * 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, composeMarkdownWithTitle, splitLeadingH1, } 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: [],
+        renames: [],
+    };
+}
+/**
+ * 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, cloudById, 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, cloudById, 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;
+    // SYNC-TITLE-1.1: a legacy file whose title lives only in frontmatter (no body
+    // H1) must reach the cloud self-describing. Materialize the title as the body's
+    // leading H1 BEFORE the push — so the cloud row carries the H1 on first write
+    // and never lands as an H1-less-but-titled row. Such a row would otherwise be
+    // reachable to a web/MCP edit that untitles it (and is out of reach of the
+    // one-time title backfill, since a legacy checkout mints it on any later sync).
+    // Only the unambiguous case fires: a known frontmatter title with no existing
+    // H1 — never a guess about a content H1.
+    if (meta?.title && splitLeadingH1(parsed.markdownContent).title === null) {
+        parsed.markdownContent = composeMarkdownWithTitle(meta.title, parsed.markdownContent);
+    }
+    // SYNC-TITLE-1: the server derives the title from the body's leading H1.
+    // A legacy frontmatter title rides along only as the server's fallback for
+    // H1-less bodies (SYNC-TITLE-1.1); the filename is never a title
+    // (SYNC-TITLE-1.0).
+    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,
+        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++;
+    // SYNC-TITLE-1.3: a push that changes the title is a rename — announce it,
+    // so an unintended H1 edit is visible and costs one heading edit to undo.
+    // The new title is derived from the pushed markdown exactly as the server
+    // derives it (H1, else the legacy frontmatter title, else untitled) — NOT
+    // from doc.title, which the comparator pins to the OLD cloud title for any
+    // id-matched document, so comparing against it never detects a rename.
+    const cloudBefore = meta?.id ? cloudById.get(meta.id) : undefined;
+    if (cloudBefore) {
+        const newTitle = splitLeadingH1(parsed.markdownContent).title ?? meta?.title ?? "";
+        // NAV-TITLE-1.2: the cloud snapshot reports an untitled document's title as
+        // the display fallback "Untitled Document", while newTitle is "" for that
+        // same state. Normalize before comparing so a content-only push of an
+        // untitled doc doesn't report a phantom `"Untitled Document" → ""` rename.
+        const before = cloudBefore.title === "Untitled Document" ? "" : cloudBefore.title;
+        if (before !== newTitle) {
+            outcome.renames.push({ from: before, to: newTitle });
+        }
+    }
+    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;
+            // SYNC-TITLE-1.2: drop the legacy frontmatter title — the body already
+            // carries the name as its leading H1 (materialized above, before the
+            // push), so the rewritten file loses the field without losing the title.
+            delete parsed.metadata.document.title;
+        }
+        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

package/dist/sync/local-files.js

@@ -0,0 +1,93 @@
+/**
+ * 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 * as fs from "node:fs";
+import * as path from "node:path";
+import { buildRequirementsFile } from "../schema/index.js";
+import { extractFrontmatterBlock } from "../schema/parser-core.js";
+/** Sanitize a document title into a filename stem. */
+export function sanitizeFileName(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * 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 function resolveLocalPath(cloud, existingPath, usedPaths, requirementsDir) {
+    if (existingPath)
+        return existingPath;
+    const baseName = sanitizeFileName(cloud.title) || cloud.documentId;
+    let candidate = path.join(requirementsDir, `${baseName}.requirements.md`);
+    let suffix = 2;
+    while (usedPaths.has(candidate) || fs.existsSync(candidate)) {
+        candidate = path.join(requirementsDir, `${baseName}-${suffix}.requirements.md`);
+        suffix++;
+    }
+    return candidate;
+}
+/** Read the ctsRun marker from an existing file's frontmatter, if any (IMPORT-1). */
+export function readCtsRun(filePath) {
+    if (!fs.existsSync(filePath))
+        return undefined;
+    // Search only the frontmatter block — a body line starting "ctsRun:" must
+    // not be mistaken for the marker.
+    const yaml = extractFrontmatterBlock(fs.readFileSync(filePath, "utf-8"));
+    const match = yaml?.match(/^ctsRun: (.+)$/m);
+    return match?.[1].trim();
+}
+/**
+ * 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 function writeLocalDocument(filePath, cloud) {
+    const existingCtsRun = readCtsRun(filePath);
+    // SYNC-TITLE-1.2: no `document.title` in frontmatter — the title lives in
+    // the body as its leading H1. A legacy file that gets rewritten loses the
+    // field here, since the metadata is rebuilt from scratch.
+    const metadata = {
+        pulledAt: new Date().toISOString(),
+        version: cloud.version,
+        ...(existingCtsRun ? { ctsRun: existingCtsRun } : {}),
+        document: {
+            id: cloud.documentId,
+            defaultPrefix: cloud.defaultPrefix,
+        },
+    };
+    const content = buildRequirementsFile(metadata, cloud.body);
+    // SYNC-WRITE-1.0: skip the write when the body+identity are unchanged, so a
+    // no-op sync leaves the working tree clean. Compare ignoring the volatile
+    // pulledAt line, which would otherwise force a rewrite every run.
+    if (fs.existsSync(filePath)) {
+        const current = fs.readFileSync(filePath, "utf-8");
+        if (withoutPulledAt(current) === withoutPulledAt(content))
+            return false;
+    }
+    fs.writeFileSync(filePath, content, "utf-8");
+    return true;
+}
+/**
+ * Normalize the volatile pulledAt line for equality comparison — within the
+ * frontmatter only, so a body line that happens to start "pulledAt:" can never
+ * mask a genuine content change (which would silently skip the write).
+ */
+function withoutPulledAt(fileContent) {
+    // CRLF-normalize first: extractFrontmatterBlock returns LF-normalized yaml,
+    // so the replace below must operate on LF content to find it.
+    const normalized = fileContent.replace(/\r\n/g, "\n");
+    const yaml = extractFrontmatterBlock(normalized);
+    if (yaml === undefined)
+        return normalized;
+    const normalizedYaml = yaml.replace(/^pulledAt: .*$/m, "pulledAt: <normalized>");
+    return normalized.replace(yaml, normalizedYaml);
+}
+//# sourceMappingURL=local-files.js.map

package/dist/sync/plan.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Turning verdicts into actions under a sync mode (SYNC-MODE-1..4).
+ *
+ * The mode is direction × authority; the action table below is the whole
+ * policy layer over the comparator. Pure and table-driven so it is exhaustively
+ * testable.
+ */
+import type { DocumentComparison, Verdict } from "./types.js";
+export type SyncMode = "bare" | "cloud_contributes" | "repo_contributes" | "repo_wins" | "cloud_wins";
+export interface ModeFlags {
+    cloudContributes?: boolean;
+    repoContributes?: boolean;
+    cloudWins?: boolean;
+    repoWins?: boolean;
+}
+/**
+ * Resolve raw flags into a mode, rejecting incoherent combinations
+ * (SYNC-MODE-3.2). Passing both contribute flags is the bare default spelled
+ * out (SYNC-MODE-2.3).
+ */
+export declare function resolveMode(flags: ModeFlags): SyncMode;
+/**
+ * What a sync does to one document.
+ * - cloud_write: save the repo's content to the cloud (create or overwrite)
+ * - local_write: write the cloud's content to the local file (create or overwrite)
+ * - cloud_delete / local_delete: remove the document on that side (wins modes only)
+ * - skip_conflict: a conflict left untouched, reported with its resolution
+ * - invalid: an unparseable local file, reported and skipped
+ * - skip: nothing to do
+ */
+export type SyncAction = "cloud_write" | "local_write" | "cloud_delete" | "local_delete" | "skip_conflict" | "invalid" | "skip";
+export declare function planAction(verdict: Verdict, mode: SyncMode): SyncAction;
+export interface PlannedAction {
+    doc: DocumentComparison;
+    action: SyncAction;
+}
+/** Assign an action to every document under the given mode. */
+export declare function buildPlan(documents: DocumentComparison[], mode: SyncMode): PlannedAction[];
+//# sourceMappingURL=plan.d.ts.map

package/dist/sync/plan.js

@@ -0,0 +1,90 @@
+/**
+ * Turning verdicts into actions under a sync mode (SYNC-MODE-1..4).
+ *
+ * The mode is direction × authority; the action table below is the whole
+ * policy layer over the comparator. Pure and table-driven so it is exhaustively
+ * testable.
+ */
+/**
+ * Resolve raw flags into a mode, rejecting incoherent combinations
+ * (SYNC-MODE-3.2). Passing both contribute flags is the bare default spelled
+ * out (SYNC-MODE-2.3).
+ */
+export function resolveMode(flags) {
+    const wins = [flags.repoWins, flags.cloudWins].filter(Boolean).length;
+    const contributes = [flags.cloudContributes, flags.repoContributes].filter(Boolean).length;
+    if (wins > 1 || (wins > 0 && contributes > 0)) {
+        throw new Error("Authority must be a single side: combine at most one of --repo-wins or --cloud-wins, and not with a --contributes flag.");
+    }
+    if (flags.repoWins)
+        return "repo_wins";
+    if (flags.cloudWins)
+        return "cloud_wins";
+    if (flags.cloudContributes && !flags.repoContributes)
+        return "cloud_contributes";
+    if (flags.repoContributes && !flags.cloudContributes)
+        return "repo_contributes";
+    return "bare";
+}
+const TABLE = {
+    only_in_repo: {
+        bare: "cloud_write",
+        cloud_contributes: "skip",
+        repo_contributes: "cloud_write",
+        repo_wins: "cloud_write",
+        cloud_wins: "local_delete",
+    },
+    only_in_cloud: {
+        bare: "local_write",
+        cloud_contributes: "local_write",
+        repo_contributes: "skip",
+        repo_wins: "cloud_delete",
+        cloud_wins: "local_write",
+    },
+    additions_in_repo: {
+        bare: "cloud_write",
+        cloud_contributes: "skip",
+        repo_contributes: "cloud_write",
+        repo_wins: "cloud_write",
+        cloud_wins: "local_write",
+    },
+    additions_in_cloud: {
+        bare: "local_write",
+        cloud_contributes: "local_write",
+        repo_contributes: "skip",
+        repo_wins: "cloud_write",
+        cloud_wins: "local_write",
+    },
+    conflict: {
+        bare: "skip_conflict",
+        cloud_contributes: "skip_conflict",
+        repo_contributes: "skip_conflict",
+        repo_wins: "cloud_write",
+        cloud_wins: "local_write",
+    },
+    in_sync: {
+        bare: "skip",
+        cloud_contributes: "skip",
+        repo_contributes: "skip",
+        repo_wins: "skip",
+        cloud_wins: "skip",
+    },
+    invalid_file: {
+        bare: "invalid",
+        cloud_contributes: "invalid",
+        repo_contributes: "invalid",
+        repo_wins: "invalid",
+        cloud_wins: "invalid",
+    },
+};
+export function planAction(verdict, mode) {
+    return TABLE[verdict][mode];
+}
+/** Assign an action to every document under the given mode. */
+export function buildPlan(documents, mode) {
+    return documents.map((doc) => ({
+        doc,
+        action: planAction(doc.verdict, mode),
+    }));
+}
+//# sourceMappingURL=plan.js.map

package/dist/sync/render.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Presentation helpers over the comparison result — shared by `dotreq diff`
+ * and `dotreq sync` so their vocabulary can't drift.
+ */
+import type { DocumentComparison, UnitDetail } from "./types.js";
+/** The stable token a user would pass as scope to act on this document: its
+ * file basename when local, else its cloud id, else its title. */
+export declare function scopeToken(doc: DocumentComparison): string;
+/** A human name for the document in listings. */
+export declare function displayName(doc: DocumentComparison): string;
+/** The copy-pasteable resolution command for a conflict (DIFF-5, SYNC-MODE-1.2). */
+export declare function resolutionHint(doc: DocumentComparison): string;
+/** One line per document: glyph, name, verdict. */
+export declare function formatVerdictLine(doc: DocumentComparison): string;
+/** Verbose, one-level-unfolded detail for a document (DIFF-2). */
+export declare function formatUnitDetail(detail: UnitDetail): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/sync/render.js

@@ -0,0 +1,46 @@
+/**
+ * Presentation helpers over the comparison result — shared by `dotreq diff`
+ * and `dotreq sync` so their vocabulary can't drift.
+ */
+import * as path from "node:path";
+import { verdictLabel } from "./types.js";
+/** A short glyph per verdict for scannable output. */
+const GLYPH = {
+    in_sync: "✓",
+    additions_in_repo: "→",
+    additions_in_cloud: "←",
+    conflict: "!",
+    only_in_repo: "+",
+    only_in_cloud: "+",
+    invalid_file: "✗",
+};
+/** The stable token a user would pass as scope to act on this document: its
+ * file basename when local, else its cloud id, else its title. */
+export function scopeToken(doc) {
+    if (doc.filePath)
+        return path.basename(doc.filePath);
+    return doc.documentId ?? doc.title;
+}
+/** A human name for the document in listings. */
+export function displayName(doc) {
+    if (doc.filePath)
+        return path.basename(doc.filePath);
+    return `${doc.title} (cloud)`;
+}
+/** The copy-pasteable resolution command for a conflict (DIFF-5, SYNC-MODE-1.2). */
+export function resolutionHint(doc) {
+    return `resolve with \`dotreq sync ${scopeToken(doc)} --repo-wins\` or \`--cloud-wins\``;
+}
+/** One line per document: glyph, name, verdict. */
+export function formatVerdictLine(doc) {
+    return `  ${GLYPH[doc.verdict]} ${displayName(doc).padEnd(40)} ${verdictLabel(doc.verdict)}`;
+}
+/** Verbose, one-level-unfolded detail for a document (DIFF-2). */
+export function formatUnitDetail(detail) {
+    const positions = detail.positions && detail.positions.length > 0
+        ? ` (${detail.note === "prose" ? "" : "positions "}${detail.positions.join(", ")})`
+        : "";
+    const label = detail.note === "prose" ? "prose" : detail.unit;
+    return `    ${label}: ${verdictLabel(detail.verdict)}${positions}`;
+}
+//# sourceMappingURL=render.js.map

package/dist/sync/segment.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Segment a document body into an ordered sequence of units — prose passages
+ * and requirement blocks, interleaved (the comparator's structural input).
+ *
+ * A requirement's identity is its key; a prose passage's identity is its
+ * normalized text (prose has no stable id, so a reworded passage reads as a
+ * removal-plus-addition — a conflict, per DIFF-4.3).
+ */
+export type Unit = {
+    kind: "prose";
+    text: string;
+} | {
+    kind: "requirement";
+    key: string;
+    blockContent: string;
+};
+/**
+ * Normalize prose for comparison: LF line endings, trailing whitespace
+ * stripped per line, runs of blank lines collapsed, ends trimmed. Two prose
+ * passages that differ only in incidental whitespace compare equal, so a
+ * whitespace-only reflow does not read as a conflict.
+ */
+export declare function normalizeProse(text: string): string;
+/**
+ * Split a body into its ordered units. Prose between (and around) fences
+ * becomes prose units when non-empty after normalization; each fence becomes a
+ * requirement unit keyed by its first-line KEY.
+ */
+export declare function segmentBody(body: string): Unit[];
+/**
+ * Flatten a requirement block into a map from position-path id (e.g. "AUTH-1",
+ * "AUTH-1.0", "AUTH-1.2.1") to a canonical label+content string.
+ *
+ * Because the id encodes the position, a criterion inserted mid-list shifts the
+ * ids of everything after it — so an insertion cannot subset-match the original
+ * (DIFF-4.2), while an appended criterion adds a new id without disturbing the
+ * others (DIFF-4.1).
+ */
+export declare function requirementUnitMap(blockContent: string): Map<string, string>;
+//# sourceMappingURL=segment.d.ts.map