@popoverai/dotrequirements 0.11.0

package/dist/templates/claude-code-overview-skill.md

@@ -0,0 +1,6 @@
+---
+name: dotreq-overview
+description: Use this to understand what the system is supposed to do. ALWAYS use it when exploring expected behavior.
+---
+
+{{OVERVIEW_CORE}}

package/dist/templates/claude-code-skill.md

@@ -0,0 +1,6 @@
+---
+name: dotreq-requirements
+description: Use this when adding new expected behavior to the system. ALWAYS use it when implementing new functionality.
+---
+
+{{BEHAVIORAL_CORE}}

package/dist/templates/claude-code-test-skill.md

@@ -0,0 +1,6 @@
+---
+name: dotreq-tests
+description: Use this when validating expected behavior. ALWAYS use it when writing tests.
+---
+
+{{TEST_WRITING_CORE}}

package/dist/templates/codex-agents.md

@@ -0,0 +1,3 @@
+<!-- BEGIN dotreq-requirements -->
+{{BEHAVIORAL_CORE}}
+<!-- END dotreq-requirements -->

package/dist/templates/codex-overview-agents.md

@@ -0,0 +1,3 @@
+<!-- BEGIN dotreq-overview -->
+{{OVERVIEW_CORE}}
+<!-- END dotreq-overview -->

package/dist/templates/codex-test-agents.md

@@ -0,0 +1,3 @@
+<!-- BEGIN dotreq-tests -->
+{{TEST_WRITING_CORE}}
+<!-- END dotreq-tests -->

package/dist/templates/cursor-overview-rule.mdc

@@ -0,0 +1,5 @@
+---
+description: Use this to understand what the system is supposed to do. ALWAYS use it when exploring expected behavior.
+---
+
+{{OVERVIEW_CORE}}

package/dist/templates/cursor-rule.mdc

@@ -0,0 +1,5 @@
+---
+description: Use this when adding new expected behavior to the system. ALWAYS use it when implementing new functionality.
+---
+
+{{BEHAVIORAL_CORE}}

package/dist/templates/cursor-test-rule.mdc

@@ -0,0 +1,5 @@
+---
+description: Use this when validating expected behavior. ALWAYS use it when writing tests.
+---
+
+{{TEST_WRITING_CORE}}

package/dist/templates/example-requirements.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Template for example.requirements.md
+ *
+ * This template is used for both local-only and authenticated init flows.
+ * It demonstrates the dotrequirements markdown format with nested requirements.
+ */
+export declare function generateExampleRequirements(projectId?: string): string;
+//# sourceMappingURL=example-requirements.d.ts.map

package/dist/templates/example-requirements.js

@@ -0,0 +1,88 @@
+/**
+ * Template for example.requirements.md
+ *
+ * This template is used for both local-only and authenticated init flows.
+ * It demonstrates the dotrequirements markdown format with nested requirements.
+ */
+export function generateExampleRequirements(projectId = 'local') {
+    const now = new Date().toISOString();
+    return `---
+projectId: ${projectId}
+pulledAt: ${now}
+version: 1
+document:
+  title: "Example Requirements"
+---
+
+# Example Requirements
+
+This file demonstrates the dotrequirements format. Feel free to edit or delete it.
+
+## HOW-TO: How to use dotrequirements
+
+\`\`\`dotrequirements
+HOW-TO: How to use dotrequirements
+  0. → Requirements live here and are referenced by index, like requirement('HOW-TO.0')
+  1. Labels → Anything before the arrow is a label. You can reference a requirement by its index or its label: requirement('HOW-TO.1') == requirement('HOW-TO.labels')
+  2. Labels → Repeated labels can be referenced sequentially: requirement('HOW-TO.labels#2')
+    2.0. Nesting → You can keep nesting. Label references don't need to be nested: requirement('HOW-TO.nesting').
+    2.1. Several words → Reference multi-word labels using kebab-case. Label references are never case sensitive: requirement('HOW-TO.several-words')
+  3. → While you _can_ write your requirements longhand in this format, there are a number of better ways.
+    3.0. MCP → The dotrequirements MCP equips an AI assistant to develop requirements with you
+    3.1. Your current tools → Dotrequirements has a composer for Jira, Confluence, and Notion
+    3.2. Our composer → You can use our requirements composer at app.dotrequirements.io
+  4. Have fun → Especially in the time you get back from having a more stable, transparent, and AI-friendly codebase
+\`\`\`
+
+---
+
+## USER-AUTH: User authentication flow
+
+**Implementation notes:** Use bcrypt for password hashing with work factor >= 12.
+
+\`\`\`dotrequirements
+USER-AUTH: User authentication flow
+  0. AC → Login form accepts email and password
+  1. AC → Invalid credentials show error message
+  2. Edge-case → Rate limiting after 5 failed attempts
+    2.0. Requirement → Lock account for 15 minutes
+    2.1. Requirement → Display countdown timer to user
+\`\`\`
+
+---
+
+## PERF-1: API endpoints respond within acceptable time limits
+
+\`\`\`dotrequirements
+PERF-1: API endpoints respond within acceptable time limits
+  0. Benchmark → Tested with 1000 concurrent users
+  1. Requirement → p95 latency under 200ms
+  2. Requirement → p99 latency under 500ms
+\`\`\`
+
+---
+
+## Referencing in Tests
+
+You can reference these requirements in your tests:
+
+\`\`\`javascript
+import { requirement } from '@popoverai/dotrequirements/test';
+
+test('login with valid credentials', () => {
+  // Reference by numeric path
+  const ac = requirement('USER-AUTH.0');
+  // Returns: "AC: Login form accepts email and password"
+
+  // Reference by label
+  const edgeCase = requirement('USER-AUTH.edge-case');
+  // Returns: "Edge-case: Rate limiting after 5 failed attempts"
+
+  // Your test implementation...
+});
+\`\`\`
+
+See the [test harness documentation](https://docs.dotrequirements.io/harness) for more details.
+`;
+}
+//# sourceMappingURL=example-requirements.js.map

