@popoverai/dotrequirements 0.27.0 → 0.27.2

package/README.md

@@ -32,7 +32,7 @@ pnpm add @popoverai/dotrequirements
 ### 1. Initialize a project
 
 ```bash
-npx dotreq init
+npx @popoverai/dotrequirements@latest init
 ```
 
 This creates a `.requirements/` directory with example requirements and configures your project.
@@ -111,7 +111,7 @@ dotreq init --invite abc123xyz
 If a team admin shares an invite command with you, join the team and connect in one step:
 
 ```bash
-npx dotrequirements init --invite abc123xyz
+npx @popoverai/dotrequirements@latest init --invite abc123xyz
 ```
 
 This shows the team name, prompts you to sign in, adds you to the team, and lets you select a project.
@@ -140,7 +140,7 @@ dotreq pull --share <token>
 If a team member shares a pull command with you, you can pull requirements without creating an account:
 
 ```bash
-npx @popoverai/dotrequirements pull --share drt_abc123...
+npx @popoverai/dotrequirements@latest pull --share drt_abc123...
 ```
 
 This gives you read-only access to view requirements. To push changes or report coverage, run `dotreq link` afterward.

package/dist/commands/create-requirement-document.js

@@ -1,6 +1,7 @@
 import { getProjectContext } from "../requirements/cloud-ai.js";
 import { loadAllRequirements } from "../requirements/index.js";
