@popoverai/dotrequirements 0.27.4 → 0.28.0

package/dist/sync/local-files.js

@@ -0,0 +1,91 @@
+/**
+ * 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);
+    const metadata = {
+        pulledAt: new Date().toISOString(),
+        version: cloud.version,
+        ...(existingCtsRun ? { ctsRun: existingCtsRun } : {}),
+        document: {
+            id: cloud.documentId,
+            title: cloud.title,
+            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

package/dist/sync/segment.js

@@ -0,0 +1,76 @@
+/**
+ * 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).
+ */
+import { getAllRequirements, parseRequirementBlock } from "../schema/index.js";
+/** Matches a fenced dotrequirements block; group 1 is its inner content. */
+const FENCE = /```dotrequirements\n([\s\S]*?)```/gm;
+/**
+ * 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 function normalizeProse(text) {
+    return text
+        .replace(/\r\n/g, "\n")
+        .split("\n")
+        .map((line) => line.replace(/\s+$/, ""))
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+/**
+ * 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 function segmentBody(body) {
+    const normalized = body.replace(/\r\n/g, "\n");
+    const units = [];
+    let lastIndex = 0;
+    FENCE.lastIndex = 0;
+    let match = FENCE.exec(normalized);
+    while (match !== null) {
+        const prose = normalizeProse(normalized.slice(lastIndex, match.index));
+        if (prose)
+            units.push({ kind: "prose", text: prose });
+        const blockContent = match[1].trim();
+        const keyMatch = blockContent.match(/^([\w-]+):/);
+        // A block whose first line isn't KEY: is malformed; parsing rejects it
+        // upstream, so segmentation never sees it in the compare path. Fall back to
+        // the leading text as a key so segmentation stays total regardless.
+        const key = (keyMatch ? keyMatch[1] : blockContent.slice(0, 24)).toUpperCase();
+        units.push({ kind: "requirement", key, blockContent });
+        lastIndex = FENCE.lastIndex;
+        match = FENCE.exec(normalized);
+    }
+    const tail = normalizeProse(normalized.slice(lastIndex));
+    if (tail)
+        units.push({ kind: "prose", text: tail });
+    return units;
+}
+/**
+ * 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 function requirementUnitMap(blockContent) {
+    const key = blockContent.match(/^([\w-]+):/)?.[1] ?? "";
+    const tree = parseRequirementBlock(key, blockContent);
+    const map = new Map();
+    for (const node of getAllRequirements([tree])) {
+        // A NUL (\u0000) separates the label from content so a label change reads as a change.
+        map.set(node.id.toUpperCase(), `${node.label}\u0000${node.content}`);
+    }
+    return map;
+}
+//# sourceMappingURL=segment.js.map

package/dist/sync/snapshot.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Snapshot acquisition for the comparator — kept separate from comparison so
+ * the comparator stays a pure function (compare.ts). The local half reads the
+ * workspace; the cloud half is one exportProjectForCli query.
+ */
+import type { CloudSnapshot, LocalDocument, LocalSnapshot } from "./types.js";
+/**
+ * Read and classify one requirements file into a LocalDocument. A file whose
+ * body has a structural error (duplicate key/position, orphaned position) is
+ * returned with `parseError` set — the comparator reports it as invalid_file
+ * (SYNC-FAIL-4) — while its frontmatter title, if readable, is kept for display.
+ */
+export declare function readLocalDocument(filePath: string): LocalDocument;
+/**
+ * Build the local snapshot from the workspace, or from an explicit set of file
+ * paths (scope). Files are always read fresh from disk.
+ */
+export declare function acquireLocalSnapshot(workspaceRoot: string, filePaths?: string[]): Promise<LocalSnapshot>;
+export interface CloudAuth {
+    /** projectSlug + projectSecret for full access, or a bare share token. */
+    projectSlug?: string;
+    projectSecret: string;
+}
+/**
+ * Build the cloud snapshot with one exportProjectForCli query. A share token is
+ * passed as the projectSecret with no slug (the read-only wrapper resolves the
+ * project from the token) — the read-only path never writes back.
+ */
+export declare function acquireCloudSnapshot(auth: CloudAuth): Promise<CloudSnapshot>;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/sync/snapshot.js