package/dist/templates/example-requirements.ts

@@ -0,0 +1,88 @@
+/**
+ * Template for example.requirements.md
+ *
+ * This template is used for both local-only and authenticated init flows.
+ * It demonstrates the dotrequirements markdown format with nested requirements.
+ */
+export function generateExampleRequirements(projectId: string = 'local'): string {
+  const now = new Date().toISOString();
+
+  return `---
+projectId: ${projectId}
+pulledAt: ${now}
+version: 1
+document:
+  title: "Example Requirements"
+---
+
+# Example Requirements
+
+This file demonstrates the dotrequirements format. Feel free to edit or delete it.
+
+## HOW-TO: How to use dotrequirements
+
+\`\`\`dotrequirements
+HOW-TO: How to use dotrequirements
+  0. → Requirements live here and are referenced by index, like requirement('HOW-TO.0')
+  1. Labels → Anything before the arrow is a label. You can reference a requirement by its index or its label: requirement('HOW-TO.1') == requirement('HOW-TO.labels')
+  2. Labels → Repeated labels can be referenced sequentially: requirement('HOW-TO.labels#2')
+    2.0. Nesting → You can keep nesting. Label references don't need to be nested: requirement('HOW-TO.nesting').
+    2.1. Several words → Reference multi-word labels using kebab-case. Label references are never case sensitive: requirement('HOW-TO.several-words')
+  3. → While you _can_ write your requirements longhand in this format, there are a number of better ways.
+    3.0. MCP → The dotrequirements MCP equips an AI assistant to develop requirements with you
+    3.1. Your current tools → Dotrequirements has a composer for Jira, Confluence, and Notion
+    3.2. Our composer → You can use our requirements composer at app.dotrequirements.io
+  4. Have fun → Especially in the time you get back from having a more stable, transparent, and AI-friendly codebase
+\`\`\`
+
+---
+
+## USER-AUTH: User authentication flow
+
+**Implementation notes:** Use bcrypt for password hashing with work factor >= 12.
+
+\`\`\`dotrequirements
+USER-AUTH: User authentication flow
+  0. AC → Login form accepts email and password
+  1. AC → Invalid credentials show error message
+  2. Edge-case → Rate limiting after 5 failed attempts
+    2.0. Requirement → Lock account for 15 minutes
+    2.1. Requirement → Display countdown timer to user
+\`\`\`
+
+---
+
+## PERF-1: API endpoints respond within acceptable time limits
+
+\`\`\`dotrequirements
+PERF-1: API endpoints respond within acceptable time limits
+  0. Benchmark → Tested with 1000 concurrent users
+  1. Requirement → p95 latency under 200ms
+  2. Requirement → p99 latency under 500ms
+\`\`\`
+
+---
+
+## Referencing in Tests
+
+You can reference these requirements in your tests:
+
+\`\`\`javascript
+import { requirement } from '@popoverai/dotrequirements/test';
+
+test('login with valid credentials', () => {
+  // Reference by numeric path
+  const ac = requirement('USER-AUTH.0');
+  // Returns: "AC: Login form accepts email and password"
+
+  // Reference by label
+  const edgeCase = requirement('USER-AUTH.edge-case');
+  // Returns: "Edge-case: Rate limiting after 5 failed attempts"
+
+  // Your test implementation...
+});
+\`\`\`
+
+See the [test harness documentation](https://docs.dotrequirements.io/harness) for more details.
+`;
+}

