@popoverai/dotrequirements 0.30.1 → 0.32.0

package/dist/sync/compare.js

@@ -3,6 +3,7 @@
  * reads no disk and makes no network calls. `dotreq diff` renders its result,
  * `dotreq sync` acts on it, CI asserts on it.
  */
+import { attachmentListsEqual } from "./attachments.js";
 import { normalizeProse, requirementUnitMap, segmentBody, } from "./segment.js";
 /** Whitespace-only normalization for the fast-path body equality check. */
 function normalizeBody(body) {
@@ -184,6 +185,81 @@ function proseLabel(text) {
         ? `${firstLine.slice(0, 40)}…`
         : firstLine || "(prose)";
 }
+function attachmentLabel(url) {
+    return url.length > 60 ? `${url.slice(0, 60)}…` : url;
+}
+/**
+ * Describe attachment differences for `dotreq diff` (ATTACH-10.2). Display
+ * only: attachments never touch the document's verdict — they resolve by
+ * their own rule in sync/attachments.ts. The directional verdicts here name
+ * which side holds the difference, for the reader.
+ */
+function describeAttachments(local, cloud) {
+    const details = [];
+    const localByUrl = new Map((local ?? []).map((a) => [a.url, a]));
+    const cloudByUrl = new Map((cloud ?? []).map((a) => [a.url, a]));
+    for (const [url, a] of localByUrl) {
+        const c = cloudByUrl.get(url);
+        if (!c) {
+            details.push({
+                unit: attachmentLabel(url),
+                verdict: "additions_in_repo",
+                note: "attachment",
+            });
+        }
+        else if ((a.title ?? "") !== (c.title ?? "")) {
+            details.push({
+                unit: attachmentLabel(url),
+                verdict: (a.title ?? "") === "" ? "additions_in_cloud" : "additions_in_repo",
+                note: "attachment name",
+            });
+        }
+    }
+    for (const url of cloudByUrl.keys()) {
+        if (!localByUrl.has(url)) {
+            details.push({
+                unit: attachmentLabel(url),
+                verdict: "additions_in_cloud",
+                note: "attachment",
+            });
+        }
+    }
+    // Duplicate entries collapse in the URL-keyed maps above, so a
+    // duplicated row would flag `differ` with no detail line beneath it —
+    // a not-in-sync header over nothing. Count per URL and say so.
+    const countBy = (list) => {
+        const counts = new Map();
+        for (const a of list ?? [])
+            counts.set(a.url, (counts.get(a.url) ?? 0) + 1);
+        return counts;
+    };
+    const localCounts = countBy(local);
+    const cloudCounts = countBy(cloud);
+    for (const [url, n] of cloudCounts) {
+        // Both-sides URLs only: a cloud-only duplicated URL already gets the
+        // first loop's addition line, and a second line with the same label
+        // double-reports one link (round 10). No local twin — the frontmatter
+        // schema rejects duplicates, so such a file is invalid_file before it
+        // reaches this comparison.
+        const localN = localCounts.get(url);
+        if (n > 1 && localN !== undefined && n !== localN) {
+            details.push({
+                unit: attachmentLabel(url),
+                verdict: "additions_in_cloud",
+                note: "duplicated entry",
+            });
+        }
+    }
+    // `differ` is THE predicate every consumer gates on (the sync command's
+    // gate resolves it further by mode; the executor's residual path trusts
+    // it) — so it is computed by the same set-equality the resolver uses,
+    // not from these display details: the URL-keyed maps above collapse
+    // duplicate entries that the length-aware comparison still sees.
+    return {
+        differ: !attachmentListsEqual(local ?? [], cloud ?? []),
+        details,
+    };
+}
 /** Compare one document across surfaces. */
 function compareDocument(local, cloud) {
     const base = {
@@ -194,9 +270,17 @@ function compareDocument(local, cloud) {
     };
     const diverges = attributesDiverge(local, cloud);
     const body = local.body ?? "";
+    const attach = describeAttachments(local.attachments, cloud.attachments);
+    const attachments = {
+        local: local.attachments,
+        cloud: cloud.attachments ?? [],
+        differ: attach.differ,
+        details: attach.details,
+    };
     // Fast path: whitespace-identical bodies with matching attributes.
+    // Attachments deliberately don't gate this — they resolve on their own.
     if (!diverges && normalizeBody(body) === normalizeBody(cloud.body)) {
-        return { ...base, verdict: "in_sync" };
+        return { ...base, verdict: "in_sync", attachments };
     }
     // SYNC-FAIL-4.2: cloud bodies reach the snapshot as stored markdown, never
     // re-parsed, so a document saved before today's grammar can still be
@@ -211,21 +295,21 @@ function compareDocument(local, cloud) {
         classified = classifyBodies(body, cloud.body);
     }
     catch {
-        return { ...base, verdict: "conflict" };
+        // `attachments` rides along like every other return: without it the
+        // residual sync and verbose diff silently drop this document's links.
+        return { ...base, verdict: "conflict", attachments };
     }
     const { verdict: bodyVerdict, details } = classified;
-    let verdict;
-    if (diverges) {
-        // A changed single-valued attribute is never additive → conflict.
-        verdict = "conflict";
-    }
-    else {
-        verdict = bodyVerdict;
-    }
+    // ATTACH-10.2: the verdict is the BODY's verdict. Attachments never move
+    // it — a name difference could otherwise freeze the document
+    // (skip_conflict) or, worse, plan a destructive body publish over a
+    // colleague's unpublished work, from someone naming a link in frontmatter.
+    const verdict = diverges ? "conflict" : bodyVerdict;
     return {
         ...base,
         verdict,
         details: verdict === "in_sync" ? undefined : details,
+        attachments,
     };
 }
 /**

package/dist/sync/execute.d.ts

@@ -16,6 +16,17 @@ export interface SyncOutcome {
     cloudDeleted: number;
     localWritten: number;
     localDeleted: number;
+    /** ATTACH-10.2: attachment-only operations, outside the body actions. */
+    attachmentPushes: number;
+    attachmentWrites: number;
+    /** ATTACH-10.3.1.0: cloud attachments a push removed on the file's
+     * authority. Recorded only after the push succeeded — the report's trace
+     * must never claim a removal a refused or failed push left in place. */
+    attachmentRemovals: Array<{
+        name: string;
+        url: string;
+        title?: string;
+    }>;
     conflicts: DocumentComparison[];
     invalid: DocumentComparison[];
     errors: Array<{

package/dist/sync/execute.js

@@ -14,6 +14,7 @@ import { getConvexUrl } from "../config.js";
 import { api } from "../convex.js";
 import { parseFilesForPushIndividually, WEB_APP_URL } from "../push/core.js";
 import { composeMarkdownWithTitle, splitLeadingH1, writeRequirementsFile, } from "../schema/index.js";
+import { cloudAttachmentRemovals, resolveAttachments } from "./attachments.js";
 import { resolveLocalPath } from "./local-files.js";
 import { publishToCloud } from "./publish.js";
 function emptyOutcome() {
@@ -23,6 +24,9 @@ function emptyOutcome() {
         cloudDeleted: 0,
         localWritten: 0,
         localDeleted: 0,
+        attachmentPushes: 0,
+        attachmentWrites: 0,
+        attachmentRemovals: [],
         conflicts: [],
         invalid: [],
         errors: [],
@@ -59,7 +63,7 @@ export async function executePlan(plan, cloud, auth, workspaceRoot, mode) {
                     outcome.invalid.push(doc);
                     break;
                 case "cloud_write":
-                    await cloudWrite(auth, doc, cloudById, outcome);
+                    await cloudWrite(auth, doc, cloudById, outcome, mode);
                     break;
                 case "cloud_delete":
                     await cloudDelete(client, auth, doc, outcome);
@@ -71,6 +75,12 @@ export async function executePlan(plan, cloud, auth, workspaceRoot, mode) {
                     localDelete(doc, outcome);
                     break;
             }
+            // ATTACH-10.2: attachments resolve outside the body's verdict, so a
+            // body action may not have carried them — cover the residue. cloud_write
+            // pushed cloudFinal and wrote back localFinal; local_write wrote
+            // localFinal; deletes moot the question. Everything else (skip,
+            // skip_conflict, and the un-pushed side of local_write) lands here.
+            await syncResidualAttachments(client, auth, doc, action, outcome, mode);
         }
         catch (err) {
             outcome.errors.push({ name, error: errorDisplayMessage(err) });
@@ -78,6 +88,79 @@ export async function executePlan(plan, cloud, auth, workspaceRoot, mode) {
     }
     return outcome;
 }
+/**
+ * Attachment-only operations for whatever the body action didn't cover.
+ * The push goes through setAttachmentsForSync — a metadata patch, never the
+ * publish path, so naming a link cannot displace anyone's working document.
+ */
+async function syncResidualAttachments(client, auth, doc, action, outcome, mode) {
+    if (!doc.attachments?.differ || !doc.documentId)
+        return;
+    // A conflicted document is reported as left alone, with a resolution hint
+    // — rewriting its frontmatter or its cloud list would falsify that report
+    // for someone mid-resolution. Deletes and invalid files moot the question.
+    if (action === "cloud_delete" ||
+        action === "local_delete" ||
+        action === "invalid" ||
+        action === "skip_conflict") {
+        return;
+    }
+    const res = resolveAttachments(doc.attachments.local, doc.attachments.cloud, mode);
+    if (res.pushNeeded && action !== "cloud_write") {
+        if (!auth.projectSlug) {
+            throw new Error("Cannot sync attachments without project credentials.");
+        }
+        await client.mutation(api.documents.mutations.setAttachmentsForSync, {
+            projectAuth: {
+                projectSlug: auth.projectSlug,
+                projectSecret: auth.projectSecret,
+            },
+            target: { type: "project", slug: auth.projectSlug },
+            documentId: doc.documentId,
+            attachments: res.cloudFinal,
+            // Compare-and-set: the resolution was computed from the snapshot's
+            // cloud list; if the cloud moved since (a paste in the web app while
+            // this run sat at a prompt), replaying our list would delete it. The
+            // mutation refuses instead, and the next run resolves fresh.
+            expectAttachments: doc.attachments.cloud,
+        });
+        outcome.attachmentPushes++;
+        for (const removed of cloudAttachmentRemovals(doc.attachments, mode)) {
+            outcome.attachmentRemovals.push({
+                name: doc.title,
+                url: removed.url,
+                title: removed.title,
+            });
+        }
+    }
+    if (res.writeNeeded &&
+        res.localFinal !== undefined &&
+        action !== "local_write" &&
+        action !== "cloud_write" &&
+        doc.filePath) {
+        const { parsedFiles } = parseFilesForPushIndividually([doc.filePath]);
+        const parsed = parsedFiles[0];
+        if (!parsed)
+            return;
+        // The writer drops the legacy frontmatter `document.title`
+        // (SYNC-TITLE-1.2) — same compensation cloudWrite makes: an H1-less
+        // legacy body gets its title materialized as the leading H1, or an
+        // attachment-only write would leave the file untitled and the next
+        // compare would flag a phantom title conflict.
+        let body = parsed.markdownContent;
+        const legacyTitle = parsed.metadata.document?.title;
+        if (legacyTitle && splitLeadingH1(body).title === null) {
+            body = composeMarkdownWithTitle(legacyTitle, body);
+        }
+        writeRequirementsFile(doc.filePath, {
+            documentId: doc.documentId,
+            defaultPrefix: "keep",
+            attachments: { set: res.localFinal },
+            version: (parsed.metadata.version ?? 0) + 1,
+        }, body);
+        outcome.attachmentWrites++;
+    }
+}
 /**
  * Servers throw ConvexError({kind, message}) for expected failures; production
  * redacts the Error message to "Server Error" but preserves error.data.
@@ -89,7 +172,7 @@ function errorDisplayMessage(err) {
         return data.message;
     return err instanceof Error ? err.message : String(err);
 }
-async function cloudWrite(auth, doc, cloudById, outcome) {
+async function cloudWrite(auth, doc, cloudById, outcome, mode) {
     if (!auth.projectSlug || !doc.filePath) {
         throw new Error("Cannot write to the cloud without project credentials.");
     }
@@ -109,6 +192,7 @@ async function cloudWrite(auth, doc, cloudById, outcome) {
     if (meta?.title && splitLeadingH1(parsed.markdownContent).title === null) {
         parsed.markdownContent = composeMarkdownWithTitle(meta.title, parsed.markdownContent);
     }
+    const attachmentsRes = resolveAttachments(meta?.attachments, meta?.id ? cloudById.get(meta.id)?.attachments : undefined, mode);
     // SYNC-CLI-EDIT-2: the push goes to the web app, which writes it into the
     // working document Quinn may have open and publishes a copy printed from it.
     // Convex cannot do that job — the conversion needs the BlockNote schema.
@@ -124,9 +208,43 @@ async function cloudWrite(auth, doc, cloudById, outcome) {
         title: meta?.title,
         markdownContent: parsed.markdownContent,
         defaultPrefix: meta?.defaultPrefix,
+        // ATTACH-10.2: the push carries the RESOLVED list (sync/attachments.ts)
+        // — union in additive modes, authority as declared, a file with no
+        // attachments key having no opinion — or nothing at all when the
+        // cloud's list already is the resolution.
+        attachments: attachmentsRes.pushNeeded
+            ? attachmentsRes.cloudFinal
+            : undefined,
+        // Compare-and-set whenever the push replaces the list: the cloud copy
+        // the resolution was computed against. A link pasted mid-sync makes the
+        // publish refuse (dry-run first, so nothing is destroyed) instead of
+        // silently replaying the stale list over it.
+        expectAttachments: attachmentsRes.pushNeeded
+            ? meta?.id
+                ? (cloudById.get(meta.id)?.attachments ?? [])
+                : []
+            : undefined,
         runMarker: parsed.metadata.ctsRun,
     });
     const documentId = saveResult.documentId;
+    // ATTACH-10.3.1.0: the publish above is the push that removes cloud
+    // attachments under repo authority — trace them now that it has landed.
+    // Named by file, like every other per-document line here: doc.title is
+    // pinned to the OLD cloud title, so a push that renames the H1 and drops
+    // a link in one edit would print the removal against a title that no
+    // longer exists (round-2 release review).
+    if (attachmentsRes.pushNeeded) {
+        const cloudBefore = meta?.id
+            ? (cloudById.get(meta.id)?.attachments ?? [])
+            : [];
+        for (const removed of cloudAttachmentRemovals({ local: meta?.attachments, cloud: cloudBefore }, mode)) {
+            outcome.attachmentRemovals.push({
+                name: path.basename(doc.filePath),
+                url: removed.url,
+                title: removed.title,
+            });
+        }
+    }
     // The server accepted the publish and told us something after it did not
     // finish. Reported rather than dropped: the push DID land, so this is not a
     // failure, but "synced" on its own would claim more than happened.
@@ -217,6 +335,11 @@ async function cloudWrite(auth, doc, cloudById, outcome) {
             defaultPrefix: meta?.defaultPrefix
                 ? { set: meta.defaultPrefix }
                 : "keep",
+            // The file adopts its side of the resolution — cloud-held names it
+            // lacked, for one (ATTACH-10.2).
+            attachments: attachmentsRes.writeNeeded && attachmentsRes.localFinal !== undefined
+                ? { set: attachmentsRes.localFinal }
+                : "keep",
             version: (parsed.metadata.version ?? 0) + 1,
         }, contentToWriteBack);
         // Counted only once the rewrite actually happened: reporting it before a
@@ -265,9 +388,19 @@ function localWrite(doc, cloudById, usedPaths, requirementsDir, outcome, mode) {
         : mode === "cloud_wins"
             ? "clear"
             : "keep";
+    // ATTACH-10.0/10.2: the file adopts its side of the attachment resolution
+    // — cloud's list plus the file's own additions in additive modes, the
+    // cloud's exactly under cloud authority. An explicit empty list is written
+    // as `attachments: []` (present key = an opinion); no write happens when
+    // the file already agrees.
+    const attachRes = resolveAttachments(doc.attachments?.local, cloudDoc.attachments, mode);
+    const attachments = attachRes.writeNeeded && attachRes.localFinal !== undefined
+        ? { set: attachRes.localFinal }
+        : "keep";
     const changed = writeRequirementsFile(filePath, {
         documentId: cloudDoc.documentId,
         defaultPrefix,
+        attachments,
         version: cloudDoc.version,
     }, cloudDoc.body);
     if (changed)

package/dist/sync/publish.d.ts

@@ -21,6 +21,16 @@ export interface PublishParams {
     /** Legacy frontmatter title, used only as the server's H1-less fallback. */
     title?: string;
     defaultPrefix?: string;
+    /** document.attachments from the file's frontmatter (ATTACH-10.1). */
+    attachments?: Array<{
+        url: string;
+        title?: string;
+    }>;
+    /** Compare-and-set: the cloud attachments the sync read them against. */
+    expectAttachments?: Array<{
+        url: string;
+        title?: string;
+    }>;
     runMarker?: string;
 }
 /**

package/dist/sync/render.js

@@ -33,6 +33,13 @@ export function resolutionHint(doc) {
 }
 /** One line per document: glyph, name, verdict. */
 export function formatVerdictLine(doc) {
+    // ATTACH-10.2: attachments resolve outside the verdict, so a document can
+    // be in sync while its attachments differ — say so rather than reporting
+    // "in sync" over a real difference. (Diff is mode-independent, like the
+    // body verdicts: whether a sync would act on it depends on the mode.)
+    if (doc.verdict === "in_sync" && doc.attachments?.differ) {
+        return `  ~ ${displayName(doc).padEnd(40)} attachments differ`;
+    }
     return `  ${GLYPH[doc.verdict]} ${displayName(doc).padEnd(40)} ${verdictLabel(doc.verdict)}`;
 }
 /** Verbose, one-level-unfolded detail for a document (DIFF-2). */

package/dist/sync/snapshot.js

@@ -32,6 +32,7 @@ export function readLocalDocument(filePath) {
     let documentId;
     let title;
     let defaultPrefix;
+    let attachments;
     let frontmatterError;
     const split = splitFrontmatter(raw);
     if (split) {
@@ -56,6 +57,24 @@ export function readLocalDocument(filePath) {
                     title = d.title;
                 if (typeof d.defaultPrefix === "string")
                     defaultPrefix = d.defaultPrefix;
+                // ATTACH-10.1: attachments from frontmatter. Shape-filtered here for
+                // the same reason as the fields above; a malformed entry is caught by
+                // validateMetadata below and flags the file rather than half-syncing.
+                // A present-but-empty key (`attachments:` or `attachments: []`) is an
+                // explicit "none" — the tri-state the resolver needs: only a file
+                // with NO key has no opinion (sync/attachments.ts).
+                if (d.attachments === null) {
+                    attachments = [];
+                }
+                else if (Array.isArray(d.attachments)) {
+                    attachments = d.attachments
+                        .filter((a) => !!a && typeof a === "object" && !Array.isArray(a))
+                        .filter((a) => typeof a.url === "string")
+                        .map((a) => ({
+                        url: a.url,
+                        title: typeof a.title === "string" ? a.title : undefined,
+                    }));
+                }
             }
         }
         if (rawMeta !== undefined && !frontmatterError) {
@@ -83,7 +102,14 @@ export function readLocalDocument(filePath) {
     // frontmatter title stands only when the body has none (SYNC-TITLE-1.1);
     // with neither, the document is untitled (SYNC-TITLE-1.4).
     const derivedTitle = splitLeadingH1(body).title ?? title;
-    return { filePath, documentId, title: derivedTitle, defaultPrefix, body };
+    return {
+        filePath,
+        documentId,
+        title: derivedTitle,
+        defaultPrefix,
+        attachments,
+        body,
+    };
 }
 /**
  * Build the local snapshot from the workspace, or from an explicit set of file
@@ -113,6 +139,7 @@ export async function acquireCloudSnapshot(auth) {
             documentId: d.documentId,
             title: d.title,
             defaultPrefix: d.defaultPrefix,
+            attachments: d.attachments,
             body: d.markdownContent,
             version: d.version,
             updatedAt: d.updatedAt,

package/dist/sync/types.d.ts

@@ -11,6 +11,11 @@
 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 attached link (ATTACH-10): document metadata that syncs both ways. */
+export interface Attachment {
+    url: string;
+    title?: 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
@@ -22,6 +27,8 @@ export interface LocalDocument {
     documentId?: string;
     title?: string;
     defaultPrefix?: string;
+    /** document.attachments from frontmatter (ATTACH-10). */
+    attachments?: Attachment[];
     /** Frontmatter-stripped markdown body (the comparison unit, SYNC-ARCH-1). */
     body?: string;
     parseError?: string;
@@ -33,6 +40,8 @@ export interface CloudDocument {
     documentId: string;
     title: string;
     defaultPrefix?: string;
+    /** The document's attached links (ATTACH-10). */
+    attachments?: Attachment[];
     /** Published markdownContent (SYNC-ARCH-1). */
     body: string;
     version: number;
@@ -75,6 +84,20 @@ export interface DocumentComparison {
     error?: string;
     /** Unit-level breakdown, populated for verbose diff of non-in-sync documents. */
     details?: UnitDetail[];
+    /**
+     * ATTACH-10.2: attachments never contribute to `verdict` — they resolve by
+     * their own rule (sync/attachments.ts), so a name difference can neither
+     * freeze the body's sync nor plan a body write. This carries what that
+     * resolution needs: both sides' lists (`local` undefined = the file has no
+     * attachments key = no opinion) and display details for `dotreq diff`.
+     */
+    attachments?: {
+        local: Attachment[] | undefined;
+        cloud: Attachment[];
+        /** True when the two sides' lists differ (set semantics, names count). */
+        differ: boolean;
+        details: UnitDetail[];
+    };
 }
 export interface ComparisonResult {
     documents: DocumentComparison[];

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 greenfield-discovery` - Print the interview protocol for working out what something new should do. Run it when the user is starting something new and has not worked out what it should do — the interview beats drafting requirements from their description
+- `dotreq validate [--file <path>]` - Check syntax (works offline)
 - `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)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.30.1",
+  "version": "0.32.0",
   "description": "Requirements as testable, human-readable data — CLI and test harness for spec-driven development with AI coding agents",
   "type": "module",
   "bin": {
@@ -12,7 +12,8 @@
     "./test": "./dist/harness/index.js",
     "./schema": "./dist/schema/index.js",
     "./schema/browser": "./dist/schema/browser.js",
-    "./style-guide": "./dist/requirements/style-guide.js"
+    "./style-guide": "./dist/requirements/style-guide.js",
+    "./greenfield": "./dist/requirements/greenfield.js"
   },
   "publishConfig": {
     "access": "public"
@@ -49,7 +50,7 @@
     "email": "support@dotrequirements.io"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "dependencies": {
     "@babel/parser": "^7.28.5",
@@ -71,7 +72,7 @@
   },
   "devDependencies": {
     "@types/babel__traverse": "^7.28.0",
-    "@types/node": "^20",
+    "@types/node": "^22",
     "@types/uuid": "^11.0.0",
     "typescript": "^5",
     "vitest": "^4.1.10"