@@ -0,0 +1,118 @@
+/**
+ * Snapshot acquisition for the comparator — kept separate from comparison so
+ * the comparator stays a pure function (compare.ts). The local half reads the
+ * workspace; the cloud half is one exportProjectForCli query.
+ */
+import * as fs from "node:fs";
+import { ConvexHttpClient } from "convex/browser";
+import YAML from "yaml";
+import { getConvexUrl } from "../config.js";
+import { api } from "../convex.js";
+import { findRequirementsFiles } from "../requirements/index.js";
+import { validateMetadata } from "../schema/index.js";
+import { parseRequirementBlocksFromMarkdown, splitFrontmatter, stripFrontmatterBlock, } from "../schema/parser-core.js";
+/**
+ * Read and classify one requirements file into a LocalDocument. A file whose
+ * body has a structural error (duplicate key/position, orphaned position) is
+ * returned with `parseError` set — the comparator reports it as invalid_file
+ * (SYNC-FAIL-4) — while its frontmatter title, if readable, is kept for display.
+ */
+export function readLocalDocument(filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf-8");
+    }
+    catch (err) {
+        return {
+            filePath,
+            parseError: `Could not read file: ${err.message}`,
+        };
+    }
+    // Frontmatter first, so a body-parse failure still yields id/title.
+    let documentId;
+    let title;
+    let defaultPrefix;
+    let frontmatterError;
+    const split = splitFrontmatter(raw);
+    if (split) {
+        // Pull id/title from the raw YAML before schema validation: an invalid
+        // frontmatter must not cost the file its identity, or its cloud
+        // counterpart re-pairs as "only_in_repo" and a sync mints a duplicate
+        // cloud document.
+        let rawMeta;
+        try {
+            rawMeta = YAML.parse(split.yaml);
+        }
+        catch (err) {
+            frontmatterError = `Invalid YAML frontmatter: ${err.message}`;
+        }
+        if (rawMeta && typeof rawMeta === "object" && !Array.isArray(rawMeta)) {
+            const rawDoc = rawMeta.document;
+            if (rawDoc && typeof rawDoc === "object" && !Array.isArray(rawDoc)) {
+                const d = rawDoc;
+                if (typeof d.id === "string")
+                    documentId = d.id;
+                if (typeof d.title === "string")
+                    title = d.title;
+                if (typeof d.defaultPrefix === "string")
+                    defaultPrefix = d.defaultPrefix;
+            }
+        }
+        if (rawMeta !== undefined && !frontmatterError) {
+            try {
+                validateMetadata(rawMeta);
+            }
+            catch (err) {
+                // Schema-invalid frontmatter flags the file (invalid_file) instead of
+                // proceeding with half-metadata — it must never sync as if unlinked.
+                frontmatterError = `Invalid frontmatter: ${err.message}`;
+            }
+        }
+    }
+    if (frontmatterError) {
+        return { filePath, documentId, title, parseError: frontmatterError };
+    }
+    const body = stripFrontmatterBlock(raw);
+    try {
+        parseRequirementBlocksFromMarkdown(body);
+    }
+    catch (err) {
+        return { filePath, documentId, title, parseError: err.message };
+    }
+    return { filePath, documentId, title, defaultPrefix, body };
+}
+/**
+ * Build the local snapshot from the workspace, or from an explicit set of file
+ * paths (scope). Files are always read fresh from disk.
+ */
+export async function acquireLocalSnapshot(workspaceRoot, filePaths) {
+    const paths = filePaths ?? (await findRequirementsFiles(workspaceRoot));
+    return { documents: paths.map(readLocalDocument) };
+}
+/**
+ * Build the cloud snapshot with one exportProjectForCli query. A share token is
+ * passed as the projectSecret with no slug (the read-only wrapper resolves the
+ * project from the token) — the read-only path never writes back.
+ */
+export async function acquireCloudSnapshot(auth) {
+    const client = new ConvexHttpClient(getConvexUrl());
+    const projectAuth = auth.projectSlug
+        ? { projectSlug: auth.projectSlug, projectSecret: auth.projectSecret }
+        : { projectSecret: auth.projectSecret };
+    const result = (await client.query(api.documents.queries.exportProjectForCli, {
+        projectAuth,
+    }));
+    return {
+        projectName: result.projectName,
+        projectSlug: result.projectSlug,
+        documents: result.documents.map((d) => ({
+            documentId: d.documentId,
+            title: d.title,
+            defaultPrefix: d.defaultPrefix,
+            body: d.markdownContent,
+            version: d.version,
+            updatedAt: d.updatedAt,
+        })),
+    };
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/sync/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared vocabulary for the repo/cloud comparator (DIFF-*, SYNC-*).
+ *
+ * One vocabulary, no translation layer: the verdict identifiers here are the
+ * words the CLI prints. `verdictLabel` only reshapes an identifier into its
+ * spaced form ("additions_in_repo" -> "additions in repo"); it never renames.
+ */
+/**
+ * Per-document verdict from comparing the repo and the cloud (DIFF-1.0).
+ */
+export type Verdict = "in_sync" | "additions_in_repo" | "additions_in_cloud" | "conflict" | "only_in_repo" | "only_in_cloud" | "invalid_file";
+/** The user-facing spelling of a verdict — same words, spaced. */
+export declare function verdictLabel(verdict: Verdict): string;
+/**
+ * One document as it exists locally: a `.requirements.md` file. When the file
+ * cannot be parsed, `parseError` is set and the other content fields are absent
+ * — the comparator reports it as `invalid_file` (SYNC-FAIL-4).
+ */
+export interface LocalDocument {
+    filePath: string;
+    /** document.id from frontmatter, when the file is linked to a cloud document. */
+    documentId?: string;
+    title?: string;
+    defaultPrefix?: string;
+    /** Frontmatter-stripped markdown body (the comparison unit, SYNC-ARCH-1). */
+    body?: string;
+    parseError?: string;
+}
+/**
+ * One published document as it exists in the cloud, from exportProjectForCli.
+ */
+export interface CloudDocument {
+    documentId: string;
+    title: string;
+    defaultPrefix?: string;
+    /** Published markdownContent (SYNC-ARCH-1). */
+    body: string;
+    version: number;
+    updatedAt: number;
+}
+export interface LocalSnapshot {
+    documents: LocalDocument[];
+}
+export interface CloudSnapshot {
+    projectName: string;
+    projectSlug: string;
+    documents: CloudDocument[];
+}
+/**
+ * A single point of difference within a paired document, for verbose
+ * document-scope diff (DIFF-2). `verdict` reuses the document vocabulary at
+ * unit granularity — the verdicts are fractal.
+ */
+export interface UnitDetail {
+    /** Requirement key, or a short prose descriptor. */
+    unit: string;
+    verdict: "additions_in_repo" | "additions_in_cloud" | "conflict";
+    /** Criterion positions new on one side, when the difference is criterion-level. */
+    positions?: string[];
+    note?: string;
+}
+/**
+ * The comparison of one document across the two surfaces. Identity for
+ * scoping/output comes from documentId / filePath / title directly.
+ */
+export interface DocumentComparison {
+    verdict: Verdict;
+    /** File path when the document exists locally. */
+    filePath?: string;
+    /** Cloud document id when the document exists in the cloud. */
+    documentId?: string;
+    /** Display title (from whichever side has the document). */
+    title: string;
+    /** Parse error message when verdict is invalid_file. */
+    error?: string;
+    /** Unit-level breakdown, populated for verbose diff of non-in-sync documents. */
+    details?: UnitDetail[];
+}
+export interface ComparisonResult {
+    documents: DocumentComparison[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/sync/types.js

@@ -0,0 +1,12 @@
+/**
+ * Shared vocabulary for the repo/cloud comparator (DIFF-*, SYNC-*).
+ *
+ * One vocabulary, no translation layer: the verdict identifiers here are the
+ * words the CLI prints. `verdictLabel` only reshapes an identifier into its
+ * spaced form ("additions_in_repo" -> "additions in repo"); it never renames.
+ */
+/** The user-facing spelling of a verdict — same words, spaced. */
+export function verdictLabel(verdict) {
+    return verdict.replace(/_/g, " ");
+}
+//# sourceMappingURL=types.js.map

package/dist/templates/context-file-section.md

@@ -57,7 +57,8 @@ test(requirement('REQ-ID.0'), () => { /* test specific criterion */ });
 **Authoring:**
 - `dotreq create-requirement-document [path]` - Print the template and style guide
 - `dotreq validate [glob]` - Check syntax (works offline)
-- `dotreq push [file]` - Sync to cloud (shows diff preview, then confirms)
+- `dotreq diff [scope...]` - Show how the repo and the cloud differ (read-only)
+- `dotreq sync [scope...]` - Reconcile the repo and the cloud (both contribute by default)
 
 **Review (judgment runs in the dispatched subagent):**
 - `dotreq style-check <file>` - Emits the style guide + content for the reviewer to judge (`--source cloud` for hosted review)