package/dist/templates/overview-core.md

@@ -0,0 +1,27 @@
+# Understanding Expected Behavior
+
+ALWAYS use this when you want to understand what the system is supposed to do.
+
+## Where to Find Expected Behavior
+
+This project uses **requirements as the source of truth** for expected behavior.
+
+**Location:** `.requirements/` directory contains `*.requirements.md` files
+
+**Format:** Requirements are structured as:
+- Requirement IDs (e.g., `AUTH-1`, `LOGIN-2`)
+- Descriptions of expected behavior
+- Hierarchical structure (parent requirements with child criteria)
+
+## MCP Tools for Exploration
+
+- `list_all_requirements` - Get overview of all requirements in the project
+- `get_requirement` - Get detailed requirement tree with test coverage
+- `search_requirements` - Search by text/regex across all requirements
+- `get_requirements_by_test` - See what a test file validates
+
+## Next Steps
+
+Once you understand the expected behavior:
+- **Adding new behavior?** Use the `dotreq-requirements` skill
+- **Writing tests?** Use the `dotreq-tests` skill

package/dist/templates/requirements-readme.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Template for .requirements/README.md
+ */
+export declare function generateRequirementsReadme(): string;
+//# sourceMappingURL=requirements-readme.d.ts.map

package/dist/templates/requirements-readme.js

@@ -0,0 +1,31 @@
+/**
+ * Template for .requirements/README.md
+ */
+export function generateRequirementsReadme() {
+    return `# Requirements
+
+This directory contains requirements for the project. Requirements can be:
+- Hand-authored locally in Markdown files
+- Generated via \`dotrequirements pull\` from dot•requirements cloud
+- Synced bidirectionally with \`dotrequirements push\`
+
+## File Format
+
+Requirements use the \`*.requirements.md\` naming pattern. See the [Markdown Schema](https://docs.dotrequirements.io/schema) for format details.
+
+## Getting Started
+
+1. Edit \`example.requirements.md\` or create new \`*.requirements.md\` files
+2. Reference requirements in tests using the test harness
+3. Run tests to track coverage
+
+## Commands
+
+- \`dotrequirements pull\` - Sync requirements from cloud
+- \`dotrequirements push\` - Push local requirements to cloud
+- \`dotrequirements test\` - Validate requirement files
+
+Learn more: https://dotrequirements.io
+`;
+}
+//# sourceMappingURL=requirements-readme.js.map

package/dist/templates/requirements-readme.ts

@@ -0,0 +1,30 @@
+/**
+ * Template for .requirements/README.md
+ */
+export function generateRequirementsReadme(): string {
+  return `# Requirements
+
+This directory contains requirements for the project. Requirements can be:
+- Hand-authored locally in Markdown files
+- Generated via \`dotrequirements pull\` from dot•requirements cloud
+- Synced bidirectionally with \`dotrequirements push\`
+
+## File Format
+
+Requirements use the \`*.requirements.md\` naming pattern. See the [Markdown Schema](https://docs.dotrequirements.io/schema) for format details.
+
+## Getting Started
+
+1. Edit \`example.requirements.md\` or create new \`*.requirements.md\` files
+2. Reference requirements in tests using the test harness
+3. Run tests to track coverage
+
+## Commands
+
+- \`dotrequirements pull\` - Sync requirements from cloud
+- \`dotrequirements push\` - Push local requirements to cloud
+- \`dotrequirements test\` - Validate requirement files
+
+Learn more: https://dotrequirements.io
+`;
+}

package/dist/templates/test-writing-core.md

