@popoverai/dotrequirements 0.33.0 → 0.34.0

package/dist/schema/schemas.d.ts

@@ -86,6 +86,8 @@ export declare const MetadataSchema: z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         title: z.ZodOptional<z.ZodString>;
         defaultPrefix: z.ZodOptional<z.ZodString>;
+        solution: z.ZodOptional<z.ZodString>;
+        outcome: z.ZodOptional<z.ZodString>;
         attachments: z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
             url: z.ZodString;
             title: z.ZodOptional<z.ZodString>;
@@ -112,6 +114,8 @@ export declare const MetadataSchema: z.ZodObject<{
         id?: string | undefined;
         title?: string | undefined;
         defaultPrefix?: string | undefined;
+        solution?: string | undefined;
+        outcome?: string | undefined;
         attachments?: {
             url: string;
             title?: string | undefined;
@@ -120,6 +124,8 @@ export declare const MetadataSchema: z.ZodObject<{
         id?: string | undefined;
         title?: string | undefined;
         defaultPrefix?: string | undefined;
+        solution?: string | undefined;
+        outcome?: string | undefined;
         attachments?: {
             url: string;
             title?: string | undefined;
@@ -133,6 +139,8 @@ export declare const MetadataSchema: z.ZodObject<{
         id?: string | undefined;
         title?: string | undefined;
         defaultPrefix?: string | undefined;
+        solution?: string | undefined;
+        outcome?: string | undefined;
         attachments?: {
             url: string;
             title?: string | undefined;
@@ -146,6 +154,8 @@ export declare const MetadataSchema: z.ZodObject<{
         id?: string | undefined;
         title?: string | undefined;
         defaultPrefix?: string | undefined;
+        solution?: string | undefined;
+        outcome?: string | undefined;
         attachments?: {
             url: string;
             title?: string | undefined;
@@ -213,6 +223,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
             title: z.ZodOptional<z.ZodString>;
             defaultPrefix: z.ZodOptional<z.ZodString>;
+            solution: z.ZodOptional<z.ZodString>;
+            outcome: z.ZodOptional<z.ZodString>;
             attachments: z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
                 url: z.ZodString;
                 title: z.ZodOptional<z.ZodString>;
@@ -239,6 +251,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -247,6 +261,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -260,6 +276,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -273,6 +291,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -288,6 +308,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
             title: z.ZodOptional<z.ZodString>;
             defaultPrefix: z.ZodOptional<z.ZodString>;
+            solution: z.ZodOptional<z.ZodString>;
+            outcome: z.ZodOptional<z.ZodString>;
             attachments: z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
                 url: z.ZodString;
                 title: z.ZodOptional<z.ZodString>;
@@ -314,6 +336,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -322,6 +346,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -335,6 +361,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -348,6 +376,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -363,6 +393,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
             title: z.ZodOptional<z.ZodString>;
             defaultPrefix: z.ZodOptional<z.ZodString>;
+            solution: z.ZodOptional<z.ZodString>;
+            outcome: z.ZodOptional<z.ZodString>;
             attachments: z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
                 url: z.ZodString;
                 title: z.ZodOptional<z.ZodString>;
@@ -389,6 +421,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -397,6 +431,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -410,6 +446,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -423,6 +461,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;

package/dist/schema/schemas.js

@@ -147,6 +147,10 @@ export const MetadataSchema = z.object({
         id: z.string().optional(), // Cloud document link - filled by push when creating
         title: z.string().optional(), // Legacy fallback — the body's leading H1 is the title
         defaultPrefix: z.string().optional(), // Editor hint for new requirement keys
+        // SOLDOC-5: the solution (by id) and the outcome (by name) this document
+        // belongs to. Written by the sync; the truth once present.
+        solution: z.string().optional(),
+        outcome: z.string().optional(),
         // ATTACH-10: links attached to the document (a Miro board, a reference
         // page). Round-trips through sync — the cloud stores them as document
         // metadata, the file carries them here.

package/dist/sync/execute.d.ts

@@ -9,6 +9,7 @@
  */
 import type { PlannedAction, SyncMode } from "./plan.js";
 import type { CloudAuth } from "./snapshot.js";
+import { type SolutionForSync } from "./solution-documents.js";
 import type { CloudSnapshot, DocumentComparison } from "./types.js";
 export interface SyncOutcome {
     cloudCreated: number;
@@ -59,6 +60,8 @@ export interface SyncOutcome {
         name: string;
         warning: string;
     }>;
+    /** SOLDOC-5.1/5.2: a file whose path and frontmatter disagree about where it belongs. Optional so an outcome built before the field existed still reads. */
+    belongingWarnings?: string[];
     /** SYNC-CLI-EDIT-3.1: files whose notation the cloud changed on storing —
      * list markers, emphasis characters, spacing. Counted so the sync can say
      * the reformatting happened and why, instead of leaving Jaime to discover
@@ -85,5 +88,11 @@ export interface SyncOutcome {
  * 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, mode: SyncMode): Promise<SyncOutcome>;
+export declare function executePlan(plan: PlannedAction[], cloud: CloudSnapshot, auth: CloudAuth, workspaceRoot: string, mode: SyncMode, 
+/**
+ * The project's solutions, as `projectSolutions` read them; null (the
+ * default) when the project's team doesn't have solutions
+ * (SOLACCESS-2.2), so no file is placed as a solution's.
+ */
+solutions?: SolutionForSync[] | null): Promise<SyncOutcome>;
 //# sourceMappingURL=execute.d.ts.map

package/dist/sync/execute.js

@@ -16,8 +16,9 @@ import { parseFilesForPushIndividually, WEB_APP_URL } from "../push/core.js";
 import { composeMarkdownWithTitle, splitLeadingH1, writeRequirementsFile, } from "../schema/index.js";
 import { commandErrorMessage } from "../utils/command-error.js";
 import { cloudAttachmentRemovals, resolveAttachments } from "./attachments.js";
-import { resolveLocalPath } from "./local-files.js";
+import { resolveLocalPath, sanitizeFileName } from "./local-files.js";
 import { publishToCloud } from "./publish.js";
+import { requirementsDocByName, resolveBelonging, solutionDirOf, solutionDocumentPath, } from "./solution-documents.js";
 function emptyOutcome() {
     return {
         cloudCreated: 0,
@@ -35,6 +36,7 @@ function emptyOutcome() {
         writeBackWarnings: [],
         importWarnings: [],
         publishWarnings: [],
+        belongingWarnings: [],
         normalized: [],
         renames: [],
         inferredPrefixes: [],
@@ -45,7 +47,13 @@ function emptyOutcome() {
  * 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, mode) {
+export async function executePlan(plan, cloud, auth, workspaceRoot, mode, 
+/**
+ * The project's solutions, as `projectSolutions` read them; null (the
+ * default) when the project's team doesn't have solutions
+ * (SOLACCESS-2.2), so no file is placed as a solution's.
+ */
+solutions = null) {
     const outcome = emptyOutcome();
     const client = new ConvexHttpClient(convexUrl());
     const cloudById = new Map(cloud.documents.map((d) => [d.documentId, d]));
@@ -64,7 +72,7 @@ export async function executePlan(plan, cloud, auth, workspaceRoot, mode) {
                     outcome.invalid.push(doc);
                     break;
                 case "cloud_write":
-                    await cloudWrite(auth, doc, cloudById, outcome, mode);
+                    await cloudWrite(auth, doc, cloudById, outcome, mode, solutions);
                     break;
                 case "cloud_delete":
                     await cloudDelete(client, auth, doc, outcome);
@@ -161,7 +169,7 @@ async function syncResidualAttachments(client, auth, doc, action, outcome, mode)
         outcome.attachmentWrites++;
     }
 }
-async function cloudWrite(auth, doc, cloudById, outcome, mode) {
+async function cloudWrite(auth, doc, cloudById, outcome, mode, solutions) {
     if (!auth.projectSlug || !doc.filePath) {
         throw new Error("Cannot write to the cloud without project credentials.");
     }
@@ -170,6 +178,24 @@ async function cloudWrite(auth, doc, cloudById, outcome, mode) {
     if (!parsed)
         throw new Error(`Could not parse ${path.basename(doc.filePath)}`);
     const meta = parsed.metadata.document;
+    // SOLDOC-3/4/5: what the file's name and place say about it. A file in a
+    // solution directory with no frontmatter declares its belonging by its
+    // path; one with frontmatter keeps that, and a disagreeing path is reported.
+    // SOLACCESS-2.2: without solutions, a file is placed as it was before them.
+    const withSolutions = solutions !== null;
+    const resolved = withSolutions
+        ? resolveBelonging(doc.filePath, { solution: meta?.solution, outcome: meta?.outcome }, solutionDirOf(doc.filePath), solutions)
+        : { belonging: undefined, warning: undefined };
+    if (resolved.warning) {
+        outcome.belongingWarnings = [
+            ...(outcome.belongingWarnings ?? []),
+            resolved.warning,
+        ];
+    }
+    const belonging = resolved.belonging;
+    const isRequirementsDoc = withSolutions
+        ? requirementsDocByName(doc.filePath)
+        : undefined;
     // 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
@@ -214,6 +240,8 @@ async function cloudWrite(auth, doc, cloudById, outcome, mode) {
                 : []
             : undefined,
         runMarker: parsed.metadata.ctsRun,
+        solution: belonging,
+        isRequirementsDoc,
     });
     const documentId = saveResult.documentId;
     // ATTACH-10.3.1.0: the publish above is the push that removes cloud
@@ -319,6 +347,9 @@ async function cloudWrite(auth, doc, cloudById, outcome, mode) {
         // the title.
         writeRequirementsFile(doc.filePath, {
             documentId,
+            // SOLDOC-4.1: the belonging the path declared is written into the
+            // frontmatter, where it is the truth from now on.
+            belonging,
             // The prefix just pushed is the file's own (or the one inferred from
             // its first key, DOC-HEADER-11.4, which the write-back materializes).
             defaultPrefix: meta?.defaultPrefix
@@ -365,8 +396,9 @@ function localWrite(doc, cloudById, usedPaths, requirementsDir, outcome, mode) {
         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);
+    const filePath = placeCloudDocument(cloudDoc, doc.filePath, usedPaths, requirementsDir);
     usedPaths.add(filePath);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
     // DOC-HEADER-11.6/11.7: a cloud document with no prefix means "nothing to
     // impose" under an additive sync and "no prefix" under cloud-wins authority
     // — so a prefix Jaime wrote is only ever removed by the mode they ran to
@@ -390,10 +422,42 @@ function localWrite(doc, cloudById, usedPaths, requirementsDir, outcome, mode) {
         defaultPrefix,
         attachments,
         version: cloudDoc.version,
+        belonging: cloudDoc.solution
+            ? {
+                solutionId: cloudDoc.solution.solutionId,
+                outcome: cloudDoc.solution.outcome,
+            }
+            : undefined,
     }, cloudDoc.body);
     if (changed)
         outcome.localWritten++;
 }
+/**
+ * SOLDOC-6: where a pulled document lands. A file it is already linked to
+ * keeps its path (SYNC-DISCOVERY-2.0); a document that belongs to a solution
+ * lands in that solution's directory, named for its outcome; a document
+ * that is not a requirements document and belongs to no solution has no
+ * place, and the pull says so rather than guessing.
+ */
+function placeCloudDocument(cloudDoc, existingPath, usedPaths, requirementsDir) {
+    if (existingPath)
+        return existingPath;
+    const isRequirementsDoc = cloudDoc.isRequirementsDoc !== false;
+    if (cloudDoc.solution) {
+        // SOLDOC-9: the solution's own directory name; a backend from before it
+        // was sent leaves it out, and the title's slug stands in.
+        const candidate = solutionDocumentPath(requirementsDir, cloudDoc.solution.directory ??
+            sanitizeFileName(cloudDoc.solution.title ?? cloudDoc.solution.solutionId), cloudDoc.solution.outcome, isRequirementsDoc);
+        if (usedPaths.has(candidate) || fs.existsSync(candidate)) {
+            throw new Error(`"${cloudDoc.title}" belongs at ${path.relative(path.dirname(requirementsDir), candidate)}, but another file is already there.`);
+        }
+        return candidate;
+    }
+    if (!isRequirementsDoc) {
+        throw new Error(`"${cloudDoc.title}" is not a requirements document and belongs to no solution, so the pull has nowhere to put it.`);
+    }
+    return resolveLocalPath(cloudDoc, existingPath, usedPaths, requirementsDir);
+}
 function localDelete(doc, outcome) {
     if (!doc.filePath)
         return;

package/dist/sync/index.d.ts

@@ -6,7 +6,7 @@ import type { ComparisonResult, DocumentComparison } from "./types.js";
 export { compareSnapshots, duplicateIdAbortMessage, 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 { acquireCloudSnapshot, acquireLocalSnapshot, type CloudAuth, foreignDocumentNotes, projectSolutions, readLocalDocument, } from "./snapshot.js";
 export type { CloudDocument, CloudSnapshot, ComparisonResult, DocumentComparison, LocalDocument, LocalSnapshot, UnitDetail, Verdict, } from "./types.js";
 export { verdictLabel } from "./types.js";
 /**

package/dist/sync/index.js

@@ -6,7 +6,7 @@ import * as path from "node:path";
 export { compareSnapshots, duplicateIdAbortMessage, 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 { acquireCloudSnapshot, acquireLocalSnapshot, foreignDocumentNotes, projectSolutions, 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

package/dist/sync/publish.d.ts

@@ -32,6 +32,13 @@ export interface PublishParams {
         title?: string;
     }>;
     runMarker?: string;
+    /** SOLDOC-4/5: the belonging the file declares. */
+    solution?: {
+        solutionId: string;
+        outcome: string;
+    };
+    /** SOLDOC-3: what the file's name says; undefined where the rule doesn't reach. */
+    isRequirementsDoc?: boolean;
 }
 /**
  * What the server reports back: the document, any run-marker complaint, and any

package/dist/sync/segment.js

@@ -6,7 +6,10 @@
  * normalized text (prose has no stable id, so a reworded passage reads as a
  * removal-plus-addition — a conflict, per DIFF-4.3).
  */
-import { canonicalRequirementKey, canonicalRequirementPath, getAllRequirements, parseRequirementBlock, splitRequirementFenceContent, } from "../schema/index.js";
+// From the fs-free modules, not the schema index, so the backend can bundle
+// the comparator for merging a solution's branch (BRANCH-7).
+import { getAllRequirements, parseRequirementBlock, splitRequirementFenceContent, } from "../schema/parser-core.js";
+import { canonicalRequirementKey, canonicalRequirementPath, } from "../schema/schemas.js";
 /** Matches a fenced dotrequirements block; group 1 is its inner content. */
 const FENCE = /```dotrequirements\n([\s\S]*?)```/gm;
 /**

package/dist/sync/snapshot.d.ts

@@ -3,6 +3,7 @@
  * the comparator stays a pure function (compare.ts). The local half reads the
  * workspace; the cloud half is one export query.
  */
+import type { SolutionForSync } from "./solution-documents.js";
 import type { CloudSnapshot, LocalDocument, LocalSnapshot } from "./types.js";
 /**
  * Read and classify one requirements file into a LocalDocument. A file whose
@@ -15,7 +16,21 @@ 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 declare function acquireLocalSnapshot(workspaceRoot: string, filePaths?: string[], options?: {
+    solutions?: boolean;
+}): Promise<LocalSnapshot>;
+/**
+ * The project's solutions as the sync places files by them (SOLDOC-4), or
+ * null when the project's team doesn't have solutions, so the sync behaves
+ * as it did before solutions (SOLACCESS-2.2). Whether it has them is the
+ * export's answer — the one the cloud side was read with — so the local
+ * side can't follow a different one. A share run places nothing, so it
+ * needs no list. A failure to fetch the list fails the sync, as does a
+ * switch flipped between the two reads: guessing would leave solution
+ * documents out of the repo's side, and a repo-wins sync would delete them
+ * from the cloud.
+ */
+export declare function projectSolutions(auth: CloudAuth, cloud: CloudSnapshot): Promise<SolutionForSync[] | null>;
 export interface CloudAuth {
     /** projectSlug + projectSecret for full access, or a bare share token. */
     projectSlug?: string;
@@ -27,4 +42,11 @@ export interface CloudAuth {
  * names the project) — the read-only path never writes back.
  */
 export declare function acquireCloudSnapshot(auth: CloudAuth): Promise<CloudSnapshot>;
+/**
+ * SYNC-FAIL-5: of the ids the workspace's files carry, the ones that name
+ * another project's document, each with the words a push of that file gets,
+ * so `dotreq diff` says what `dotreq sync` will. A backend that can't answer
+ * leaves the diff as it was rather than failing it.
+ */
+export declare function foreignDocumentNotes(auth: CloudAuth, documentIds: string[]): Promise<Map<string, string>>;
 //# sourceMappingURL=snapshot.d.ts.map

package/dist/sync/snapshot.js

@@ -8,7 +8,7 @@ import { ConvexHttpClient } from "convex/browser";
 import YAML from "yaml";
 import { convexUrl } from "../cloud.js";
 import { api } from "../convex.js";
-import { findRequirementsFiles } from "../requirements/index.js";
+import { findRequirementsFiles, findSyncedFiles, } from "../requirements/index.js";
 import { splitLeadingH1, validateMetadata } from "../schema/index.js";
 import { parseRequirementBlocksFromMarkdown, splitFrontmatter, stripFrontmatterBlock, } from "../schema/parser-core.js";
 /**
@@ -33,6 +33,8 @@ export function readLocalDocument(filePath) {
     let title;
     let defaultPrefix;
     let attachments;
+    let solution;
+    let outcome;
     let frontmatterError;
     const split = splitFrontmatter(raw);
     if (split) {
@@ -57,6 +59,11 @@ export function readLocalDocument(filePath) {
                     title = d.title;
                 if (typeof d.defaultPrefix === "string")
                     defaultPrefix = d.defaultPrefix;
+                // SOLDOC-5: the belonging, read like the id — before validation.
+                if (typeof d.solution === "string")
+                    solution = d.solution;
+                if (typeof d.outcome === "string")
+                    outcome = d.outcome;
                 // 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.
@@ -108,6 +115,8 @@ export function readLocalDocument(filePath) {
         title: derivedTitle,
         defaultPrefix,
         attachments,
+        solution,
+        outcome,
         body,
     };
 }
@@ -115,10 +124,44 @@ export function readLocalDocument(filePath) {
  * 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));
+export async function acquireLocalSnapshot(workspaceRoot, filePaths, options = {}) {
+    // SOLACCESS-2.2: a project whose team doesn't have solutions syncs the
+    // files it always did — solution directories' Markdown is left alone.
+    const paths = filePaths ??
+        (options.solutions === false
+            ? await findRequirementsFiles(workspaceRoot)
+            : await findSyncedFiles(workspaceRoot));
     return { documents: paths.map(readLocalDocument) };
 }
+/**
+ * The project's solutions as the sync places files by them (SOLDOC-4), or
+ * null when the project's team doesn't have solutions, so the sync behaves
+ * as it did before solutions (SOLACCESS-2.2). Whether it has them is the
+ * export's answer — the one the cloud side was read with — so the local
+ * side can't follow a different one. A share run places nothing, so it
+ * needs no list. A failure to fetch the list fails the sync, as does a
+ * switch flipped between the two reads: guessing would leave solution
+ * documents out of the repo's side, and a repo-wins sync would delete them
+ * from the cloud.
+ */
+export async function projectSolutions(auth, cloud) {
+    if (cloud.solutions !== true)
+        return null;
+    if (!auth.projectSlug)
+        return [];
+    const client = new ConvexHttpClient(convexUrl());
+    const answer = await client.query(api.solutions.queries.forSync, {
+        projectAuth: {
+            projectSlug: auth.projectSlug,
+            projectSecret: auth.projectSecret,
+        },
+        project: auth.projectSlug,
+    });
+    if (!Array.isArray(answer)) {
+        throw new Error("The project's solutions were switched off while syncing. Run the sync again.");
+    }
+    return answer;
+}
 /**
  * Build the cloud snapshot with one export query: the project's own, with a
  * project secret, or the share endpoint, with a bare share token (the token
@@ -140,6 +183,7 @@ export async function acquireCloudSnapshot(auth) {
     return {
         projectName: result.projectName,
         projectSlug: result.projectSlug,
+        solutions: result.solutions === true,
         documents: result.documents.map((d) => ({
             documentId: d.documentId,
             title: d.title,
@@ -148,7 +192,35 @@ export async function acquireCloudSnapshot(auth) {
             body: d.markdownContent,
             version: d.version,
             updatedAt: d.updatedAt,
+            solution: d.solution,
+            isRequirementsDoc: d.isRequirementsDoc,
         })),
     };
 }
+/**
+ * SYNC-FAIL-5: of the ids the workspace's files carry, the ones that name
+ * another project's document, each with the words a push of that file gets,
+ * so `dotreq diff` says what `dotreq sync` will. A backend that can't answer
+ * leaves the diff as it was rather than failing it.
+ */
+export async function foreignDocumentNotes(auth, documentIds) {
+    // A share token only syncs down, so it pushes nothing to warn about.
+    if (documentIds.length === 0 || !auth.projectSlug)
+        return new Map();
+    const client = new ConvexHttpClient(convexUrl());
+    try {
+        const foreign = (await client.query(api.documents.queries.foreignDocumentIds, {
+            projectAuth: {
+                projectSlug: auth.projectSlug,
+                projectSecret: auth.projectSecret,
+            },
+            project: auth.projectSlug,
+            documentIds,
+        }));
+        return new Map(foreign.map((f) => [f.documentId, f.message]));
+    }
+    catch {
+        return new Map();
+    }
+}
 //# sourceMappingURL=snapshot.js.map

package/dist/sync/solution-documents.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Where a solution's documents live, the sync's half (SOLDOC; the decision
+ * is in docs/working/four-areas-prototype.md, "Where a solution's documents
+ * live"). A document that belongs to a solution and is not a requirements
+ * document lives in a solution directory, `.requirements/solutions/<solution>/`,
+ * named for its outcome; the `.requirements.md` name is what makes a file a
+ * requirements document, wherever it sits. A new file declares its belonging
+ * by its path; once the frontmatter carries it, the frontmatter is the truth.
+ */
+export declare const SOLUTIONS_DIR = "solutions";
+/** What a file's place in the workspace says about it, before any frontmatter. */
+export interface PathClaim {
+    /** The solution directory's name and the file's stem, as slugs. */
+    solutionSlug: string;
+    outcomeSlug: string;
+}
+/** The solution directory a file sits directly in, if any (SOLDOC-8.1). */
+export declare function solutionDirOf(filePath: string): PathClaim | undefined;
+/** `pitch` for `pitch.md` and for `pitch.requirements.md`. */
+export declare function stemOf(fileName: string): string;
+/** SOLDOC-3: the name, never the content. Undefined for a file the rule doesn't reach. */
+export declare function requirementsDocByName(filePath: string): boolean | undefined;
+export interface SolutionForSync {
+    solutionId: string;
+    title: string;
+    /**
+     * The solution's directory name, which no other solution in the project
+     * has (SOLDOC-9). A backend from before it was sent leaves it out, and the
+     * title's slug stands in.
+     */
+    directory?: string;
+    outcomes: string[];
+}
+/** The directory a solution's documents live in, by name. */
+export declare function directoryOf(solution: SolutionForSync): string;
+export interface Belonging {
+    solutionId: string;
+    outcome: string;
+}
+export type Resolved = {
+    belonging: Belonging;
+    warning?: string;
+} | {
+    belonging: undefined;
+    warning?: string;
+};
+/**
+ * What a pushed file belongs to (SOLDOC-4, SOLDOC-5): the frontmatter's
+ * belonging when it has one, else what its path claims, resolved against
+ * the project's solutions. A frontmatter that disagrees with the path is
+ * kept and reported; a path that resolves to nothing refuses the push.
+ */
+export declare function resolveBelonging(filePath: string, frontmatter: {
+    solution?: string;
+    outcome?: string;
+}, claim: PathClaim | undefined, solutions: SolutionForSync[] | undefined): Resolved;
+/**
+ * SOLDOC-6, SOLDOC-9: where a pulled document that belongs to a solution
+ * lands when it has no file yet: in the solution's own directory, named for
+ * its outcome, with the `.requirements.md` name when it is a requirements
+ * document.
+ */
+export declare function solutionDocumentPath(requirementsDir: string, solutionDirectory: string, outcome: string, isRequirementsDoc: boolean): string;
+//# sourceMappingURL=solution-documents.d.ts.map