@popoverai/dotrequirements 0.24.3 → 0.26.0

package/dist/push/core.js

@@ -14,6 +14,8 @@ import * as path from "node:path";
 import { ConvexHttpClient } from "convex/browser";
 import { api } from "../convex.js";
 import { buildRequirementsFile, getAllRequirements, parseRequirementKey, parseRequirementsFromFile, } from "../schema/index.js";
+/** Base URL of the web app, where synced documents are reviewed. */
+export const WEB_APP_URL = "https://app.dotrequirements.io";
 // ============================================================================
 // Parsing
 // ============================================================================
@@ -170,13 +172,15 @@ export async function executePush(dryRunResult, credentials) {
     let created = 0;
     let updated = 0;
     const errors = [];
+    const importWarnings = [];
+    const synced = [];
     for (const { file, result } of pushableFiles) {
         const doc = file.metadata.document;
         const fileName = path.basename(file.filePath);
         // For not_found, clear the ID so we create a new document
         const effectiveDocId = result.action === "not_found" ? undefined : doc.id;
         try {
-            const pushResult = (await client.mutation(api.documents.saveWithRequirements.saveWithRequirements, {
+            const rawResult = (await client.mutation(api.documents.saveWithRequirements.saveWithRequirements, {
                 projectAuth: {
                     projectSlug: credentials.projectId,
                     projectSecret: credentials.projectSecret,
@@ -186,8 +190,21 @@ export async function executePush(dryRunResult, credentials) {
                 title: doc.title,
                 markdownContent: file.markdownContent,
                 defaultPrefix: doc.defaultPrefix,
+                // IMPORT-2: forward the CTS run marker when the file is stamped
+                runMarker: file.metadata.ctsRun,
                 dryRun: false,
             }));
+            // The server returns a structured result iff we sent a runMarker
+            const pushResult = typeof rawResult === "string" ? rawResult : rawResult.documentId;
+            if (typeof rawResult !== "string") {
+                const status = rawResult.importStatus;
+                if (status === "invalid_marker" ||
+                    status === "unsupported_version" ||
+                    status === "already_used") {
+                    // IMPORT-3.2/3.3: loud, never fatal
+                    importWarnings.push({ fileName, status });
+                }
+            }
             const isCreate = result.action === "create" || result.action === "not_found";
             if (isCreate) {
                 // New document - write ID back to file
@@ -206,11 +223,61 @@ export async function executePush(dryRunResult, credentials) {
                 fs.writeFileSync(file.filePath, updatedContent, "utf-8");
                 updated++;
             }
+            // SYNC-LAND-1: every synced document gets its web URL in the result
+            synced.push({
+                fileName,
+                documentId: pushResult,
+                url: `${WEB_APP_URL}/documents/${pushResult}`,
+            });
         }
         catch (err) {
-            errors.push({ fileName, error: err.message });
+            errors.push({ fileName, error: errorDisplayMessage(err) });
+        }
+    }
+    return { created, updated, errors, importWarnings, synced };
+}
+/**
+ * Servers throw ConvexError({kind, message}) for expected failures (e.g.
+ * LIMITS-4.2's limit error); the client-side Error message embeds that data
+ * as JSON. Surface the human-readable message it carries instead of the blob.
+ */
+function errorDisplayMessage(err) {
+    const data = err.data;
+    const fromData = humanMessage(data);
+    if (fromData)
+        return fromData;
+    const message = err instanceof Error ? err.message : String(err);
+    // ConvexError messages may embed the data JSON directly or after a
+    // "ConvexError:" prefix — try the trailing {...} chunk
+    const jsonStart = message.indexOf("{");
+    if (jsonStart !== -1) {
+        try {
+            const parsed = JSON.parse(message.slice(jsonStart));
+            const fromMessage = humanMessage(parsed);
+            if (fromMessage)
+                return fromMessage;
+        }
+        catch {
+            // fall through to the raw message
+        }
+    }
+    return message;
+}
+function humanMessage(data) {
+    if (typeof data === "string") {
+        try {
+            return humanMessage(JSON.parse(data));
         }
+        catch {
+            return undefined;
+        }
+    }
+    if (data &&
+        typeof data === "object" &&
+        "message" in data &&
+        typeof data.message === "string") {
+        return data.message;
     }
-    return { created, updated, errors };
+    return undefined;
 }
 //# sourceMappingURL=core.js.map

package/dist/push/index.d.ts

@@ -4,5 +4,5 @@
  * Shared push logic for syncing local requirements files to the cloud.
  * Used by both CLI push command and MCP push_requirements tool.
  */
-export { type CloudDocumentMetadata, type ConflictInfo, type DryRunResult, type DryRunResultItem, dryRunPush, executePush, extractMarkdownContent, type FileWithDryRun, type ParsedFile, type PushCredentials, type PushResult, parseFilesForPush, } from "./core.js";
+export { type CloudDocumentMetadata, type ConflictInfo, type DryRunResult, type DryRunResultItem, dryRunPush, executePush, extractMarkdownContent, type FileWithDryRun, type ParsedFile, type PushCredentials, type PushResult, parseFilesForPush, WEB_APP_URL, } from "./core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/push/index.js

@@ -6,5 +6,5 @@
  */
 export { dryRunPush, executePush, 
 // Functions
-extractMarkdownContent, parseFilesForPush, } from "./core.js";
+extractMarkdownContent, parseFilesForPush, WEB_APP_URL, } from "./core.js";
 //# sourceMappingURL=index.js.map

package/dist/schema/parser-core.js

@@ -4,7 +4,7 @@
  * This module contains pure parsing functions with no Node.js dependencies,
  * making it safe to import in Convex runtime or browser environments.
  */
-import { ValidationError, } from "./schemas.js";
+import { ValidationError, validateKey, } from "./schemas.js";
 /**
  * Default delimiter for requirements.
  * Can be overridden for organization-specific preferences.
@@ -186,6 +186,10 @@ export function extractRequirementBlocks(body) {
             throw new ValidationError(`Invalid requirement block format - first line must be "KEY: content"`, blockContent.substring(0, 50));
         }
         const key = firstLineMatch[1];
+        // SYNC-KEY-1: reject malformed keys at parse time so push/validate fail
+        // locally instead of erroring server-side. Validation only — the original
+        // key is preserved (normalization happens downstream).
+        validateKey(key);
         blocks.push({ key, blockContent: blockContent.trim() });
         match = blockRegex.exec(body);
     }

package/dist/schema/parser.js

@@ -3,7 +3,7 @@
  */
 import * as fs from "node:fs";
 import YAML from "yaml";
-import { ValidationError, validateMetadata, } from "./schemas.js";
+import { ValidationError, validateKey, validateMetadata, } from "./schemas.js";
 const DELIMITER_PATTERN = "(?:→|->)"; // Non-capturing group for both Unicode and ASCII
 /**
  * Parse a criterion line in "position. Label → content" format.
@@ -198,6 +198,10 @@ function extractRequirementBlocks(body) {
             throw new ValidationError(`Invalid requirement block format - first line must be "KEY: content"`, blockContent.substring(0, 50));
         }
         const key = firstLineMatch[1];
+        // SYNC-KEY-1: reject malformed keys at parse time so push/validate fail
+        // locally instead of erroring server-side. Validation only — the original
+        // key is preserved (normalization happens downstream).
+        validateKey(key);
         // Try to find a heading immediately before this block for the title
         // Look backwards from the match position to find the nearest heading
         const textBeforeBlock = body.substring(0, match.index);

package/dist/schema/run-marker.d.ts

@@ -0,0 +1,38 @@
+/**
+ * CTS run markers: per-run identifiers stamped into the frontmatter of every
+ * document a codebase-to-spec run produces. At push time a valid, team-unseen
+ * marker grants `imported` authorship to the rows it creates (IMPORT-1, IMPORT-2).
+ *
+ * Format: 32 hex chars rendered in UUID layout (8-4-4-4-12).
+ *   [0..23]  random component (96 bits)
+ *   [24]     scheme version nibble
+ *   [25..31] integrity checksum: first 7 hex chars of
+ *            sha256(`${SALT}:${random}:${version}`)
+ *
+ * The checksum is an intentionality gate, not security: the salt ships in
+ * published source, so a determined forger can reproduce it. Its job is to make
+ * casual tampering ("what if I tweak this value?") fail validation, so that
+ * successful forgery requires mining the source — documented intent (see
+ * docs/working/cts-onboarding-funnel.md, abuse posture).
+ *
+ * Pure-JS SHA-256 is used (rather than node:crypto or crypto.subtle) so the
+ * same module runs identically in Node and the Convex isolate, synchronously.
+ */
+export type RunMarkerValidation = {
+    valid: true;
+    version: string;
+} | {
+    valid: false;
+    reason: "malformed" | "unsupported_version" | "checksum_mismatch";
+};
+/**
+ * Generate a new run marker (IMPORT-1.2, IMPORT-1.3).
+ */
+export declare function generateRunMarker(): string;
+/**
+ * Validate a run marker's shape and integrity (IMPORT-2.0, IMPORT-3.0).
+ * Does NOT consult the import ledger — replay checking is the caller's job.
+ */
+export declare function validateRunMarker(marker: string): RunMarkerValidation;
+export declare function sha256Hex(input: string): string;
+//# sourceMappingURL=run-marker.d.ts.map

package/dist/schema/run-marker.js

@@ -0,0 +1,138 @@
+/**
+ * CTS run markers: per-run identifiers stamped into the frontmatter of every
+ * document a codebase-to-spec run produces. At push time a valid, team-unseen
+ * marker grants `imported` authorship to the rows it creates (IMPORT-1, IMPORT-2).
+ *
+ * Format: 32 hex chars rendered in UUID layout (8-4-4-4-12).
+ *   [0..23]  random component (96 bits)
+ *   [24]     scheme version nibble
+ *   [25..31] integrity checksum: first 7 hex chars of
+ *            sha256(`${SALT}:${random}:${version}`)
+ *
+ * The checksum is an intentionality gate, not security: the salt ships in
+ * published source, so a determined forger can reproduce it. Its job is to make
+ * casual tampering ("what if I tweak this value?") fail validation, so that
+ * successful forgery requires mining the source — documented intent (see
+ * docs/working/cts-onboarding-funnel.md, abuse posture).
+ *
+ * Pure-JS SHA-256 is used (rather than node:crypto or crypto.subtle) so the
+ * same module runs identically in Node and the Convex isolate, synchronously.
+ */
+const RUN_MARKER_SALT = "dotrequirements-cts-run-marker";
+/** Current marker scheme version (single hex nibble). */
+const SCHEME_VERSION = "1";
+const HEX_32 = /^[0-9a-f]{32}$/;
+const UUID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/**
+ * Generate a new run marker (IMPORT-1.2, IMPORT-1.3).
+ */
+export function generateRunMarker() {
+    const bytes = new Uint8Array(12); // 96 bits → 24 hex chars
+    globalThis.crypto.getRandomValues(bytes);
+    const random = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+    const checksum = computeChecksum(random, SCHEME_VERSION);
+    return toUuidLayout(`${random}${SCHEME_VERSION}${checksum}`);
+}
+/**
+ * Validate a run marker's shape and integrity (IMPORT-2.0, IMPORT-3.0).
+ * Does NOT consult the import ledger — replay checking is the caller's job.
+ */
+export function validateRunMarker(marker) {
+    if (typeof marker !== "string" || !UUID_SHAPE.test(marker)) {
+        return { valid: false, reason: "malformed" };
+    }
+    const hex = marker.replaceAll("-", "");
+    if (!HEX_32.test(hex)) {
+        return { valid: false, reason: "malformed" };
+    }
+    const random = hex.slice(0, 24);
+    const version = hex.slice(24, 25);
+    const checksum = hex.slice(25);
+    if (version !== SCHEME_VERSION) {
+        // IMPORT-1.4: future schemes validate their own versions; anything we
+        // don't know is unsupported, not malformed.
+        return { valid: false, reason: "unsupported_version" };
+    }
+    if (computeChecksum(random, version) !== checksum) {
+        return { valid: false, reason: "checksum_mismatch" };
+    }
+    return { valid: true, version };
+}
+function computeChecksum(randomHex, version) {
+    return sha256Hex(`${RUN_MARKER_SALT}:${randomHex}:${version}`).slice(0, 7);
+}
+function toUuidLayout(hex32) {
+    return `${hex32.slice(0, 8)}-${hex32.slice(8, 12)}-${hex32.slice(12, 16)}-${hex32.slice(16, 20)}-${hex32.slice(20)}`;
+}
+// =============================================================================
+// Pure-JS SHA-256 (FIPS 180-4). Synchronous and runtime-independent.
+// =============================================================================
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1,
+    0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+    0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+    0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147,
+    0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+    0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
+    0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+    0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+    0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+function rotr(x, n) {
+    return (x >>> n) | (x << (32 - n));
+}
+export function sha256Hex(input) {
+    const data = new TextEncoder().encode(input);
+    const bitLen = data.length * 8;
+    // Padding: 0x80, zeros, 64-bit big-endian length
+    const padded = new Uint8Array((((data.length + 8) >> 6) << 6) + 64);
+    padded.set(data);
+    padded[data.length] = 0x80;
+    const view = new DataView(padded.buffer);
+    view.setUint32(padded.length - 4, bitLen >>> 0, false);
+    view.setUint32(padded.length - 8, Math.floor(bitLen / 0x100000000), false);
+    const h = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c,
+        0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const w = new Uint32Array(64);
+    for (let offset = 0; offset < padded.length; offset += 64) {
+        for (let i = 0; i < 16; i++) {
+            w[i] = view.getUint32(offset + i * 4, false);
+        }
+        for (let i = 16; i < 64; i++) {
+            const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >>> 3);
+            const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >>> 10);
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+        }
+        let [a, b, c, d, e, f, g, hh] = h;
+        for (let i = 0; i < 64; i++) {
+            const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+            const ch = (e & f) ^ (~e & g);
+            const temp1 = (hh + S1 + ch + K[i] + w[i]) >>> 0;
+            const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+            const maj = (a & b) ^ (a & c) ^ (b & c);
+            const temp2 = (S0 + maj) >>> 0;
+            hh = g;
+            g = f;
+            f = e;
+            e = (d + temp1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (temp1 + temp2) >>> 0;
+        }
+        h[0] = (h[0] + a) >>> 0;
+        h[1] = (h[1] + b) >>> 0;
+        h[2] = (h[2] + c) >>> 0;
+        h[3] = (h[3] + d) >>> 0;
+        h[4] = (h[4] + e) >>> 0;
+        h[5] = (h[5] + f) >>> 0;
+        h[6] = (h[6] + g) >>> 0;
+        h[7] = (h[7] + hh) >>> 0;
+    }
+    return Array.from(h, (x) => x.toString(16).padStart(8, "0")).join("");
+}
+//# sourceMappingURL=run-marker.js.map

package/dist/schema/schemas.d.ts

@@ -60,6 +60,7 @@ export declare function buildRequirementKey(prefix: string, number: number): str
 export declare const MetadataSchema: z.ZodObject<{
     version: z.ZodOptional<z.ZodNumber>;
     pulledAt: z.ZodOptional<z.ZodString>;
+    ctsRun: z.ZodOptional<z.ZodString>;
     document: z.ZodOptional<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         title: z.ZodString;
@@ -76,6 +77,7 @@ export declare const MetadataSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     version?: number | undefined;
     pulledAt?: string | undefined;
+    ctsRun?: string | undefined;
     document?: {
         title: string;
         id?: string | undefined;
@@ -84,6 +86,7 @@ export declare const MetadataSchema: z.ZodObject<{
 }, {
     version?: number | undefined;
     pulledAt?: string | undefined;
+    ctsRun?: string | undefined;
     document?: {
         title: string;
         id?: string | undefined;
@@ -146,6 +149,7 @@ export declare const RequirementsFileSchema: z.ZodObject<{
     _meta: z.ZodObject<{
         version: z.ZodOptional<z.ZodNumber>;
         pulledAt: z.ZodOptional<z.ZodString>;
+        ctsRun: z.ZodOptional<z.ZodString>;
         document: z.ZodOptional<z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
             title: z.ZodString;
@@ -162,6 +166,7 @@ export declare const RequirementsFileSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         version?: number | undefined;
         pulledAt?: string | undefined;
+        ctsRun?: string | undefined;
         document?: {
             title: string;
             id?: string | undefined;
@@ -170,6 +175,7 @@ export declare const RequirementsFileSchema: z.ZodObject<{
     }, {
         version?: number | undefined;
         pulledAt?: string | undefined;
+        ctsRun?: string | undefined;
         document?: {
             title: string;
             id?: string | undefined;
@@ -180,6 +186,7 @@ export declare const RequirementsFileSchema: z.ZodObject<{
     _meta: z.ZodObject<{
         version: z.ZodOptional<z.ZodNumber>;
         pulledAt: z.ZodOptional<z.ZodString>;
+        ctsRun: z.ZodOptional<z.ZodString>;
         document: z.ZodOptional<z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
             title: z.ZodString;
@@ -196,6 +203,7 @@ export declare const RequirementsFileSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         version?: number | undefined;
         pulledAt?: string | undefined;
+        ctsRun?: string | undefined;
         document?: {
             title: string;
             id?: string | undefined;
@@ -204,6 +212,7 @@ export declare const RequirementsFileSchema: z.ZodObject<{
     }, {
         version?: number | undefined;
         pulledAt?: string | undefined;
+        ctsRun?: string | undefined;
         document?: {
             title: string;
             id?: string | undefined;
@@ -214,6 +223,7 @@ export declare const RequirementsFileSchema: z.ZodObject<{
     _meta: z.ZodObject<{
         version: z.ZodOptional<z.ZodNumber>;
         pulledAt: z.ZodOptional<z.ZodString>;
+        ctsRun: z.ZodOptional<z.ZodString>;
         document: z.ZodOptional<z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
             title: z.ZodString;
@@ -230,6 +240,7 @@ export declare const RequirementsFileSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         version?: number | undefined;
         pulledAt?: string | undefined;
+        ctsRun?: string | undefined;
         document?: {
             title: string;
             id?: string | undefined;
@@ -238,6 +249,7 @@ export declare const RequirementsFileSchema: z.ZodObject<{
     }, {
         version?: number | undefined;
         pulledAt?: string | undefined;
+        ctsRun?: string | undefined;
         document?: {
             title: string;
             id?: string | undefined;

package/dist/schema/schemas.js

@@ -112,6 +112,7 @@ export function buildRequirementKey(prefix, number) {
 export const MetadataSchema = z.object({
     version: z.number().optional(), // Informational - incremented on push
     pulledAt: z.string().optional(), // ISO 8601 timestamp - used for conflict detection
+    ctsRun: z.string().optional(), // Run marker stamped by codebase-to-spec (IMPORT-1); grants imported authorship at document creation (IMPORT-2)
     document: z
         .object({
         id: z.string().optional(), // Cloud document link - filled by push when creating

package/dist/templates/agents/cts-worker.md

@@ -1,9 +1,9 @@
 ---
 name: cts-worker
-description: Generic worker subagent for the codebase-to-spec conversational orchestrator. Used for planner, specifier, editor, and reviewer dispatches. The per-dispatch persona is injected by the cts-worker-persona PreToolUse hook at dispatch time.
+description: Generic worker subagent for the codebase-to-spec workflow. Handles planner, outline-reviewer, specifier, reviewer, and editor dispatches. Each worker fetches its own role-specific instructions from the CLI at dispatch time.
 tools: Bash, Read, Edit, Write, Glob, Grep
 ---
 
-You are a codebase-to-spec worker. Your dispatched prompt is composed externally and supplied to you at dispatch time. It will specify your role for this dispatch (planner, specifier, editor, or reviewer), the artifacts you're working with, and the output convention you must follow.
+You are a codebase-to-spec worker. The prompt you receive tells you which CLI dispatch to fetch: it will instruct you to run `{{DOTREQ_CLI}} cts dispatch-context <dispatch-id>` (the exact invocation is given in your prompt), read the `"prompt"` field of the JSON it prints, and follow those instructions exactly.
 
-Follow the dispatched prompt exactly. Do not improvise behavior beyond what it asks. When your work is done, submit via the convention specified in the dispatch (typically a `dotrequirements cts submit` call).
+Those fetched instructions are your real task — which files to read, what to write and where, and how to validate and style-check your output via Bash. Follow them exactly and do not improvise beyond what they ask. When your prompt also asks you to return a structured result, return exactly that shape.