@@ -0,0 +1,72 @@
+# Test Writing with Requirements
+
+ALWAYS use this guidance when writing tests based on requirements.
+
+## Core Principle
+
+Use `requirement()` AS the test description, not in the body or comments.
+
+```typescript
+// ✅ Good
+test(requirement('AUTH-1'), () => { /* test */ });
+
+// ❌ Bad
+test("user can log in", () => { requirement('AUTH-1'); });
+```
+
+## Test Structure
+
+**Match the requirement hierarchy:**
+
+For structured requirements, nest describe/it blocks:
+
+```typescript
+describe(requirement('LOGIN-1'), () => {
+  describe(requirement('LOGIN-1.given'), () => {
+    // Arrange
+  });
+  describe(requirement('LOGIN-1.when'), () => {
+    // Act
+    it(requirement('LOGIN-1.then'), () => {
+      // Assert
+    });
+  });
+});
+```
+
+For simple requirements, use a single test block.
+
+## Comments
+
+Comments should describe the TEST implementation, not copy the requirement text verbatim.
+
+**NEVER document coverage in comments.** Our MCP tools track coverage automatically.
+
+```typescript
+// ❌ Bad - creates second source of truth
+/**
+ * Requirements coverage:
+ * - AUTH-9.0: Backend creates project ✓
+ * - AUTH-9.1: CLI writes to .env.local ✓
+ */
+
+// ✅ Good - use MCP tools instead
+// Use get_requirement, get_requirements_by_test to see coverage
+```
+
+## Workflow
+
+After writing tests:
+
+1. Run tests to ensure they don't throw errors
+2. **ALWAYS run `review_test`** on the test file to validate tests actually check what requirements specify
+3. Fix any issues identified by the review
+
+## MCP Tools for Test Writing
+
+- `get_requirement` - Get requirement tree with existing coverage
+- `get_requirements_by_test` - See requirements referenced in a test file
+- `list_untested_requirements` - Find requirements without tests
+- `review_test` - Validate test actually checks what requirement specifies (run after writing tests)
+
+Note: Users can also explicitly trigger this workflow with `/write-tests`.

package/dist/utils/brand.d.ts

@@ -0,0 +1,5 @@
+/** Branded name for terminal output (colored bullet) */
+export declare const brand: string;
+/** Branded name for plain text (MCP descriptions, etc) */
+export declare const brandPlain = "dot\u2022requirements";
+//# sourceMappingURL=brand.d.ts.map

package/dist/utils/brand.js

@@ -0,0 +1,8 @@
+import chalk from 'chalk';
+// Cyan color: rgb(8, 145, 178)
+const bulletColor = chalk.rgb(8, 145, 178);
+/** Branded name for terminal output (colored bullet) */
+export const brand = `dot${bulletColor('•')}requirements`;
+/** Branded name for plain text (MCP descriptions, etc) */
+export const brandPlain = 'dot•requirements';
+//# sourceMappingURL=brand.js.map

package/dist/utils/browser-launch.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cross-platform browser launching utility for OAuth flows.
+ *
+ * Implements AUTH-23: Browser launch utility for OAuth flow
+ *
+ * Uses the `open` npm package for secure, cross-platform browser launching
+ * without shell command injection vulnerabilities.
+ */
+/**
+ * Open a URL in the user's default browser
+ *
+ * Works cross-platform (macOS, Windows, Linux)
+ */
+export declare function openBrowser(url: string): Promise<void>;
+/**
+ * Open browser with fallback instructions if automatic launch fails
+ */
+export declare function openBrowserWithFallback(url: string): Promise<void>;
+//# sourceMappingURL=browser-launch.d.ts.map

package/dist/utils/browser-launch.js

