@popoverai/dotrequirements 0.27.4 → 0.29.0

package/dist/schema/schemas.js

@@ -106,8 +106,10 @@ export function buildRequirementKey(prefix, number) {
 // Metadata Schema
 // =============================================================================
 /**
- * Metadata block at the top of every requirements file.
- * Only document.title is required for push; everything else is optional or auto-filled.
+ * Metadata block at the top of every requirements file. Everything is
+ * optional or auto-filled; the document's title lives in the BODY as its
+ * leading H1 (SYNC-TITLE-1), with a legacy frontmatter title tolerated as a
+ * fallback for files from before that convention.
  */
 export const MetadataSchema = z.object({
     version: z.number().optional(), // Informational - incremented on push
@@ -116,7 +118,7 @@ export const MetadataSchema = z.object({
     document: z
         .object({
         id: z.string().optional(), // Cloud document link - filled by push when creating
-        title: z.string(), // Required for push
+        title: z.string().optional(), // Legacy fallback — the body's leading H1 is the title
         defaultPrefix: z.string().optional(), // Editor hint for new requirement keys
     })
         .optional(),
@@ -136,18 +138,13 @@ export const CONVEX_ID_PATTERN = /^j[a-z0-9]{31}$/;
  * SYNC-CLI-EDIT-1: Files with valid document.id update existing documents
  */
 export function validateForPush(metadata) {
-    // Must have document section
+    // Must have document section. (A title is NOT required — untitled
+    // documents are allowed, and the title is derived from the markdown's
+    // leading H1 anyway; see docs/working/h1-as-title.md.)
     if (!metadata.document) {
         return {
             valid: false,
-            reason: "Missing document section. Add a document section with a title to push this file.",
-        };
-    }
-    // Must have title
-    if (!metadata.document.title || metadata.document.title.trim() === "") {
-        return {
-            valid: false,
-            reason: "Document section missing required title.",
+            reason: "Missing document section. Add a document section to sync this file.",
         };
     }
     // Check document.id

package/dist/schema/title-markdown.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The document title and the markdown's leading H1 are the same thing
+ * (DOC-TITLE-3). These helpers hold that contract at the web app's storage
+ * boundary: markdown coming *in* from Convex is split into title + body, and
+ * markdown going *out* is recomposed — so inside the app, `Content.markdown`
+ * is always the body (no leading H1) and `Content.title` carries the title.
+ */
+export interface SplitMarkdown {
+    /** The leading H1's text, or null when the markdown has no leading H1. */
+    title: string | null;
+    /** Everything after the leading H1 (or the whole input when there is none). */
+    body: string;
+}
+/**
+ * Split a leading ATX H1 (`# Title`) off the markdown.
+ *
+ * "Leading" means the first non-blank line (DOC-TITLE-3.0); an H1 further
+ * down is ordinary content and stays in the body (DOC-TITLE-3.4). Markdown
+ * allows up to 3 spaces of heading indentation — 4+ is a code block, so it
+ * is not a title.
+ */
+export declare function splitLeadingH1(markdown: string): SplitMarkdown;
+/**
+ * Compose full-document markdown from a title and a body.
+ *
+ * The title becomes the leading H1 (DOC-TITLE-3.1); an untitled document
+ * gets no empty heading line (DOC-TITLE-3.3).
+ */
+export declare function composeMarkdownWithTitle(title: string, body: string): string;
+//# sourceMappingURL=title-markdown.d.ts.map

package/dist/schema/title-markdown.js

@@ -0,0 +1,38 @@
+/**
+ * The document title and the markdown's leading H1 are the same thing
+ * (DOC-TITLE-3). These helpers hold that contract at the web app's storage
+ * boundary: markdown coming *in* from Convex is split into title + body, and
+ * markdown going *out* is recomposed — so inside the app, `Content.markdown`
+ * is always the body (no leading H1) and `Content.title` carries the title.
+ */
+/**
+ * Split a leading ATX H1 (`# Title`) off the markdown.
+ *
+ * "Leading" means the first non-blank line (DOC-TITLE-3.0); an H1 further
+ * down is ordinary content and stays in the body (DOC-TITLE-3.4). Markdown
+ * allows up to 3 spaces of heading indentation — 4+ is a code block, so it
+ * is not a title.
+ */
+export function splitLeadingH1(markdown) {
+    const match = /^(?:[ \t]*\r?\n)* {0,3}# (.*)(?:\r?\n|$)/.exec(markdown);
+    if (!match) {
+        return { title: null, body: markdown };
+    }
+    const body = markdown.slice(match[0].length).replace(/^(\s*\r?\n)+/, "");
+    return { title: match[1].trim(), body };
+}
+/**
+ * Compose full-document markdown from a title and a body.
+ *
+ * The title becomes the leading H1 (DOC-TITLE-3.1); an untitled document
+ * gets no empty heading line (DOC-TITLE-3.3).
+ */
+export function composeMarkdownWithTitle(title, body) {
+    const trimmedTitle = title.trim();
+    if (!trimmedTitle)
+        return body;
+    if (!body.trim())
+        return `# ${trimmedTitle}\n`;
+    return `# ${trimmedTitle}\n\n${body}`;
+}
+//# sourceMappingURL=title-markdown.js.map

package/dist/sync/compare.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 type { CloudSnapshot, ComparisonResult, LocalSnapshot } from "./types.js";
+/**
+ * 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 declare function duplicateLocalDocumentIds(local: LocalSnapshot): Array<{
+    documentId: string;
+    filePaths: string[];
+}>;
+/**
+ * Compare the whole repo against the whole cloud, pairing documents by id.
+ */
+export declare function compareSnapshots(local: LocalSnapshot, cloud: CloudSnapshot): ComparisonResult;
+//# sourceMappingURL=compare.d.ts.map

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,53 @@
+/**
+ * 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;
+    }>;
+    /** SYNC-TITLE-1.3: pushes that changed a document's title. */
+    renames: Array<{
+        from: string;
+        to: 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