-import { generateStyleGuide, readLocalStyleGuide, } from "../requirements/style-guide.js";
+import { generateStyleGuide } from "../requirements/style-guide.js";
+import { readLocalStyleGuide } from "../requirements/style-guide-file.js";
 import { findProjectRoot, getProjectCredentials, } from "../utils/project-settings.js";
 const CONVEX_URL = "https://data.dotrequirements.io";
 export async function createRequirementDocumentCommand(filePath) {

package/dist/commands/link.js

@@ -262,7 +262,7 @@ async function mintShareArtifacts(client, teamId, projectId) {
         const share = (await client.mutation(api.projectSecrets.mutations.ensureShareToken, 
         // biome-ignore lint/suspicious/noExplicitAny: CLI workspace doesn't import convex's branded Id type; the runtime value is a plain string the server validates.
         { target: { type: "project", id: projectId } }));
-        artifacts.sharePullCommand = `npx -y @popoverai/dotrequirements pull --share ${share.token}`;
+        artifacts.sharePullCommand = `npx -y @popoverai/dotrequirements@latest pull --share ${share.token}`;
     }
     catch {
         // LINK-13.3: connection already succeeded — omit rather than fail

package/dist/commands/style-check.js

@@ -2,7 +2,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { DEFAULT_API_BASE_URL, fetchStyleCheckFeedback, getProjectContext, } from "../requirements/cloud-ai.js";
 import { filterRequirementsByKeys, loadAllRequirements, } from "../requirements/index.js";
-import { generateStyleGuideBody, readLocalStyleGuide, } from "../requirements/style-guide.js";
+import { generateStyleGuideBody } from "../requirements/style-guide.js";
+import { readLocalStyleGuide } from "../requirements/style-guide-file.js";
 import { findProjectRoot, getProjectCredentials, } from "../utils/project-settings.js";
 const CONVEX_URL = "https://data.dotrequirements.io";
 /**

package/dist/requirements/style-guide-file.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Filesystem access for the style guide — kept apart from the generator itself.
+ *
+ * `style-guide.ts` is imported by the web app to serve the same primer to chat
+ * agents (REMOTE-MCP-10), which have no repo to read. Everything in that module
+ * must therefore stay free of `node:fs`; the workspace lookups live here, where
+ * only the CLI reaches them. This mirrors the split the schema module already
+ * makes between its node and browser entry points.
+ */
+/**
+ * Conventional location of a project's STYLE.md, relative to the workspace
+ * root. Exported so callers (init, push/pull, tests) can reference one place.
+ */
+export declare const STYLE_MD_PATH = ".requirements/STYLE.md";
+/**
+ * Read `.requirements/STYLE.md` if the workspace has one. Returns the file
+ * contents on success, `null` if the file is absent. Empty / whitespace-only
+ * files are treated as absent so the bundled defaults still apply.
+ */
+export declare function readLocalStyleGuide(workspaceRoot: string): string | null;
+//# sourceMappingURL=style-guide-file.d.ts.map

package/dist/requirements/style-guide-file.js

@@ -0,0 +1,30 @@
+/**
+ * Filesystem access for the style guide — kept apart from the generator itself.
+ *
+ * `style-guide.ts` is imported by the web app to serve the same primer to chat
+ * agents (REMOTE-MCP-10), which have no repo to read. Everything in that module
+ * must therefore stay free of `node:fs`; the workspace lookups live here, where
+ * only the CLI reaches them. This mirrors the split the schema module already
+ * makes between its node and browser entry points.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Conventional location of a project's STYLE.md, relative to the workspace
+ * root. Exported so callers (init, push/pull, tests) can reference one place.
+ */
+export const STYLE_MD_PATH = ".requirements/STYLE.md";
+/**
+ * Read `.requirements/STYLE.md` if the workspace has one. Returns the file
+ * contents on success, `null` if the file is absent. Empty / whitespace-only
+ * files are treated as absent so the bundled defaults still apply.
+ */
+export function readLocalStyleGuide(workspaceRoot) {
+    const fullPath = join(workspaceRoot, STYLE_MD_PATH);
+    if (!existsSync(fullPath)) {
+        return null;
+    }
+    const contents = readFileSync(fullPath, "utf-8");
+    return contents.trim().length > 0 ? contents : null;
+}
+//# sourceMappingURL=style-guide-file.js.map

package/dist/requirements/style-guide.d.ts

@@ -11,37 +11,35 @@
  *
  * If the project has a `.requirements/STYLE.md`, callers can pass its
  * contents via `localStyleGuide` to use that body in place of the bundled
- * defaults. See {@link readLocalStyleGuide} for the lookup helper.
+ * defaults. See `readLocalStyleGuide` in ./style-guide-file.ts (CLI-only —
+ * this module stays free of node:fs so the web can serve the same primer).
  */
 import type { FlattenedRequirement } from "./index.js";
 /**
- * Conventional location of a project's STYLE.md, relative to the workspace
- * root. Exported so callers (init, push/pull, tests) can reference one place.
+ * The only fields the guide reads off a requirement.
+ *
+ * Deliberately narrower than {@link FlattenedRequirement}, which is file-shaped
+ * (`sourceFile`, `documentTitle`). The web serves this same guide from cloud
+ * requirements, which have no file to name (REMOTE-MCP-10) — asking only for
+ * what's used lets both callers pass what they actually have instead of
+ * inventing filenames.
  */
-export declare const STYLE_MD_PATH = ".requirements/STYLE.md";
+export type StyleGuideRequirement = Pick<FlattenedRequirement, "id" | "label" | "path">;
 export interface GenerateStyleGuideParams {
-    /** Flattened view of the workspace's existing requirements, used to
-     * surface label patterns and key-prefix patterns in the output. Pass
-     * an empty array when no requirements exist yet. */
-    requirements: FlattenedRequirement[];
-    /** Project-owner-supplied custom guidance (currently sourced from the
-     * cloud project's `requirementsStyleContext` field). Pass null/undefined
-     * to omit. */
+    /** The existing requirements to discover label and key-prefix patterns from.
+     * Pass an empty array when none exist yet. */
+    requirements: StyleGuideRequirement[];
+    /** Project-owner-supplied custom guidance (sourced from the cloud project's
+     * `requirementsStyleContext` field). Pass null/undefined to omit. */
     customStyleGuidance?: string | null;
-    /** Suggested target path for the new file. Used only in the preamble
-     * and "Next Steps" section. Defaults to a generic example path. */
+    /** Suggested target path for the new file. Used only in the preamble and
+     * "Next Steps" section. Defaults to a generic example path. */
     filePath?: string;
-    /** Project-local STYLE.md contents. When provided and non-empty, this
-     * body replaces the bundled default; callers can fetch it via
-     * {@link readLocalStyleGuide}. */
+    /** Project-local STYLE.md contents. When provided and non-empty, this body
+     * replaces the bundled default. CLI-only — see `readLocalStyleGuide` in
+     * ./style-guide-file.ts. */
     localStyleGuide?: string | null;
 }
-/**
- * Read `.requirements/STYLE.md` if the workspace has one. Returns the file
- * contents on success, `null` if the file is absent. Empty / whitespace-only
- * files are treated as absent so the bundled defaults still apply.
- */
-export declare function readLocalStyleGuide(workspaceRoot: string): string | null;
 /**
  * Build the body of the bundled default style guide. This is the content
  * that lives inside the "# Requirements File Template" preamble — the

package/dist/requirements/style-guide.js

@@ -11,27 +11,47 @@
  *
  * If the project has a `.requirements/STYLE.md`, callers can pass its
  * contents via `localStyleGuide` to use that body in place of the bundled
- * defaults. See {@link readLocalStyleGuide} for the lookup helper.
+ * defaults. See `readLocalStyleGuide` in ./style-guide-file.ts (CLI-only —
+ * this module stays free of node:fs so the web can serve the same primer).
  */
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { ROOT_LABEL_MARKER } from "../schema/parser-core.js";
 /**
- * Conventional location of a project's STYLE.md, relative to the workspace
- * root. Exported so callers (init, push/pull, tests) can reference one place.
+ * How many discovered labels or key prefixes the guide will show.
+ *
+ * These lists exist under "match the existing pattern", and past ten that
+ * instruction stops being actionable — a reader can't match a hundred and forty
+ * things. Worse, an uncapped list presents whatever sprawl a codebase has
+ * accumulated as the house style, so each new author reproduces it and the list
+ * grows: the mechanism meant to hold conventions steady is what compounds their
+ * drift. Ten is a sample, and the trailing count says so rather than letting the
+ * truncation read as the whole set.
  */
-export const STYLE_MD_PATH = ".requirements/STYLE.md";
+const SAMPLE_LIMIT = 10;
 /**
- * Read `.requirements/STYLE.md` if the workspace has one. Returns the file
- * contents on success, `null` if the file is absent. Empty / whitespace-only
- * files are treated as absent so the bundled defaults still apply.
+ * The most-used values first, not the alphabetically-first.
+ *
+ * Sorting by name and taking the head is a trap: on this codebase it yields ten
+ * prefixes all beginning with "A", which under "match the existing pattern"
+ * teaches a convention nobody has. Frequency is what the phrase actually means —
+ * the prefixes carrying the most requirements are the house style. Ties break
+ * alphabetically so the sample is stable across runs.
  */
-export function readLocalStyleGuide(workspaceRoot) {
-    const fullPath = join(workspaceRoot, STYLE_MD_PATH);
-    if (!existsSync(fullPath)) {
-        return null;
-    }
-    const contents = readFileSync(fullPath, "utf-8");
-    return contents.trim().length > 0 ? contents : null;
+function sample(counts) {
+    const ranked = Array.from(counts.entries())
+        .sort(([aName, aCount], [bName, bCount]) => bCount === aCount ? aName.localeCompare(bName) : bCount - aCount)
+        .map(([name]) => name);
+    return {
+        list: ranked
+            .slice(0, SAMPLE_LIMIT)
+            .map((v) => `"${v}"`)
+            .join(", "),
+        more: ranked.length > SAMPLE_LIMIT
+            ? ` (and ${ranked.length - SAMPLE_LIMIT} more)`
+            : "",
+    };
+}
+function tally(counts, key) {
+    counts.set(key, (counts.get(key) ?? 0) + 1);
 }
 /**
  * Build the body of the bundled default style guide. This is the content
@@ -46,43 +66,45 @@ export function readLocalStyleGuide(workspaceRoot) {
  */
 export function generateStyleGuideBody(params) {
     const { requirements, customStyleGuidance } = params;
-    const labels = new Set();
-    const keyPrefixes = new Set();
+    const labels = new Map();
+    const keyPrefixes = new Map();
     for (const req of requirements) {
-        if (req.label?.trim()) {
-            labels.add(req.label);
+        // The root marker is on every root in every workspace and chosen by nobody,
+        // so counting it would hand back a storage detail as house style. Worst for
+        // a project that took this guide's own advice to leave criteria unlabelled:
+        // it would be the only label found, and would suppress the "default to
+        // unlabeled" branch below in favour of matching a label nobody types.
+        if (req.label?.trim() && req.label !== ROOT_LABEL_MARKER) {
+            tally(labels, req.label);
         }
         if (req.path.length === 0 && req.id) {
             const lastDashIndex = req.id.lastIndexOf("-");
             if (lastDashIndex > 0) {
-                keyPrefixes.add(req.id.substring(0, lastDashIndex));
+                tally(keyPrefixes, req.id.substring(0, lastDashIndex));
             }
         }
     }
-    const discoveredLabels = Array.from(labels).sort();
-    const discoveredPrefixes = Array.from(keyPrefixes).sort();
     let labelGuidance;
-    if (discoveredLabels.length > 0) {
-        const labelList = discoveredLabels
-            .slice(0, 10)
-            .map((l) => `"${l}"`)
-            .join(", ");
-        const more = discoveredLabels.length > 10
-            ? ` (and ${discoveredLabels.length - 10} more)`
-            : "";
+    if (labels.size > 0) {
+        const { list: labelList, more } = sample(labels);
         labelGuidance = `**Existing labels in this codebase:** ${labelList}${more}
 
 **Use these existing labels** to maintain consistency. If you're unsure which labels to use for a new requirement, ask the user.`;
     }
     else {
-        labelGuidance = `**No existing requirements found in this codebase.**
+        // Says *labels*, not requirements. Reaching here means nobody has labelled
+        // a criterion — which is what a project following the advice below looks
+        // like, not an empty one. The key-prefix branch shares this sentence and is
+        // right to: there, an empty set really does mean no requirements. Here it
+        // would contradict the prefix list printed two headings above.
+        labelGuidance = `**No labelled criteria found in this codebase.**
 
 **Default to unlabeled requirements** (\`0. → content\`). If the user wants labels, ask them which format they prefer. Do not choose an opinionated framework like Given/When/Then without explicit user consent.`;
     }
     let keyGuidance;
-    if (discoveredPrefixes.length > 0) {
-        const prefixList = discoveredPrefixes.map((p) => `"${p}"`).join(", ");
-        keyGuidance = `**Existing requirement key prefixes in this codebase:** ${prefixList}
+    if (keyPrefixes.size > 0) {
+        const { list: prefixList, more } = sample(keyPrefixes);
+        keyGuidance = `**Existing requirement key prefixes in this codebase:** ${prefixList}${more}
 
 **Match the existing pattern** when creating new requirement keys. Use the same domain prefixes and sequential numbering style.`;
     }

package/dist/schema/browser.d.ts

@@ -6,7 +6,7 @@
 export { buildRequirementMarkdown, buildRequirementsMarkdown, DEFAULT_DELIMITER, } from "./builder.js";
 export type { ConvexRequirement } from "./conversions.js";
 export { buildMetadata, constructKey, convexToRequirements, extractRequirementKeys, groupByRoot, parseKey, requirementsToConvex, } from "./conversions.js";
-export { DELIMITER_PATTERN, extractRequirementBlocks, findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementBlocksFromMarkdown, parseRootLine, } from "./parser-core.js";
+export { DELIMITER_PATTERN, extractRequirementBlocks, findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementBlocksFromMarkdown, parseRootLine, ROOT_LABEL_MARKER, } from "./parser-core.js";
 export type { Metadata, ParsedCriterion, RequirementKey, RequirementNode, RequirementPrefix, RequirementsFile, } from "./schemas.js";
 export { buildRequirementKey, MetadataSchema, normalizePrefix, ParsedCriterionSchema, parseRequirementKey, REQUIREMENT_KEY_PATTERN, REQUIREMENT_PREFIX_PATTERN, RequirementKeySchema, RequirementNodeSchema, RequirementPrefixSchema, RequirementsFileSchema, ValidationError, validateKey, validateMetadata, validatePrefix, validateRequirementNode, validateRequirementsFile, } from "./schemas.js";
 export type { BuildScenarioOptions, Scenario, ScenarioAssertionSource, ScenarioStep, } from "./scenario.js";

package/dist/schema/browser.js

@@ -8,7 +8,10 @@ export { buildRequirementMarkdown, buildRequirementsMarkdown, DEFAULT_DELIMITER,
 export { buildMetadata, constructKey, convexToRequirements, extractRequirementKeys, groupByRoot, parseKey, requirementsToConvex, } from "./conversions.js";
 // Parser core (pure TypeScript - browser-safe, no fs dependency)
 // These functions parse markdown strings directly without file I/O
-export { DELIMITER_PATTERN, extractRequirementBlocks, findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementBlocksFromMarkdown, parseRootLine, } from "./parser-core.js";
+export { DELIMITER_PATTERN, extractRequirementBlocks, findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementBlocksFromMarkdown, parseRootLine, 
+// The web reaches parser-core only through this entry point, so without this
+// its readers have no way to import the marker and must hard-code it.
+ROOT_LABEL_MARKER, } from "./parser-core.js";
 // Schemas and types (uses zod - browser-safe)
 export { buildRequirementKey, 
 // Zod schemas

package/dist/schema/index.d.ts

@@ -7,7 +7,7 @@
 export { buildRequirementMarkdown, buildRequirementsFile, buildRequirementsMarkdown, } from "./builder.js";
 export type { ConvexRequirement } from "./conversions.js";
 export { buildMetadata, constructKey, convexToRequirements, extractRequirementKeys, groupByRoot, parseKey, requirementsToConvex, } from "./conversions.js";
-export { findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementsFile, parseRequirementsFromFile, } from "./parser.js";
+export { findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementsFile, parseRequirementsFromFile, parseRootLine, } from "./parser.js";
 export { checkPathAmbiguity, findChildrenByLabel, getAllLabelPaths, parsePathSegment, parseRequirementPath, resolvePathSegment, resolveRequirementPath, resolveToNumericPath, } from "./resolver.js";
 export type { BuildScenarioOptions, Scenario, ScenarioAssertionSource, ScenarioStep, } from "./scenario.js";
 export { buildScenarioFromRequirements, requirementTreeToScenario, } from "./scenario.js";

package/dist/schema/index.js

@@ -8,7 +8,7 @@
 export { buildRequirementMarkdown, buildRequirementsFile, buildRequirementsMarkdown, } from "./builder.js";
 export { buildMetadata, constructKey, convexToRequirements, extractRequirementKeys, groupByRoot, parseKey, requirementsToConvex, } from "./conversions.js";
 // Parsing
-export { findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementsFile, parseRequirementsFromFile, } from "./parser.js";
+export { findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementsFile, parseRequirementsFromFile, parseRootLine, } from "./parser.js";
 // Path resolution
 export { checkPathAmbiguity, findChildrenByLabel, getAllLabelPaths, parsePathSegment, parseRequirementPath, resolvePathSegment, resolveRequirementPath, resolveToNumericPath, } from "./resolver.js";
 // Scenario building (for browser-automation / runScenario)

package/dist/schema/parser-core.d.ts

@@ -5,6 +5,21 @@
  * making it safe to import in Convex runtime or browser environments.
  */
 import { type ParsedCriterion, type RequirementNode } from "./schemas.js";
+/**
+ * The label stamped on every requirement's root, for indexing and querying.
+ *
+ * An internal marker, not a convention: no author writes it, the markdown
+ * format has no syntax for it, and consumers that show labels to a human or an
+ * agent must exclude it — the harness's output filters, Convex's label queries,
+ * and the style guide's discovered-label list all do.
+ *
+ * Declared here because this is where parsing stamps it, but be warned: most of
+ * those readers still hard-code the literal, and `web/lib/markdown-conversion`
+ * stamps it independently for the BlockNote path. So renaming this does NOT yet
+ * move everyone with it — you would have to grep. Each reader migrated here is
+ * one that a rename can no longer silently strand.
+ */
+export declare const ROOT_LABEL_MARKER = "requirementHeader";
 /**
  * Default delimiter for requirements.
  * Can be overridden for organization-specific preferences.

package/dist/schema/parser-core.js

@@ -5,6 +5,21 @@
  * making it safe to import in Convex runtime or browser environments.
  */
 import { ValidationError, validateKey, } from "./schemas.js";
+/**
+ * The label stamped on every requirement's root, for indexing and querying.
+ *
+ * An internal marker, not a convention: no author writes it, the markdown
+ * format has no syntax for it, and consumers that show labels to a human or an
+ * agent must exclude it — the harness's output filters, Convex's label queries,
+ * and the style guide's discovered-label list all do.
+ *
+ * Declared here because this is where parsing stamps it, but be warned: most of
+ * those readers still hard-code the literal, and `web/lib/markdown-conversion`
+ * stamps it independently for the BlockNote path. So renaming this does NOT yet
+ * move everyone with it — you would have to grep. Each reader migrated here is
+ * one that a rename can no longer silently strand.
+ */
+export const ROOT_LABEL_MARKER = "requirementHeader";
 /**
  * Default delimiter for requirements.
  * Can be overridden for organization-specific preferences.
@@ -103,9 +118,9 @@ export function parseRequirementBlock(key, blockContent) {
     }
     const root = {
         id: key,
-        // Root requirements always use "requirementHeader" label for indexing/querying
-        // The markdown format doesn't preserve root labels, but we standardize on this value
-        label: "requirementHeader",
+        // Root requirements always use this label for indexing/querying. The
+        // markdown format doesn't preserve root labels, so we standardize on it.
+        label: ROOT_LABEL_MARKER,
         content: rootParsed.content,
         children: [],
     };

package/dist/schema/parser.d.ts

@@ -8,7 +8,7 @@
  * requirements file means (SYNC-FORMAT-2.3).
  */
 import { type RequirementNode, type RequirementsFile } from "./schemas.js";
-export { findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, } from "./parser-core.js";
+export { findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRootLine, } from "./parser-core.js";
 /**
  * Parse a complete requirements Markdown file.
  */

package/dist/schema/parser.js

@@ -13,7 +13,7 @@ import { parseRequirementBlocksFromMarkdown, splitFrontmatter, } from "./parser-
 import { ValidationError, validateMetadata, } from "./schemas.js";
 // Block/criterion parsing and tree utilities live in parser-core; re-exported
 // here so the schema module's public surface is unchanged.
-export { findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, } from "./parser-core.js";
+export { findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRootLine, } from "./parser-core.js";
 /**
  * Extract YAML frontmatter from Markdown content.
  * Returns { frontmatter, body } where frontmatter is the parsed YAML object.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.27.0",
+  "version": "0.27.2",
   "description": "Requirements tracking CLI and test harness",
   "type": "module",
   "bin": {
@@ -11,7 +11,8 @@
     ".": "./dist/cli.js",
     "./test": "./dist/harness/index.js",
     "./schema": "./dist/schema/index.js",
-    "./schema/browser": "./dist/schema/browser.js"
+    "./schema/browser": "./dist/schema/browser.js",
+    "./style-guide": "./dist/requirements/style-guide.js"
   },
   "publishConfig": {
     "access": "public"