@@ -0,0 +1,36 @@
+/**
+ * Cross-platform browser launching utility for OAuth flows.
+ *
+ * Implements AUTH-23: Browser launch utility for OAuth flow
+ *
+ * Uses the `open` npm package for secure, cross-platform browser launching
+ * without shell command injection vulnerabilities.
+ */
+import open from 'open';
+/**
+ * Open a URL in the user's default browser
+ *
+ * Works cross-platform (macOS, Windows, Linux)
+ */
+export async function openBrowser(url) {
+    try {
+        await open(url);
+    }
+    catch (error) {
+        throw new Error(`Failed to open browser: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Open browser with fallback instructions if automatic launch fails
+ */
+export async function openBrowserWithFallback(url) {
+    try {
+        await openBrowser(url);
+        console.log('Opening browser for authentication...');
+    }
+    catch (error) {
+        console.error('Could not automatically open browser.');
+        console.log(`\nPlease open this URL in your browser manually:\n${url}\n`);
+    }
+}
+//# sourceMappingURL=browser-launch.js.map

package/dist/utils/detect-existing-project.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Detect if .requirements/ directory exists and extract projectId from files
+ */
+export declare function detectExistingProject(cwd: string): string | null;
+//# sourceMappingURL=detect-existing-project.d.ts.map

package/dist/utils/detect-existing-project.js

@@ -0,0 +1,34 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseRequirementsFromFile } from '../schema/index.js';
+/**
+ * Detect if .requirements/ directory exists and extract projectId from files
+ */
+export function detectExistingProject(cwd) {
+    const requirementsDir = path.join(cwd, '.requirements');
+    if (!fs.existsSync(requirementsDir)) {
+        return null;
+    }
+    // Look for .requirements.md files
+    const files = fs.readdirSync(requirementsDir)
+        .filter(f => f.endsWith('.requirements.md'));
+    if (files.length === 0) {
+        return null;
+    }
+    // Try to parse first file to get projectId
+    for (const file of files) {
+        try {
+            const filePath = path.join(requirementsDir, file);
+            const parsed = parseRequirementsFromFile(filePath);
+            if (parsed.metadata.projectId) {
+                return parsed.metadata.projectId;
+            }
+        }
+        catch (error) {
+            // Skip files that can't be parsed
+            continue;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=detect-existing-project.js.map

package/dist/utils/env.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Load environment variables from .env.local file
+ * Merges with existing process.env (process.env takes precedence)
+ */
+export declare function loadEnvFile(cwd?: string): void;
+/**
+ * Get project credentials from environment
+ * Returns undefined if not found
+ */
+export declare function getProjectCredentials(): {
+    projectId: string;
+    projectSecret: string;
+} | undefined;
+/**
+ * Get project ID from environment
+ * Returns undefined if not found
+ */
+export declare function getProjectId(): string | undefined;
+//# sourceMappingURL=env.d.ts.map

package/dist/utils/env.js

@@ -0,0 +1,56 @@
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Load environment variables from .env.local file
+ * Merges with existing process.env (process.env takes precedence)
+ */
+export function loadEnvFile(cwd = process.cwd()) {
+    const envPath = path.join(cwd, '.env.local');
+    if (!fs.existsSync(envPath)) {
+        return;
+    }
+    try {
+        const content = fs.readFileSync(envPath, 'utf-8');
+        const lines = content.split('\n');
+        for (const line of lines) {
+            // Skip empty lines and comments
+            if (!line.trim() || line.trim().startsWith('#')) {
+                continue;
+            }
+            // Parse KEY=VALUE format
+            const match = line.match(/^([^=]+)=(.*)$/);
+            if (match) {
+                const key = match[1].trim();
+                const value = match[2].trim();
+                // Only set if not already in process.env
+                if (!process.env[key]) {
+                    process.env[key] = value;
+                }
+            }
+        }
+    }
+    catch (error) {
+        // Silently fail if we can't read the file
+        // The commands will error appropriately if env vars are missing
+    }
+}
+/**
+ * Get project credentials from environment
+ * Returns undefined if not found
+ */
+export function getProjectCredentials() {
+    const projectId = process.env.DOTREQUIREMENTS_PROJECT_ID;
+    const projectSecret = process.env.DOTREQUIREMENTS_PROJECT_SECRET;
+    if (!projectId || !projectSecret) {
+        return undefined;
+    }
+    return { projectId, projectSecret };
+}
+/**
+ * Get project ID from environment
+ * Returns undefined if not found
+ */
+export function getProjectId() {
+    return process.env.DOTREQUIREMENTS_PROJECT_ID;
+}
+//# sourceMappingURL=env.js.map

package/dist/utils/gitignore.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Ensure .env.local is in .gitignore
+ * Creates .gitignore if it doesn't exist
+ * Appends .env.local if not already present
+ */
+export declare function ensureGitignore(cwd?: string): void;
+//# sourceMappingURL=gitignore.d.ts.map

package/dist/utils/gitignore.js

@@ -0,0 +1,29 @@
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Ensure .env.local is in .gitignore
+ * Creates .gitignore if it doesn't exist
+ * Appends .env.local if not already present
+ */
+export function ensureGitignore(cwd = process.cwd()) {
+    const gitignorePath = path.join(cwd, '.gitignore');
+    const entryToAdd = '.env.local';
+    const comment = '# dotrequirements credentials';
+    // Check if .gitignore exists
+    if (!fs.existsSync(gitignorePath)) {
+        // Create new .gitignore
+        fs.writeFileSync(gitignorePath, `${comment}\n${entryToAdd}\n`);
+        return;
+    }
+    // Read existing .gitignore
+    const content = fs.readFileSync(gitignorePath, 'utf-8');
+    // Check if .env.local is already present
+    if (content.includes(entryToAdd)) {
+        return; // Already present, nothing to do
+    }
+    // Append to .gitignore
+    const separator = content.endsWith('\n') ? '' : '\n';
+    const newContent = `${content}${separator}\n${comment}\n${entryToAdd}\n`;
+    fs.writeFileSync(gitignorePath, newContent);
+}
+//# sourceMappingURL=gitignore.js.map