@popoverai/dotrequirements 0.11.0

package/README.md

@@ -0,0 +1,478 @@
+# dot•requirements
+
+Requirements tracking CLI, test harness, and MCP server for AI-assisted development.
+
+**dot•requirements** treats requirements as discrete, testable data that flows from discovery through implementation to testing. Write requirements as structured Markdown, reference them in tests, and track coverage over time.
+
+> **Alpha Software** — This package is under active development and may be unstable or incomplete. We're working toward a stable release, but things may break. Please report issues to support@popover.ca.
+
+## Installation
+
+```bash
+npm install @popoverai/dotrequirements
+# or
+pnpm add @popoverai/dotrequirements
+```
+
+> **Note:** Examples use `dotreq` for brevity. The full command `dotrequirements` also works.
+
+## Quick Start
+
+### 1. Initialize a project
+
+```bash
+npx dotreq init
+```
+
+This creates a `.requirements/` directory with example requirements and configures your project.
+
+### 2. Write requirements
+
+Create `*.requirements.md` files in `.requirements/` or colocate them with your code:
+
+```markdown
+---
+projectId: my-project
+version: 1
+document:
+  id: auth-requirements
+  title: "Authentication Requirements"
+---
+
+## User Authentication
+
+```dotrequirements
+AUTH-LOGIN-1: A registered user, Jamie, can log in to their account
+  0. → When Jamie provides a valid username and password, they are authenticated and brought to their dashboard
+  1. → When Jamie provides an incorrect password, they see an error message and remain on the login page
+  2. → When Jamie's account has been deactivated, but they provide otherwise correct credentials, they see a message explaining their account status
+```
+
+If your team prefers a structure such as Gherkin, you can add labels:
+
+```dotrequirements
+AUTH-LOGIN-2: A user with two-factor authentication enabled must provide an OTP
+  0. Given → Jamie has two-factor authentication enabled on their account
+  1. When → Jamie provides valid credentials
+  2. Then → Jamie is prompted to enter an OTP before accessing their dashboard
+```
+
+### 3. Reference requirements in tests
+
+```typescript
+import { requirement } from '@popoverai/dotrequirements/test';
+
+describe(requirement('AUTH-LOGIN-1'), () => {
+  it(requirement('AUTH-LOGIN-1.0'), () => {
+    // valid credentials → authenticated
+  });
+
+  it(requirement('AUTH-LOGIN-1.1'), () => {
+    // incorrect password → error message
+  });
+});
+```
+
+### 4. Track coverage
+
+After running tests, you'll see a coverage report showing which requirements have been tested.
+
+---
+
+## What Works Locally
+
+The following features work fully offline—no account required:
+
+- Write requirements (`.requirements.md` files)
+- Validate requirements (`dotreq test`)
+- Reference requirements in tests (`requirement()`)
+- Coverage reporting (console output)
+- MCP tools (search, validate, explore)
+
+The following features require a dot•requirements cloud account:
+
+- Sync requirements (`pull` / `push`)
+- Historical coverage tracking
+- AI-powered style checking
+- Team collaboration
+
+To enable cloud features, run `dotreq login`.
+
+---
+
+## CLI Commands
+
+### `dotreq init`
+
+Initialize a new project. Creates `.requirements/` directory, example files, and configuration.
+
+```bash
+dotreq init
+dotreq init --name my-project
+```
+
+### `dotreq link`
+
+Link your local environment to an existing project (when you already have a project in dot•requirements cloud).
+
+```bash
+dotreq link
+```
+
+### `dotreq pull`
+
+Sync requirements from dot•requirements cloud to local `.requirements/` files.
+
+```bash
+dotreq pull
+dotreq pull --project <project-id>
+dotreq pull --document <document-id>
+```
+
+### `dotreq push`
+
+Push local requirements to dot•requirements cloud.
+
+```bash
+dotreq push
+dotreq push .requirements/auth.requirements.md
+dotreq push --yes  # Skip confirmation
+```
+
+### `dotreq test`
+
+Validate requirements files against the schema.
+
+```bash
+dotreq test
+dotreq test --file .requirements/auth.requirements.md
+```
+
+### `dotreq login` / `logout`
+
+Authenticate with dot•requirements cloud.
+
+```bash
+dotreq login
+dotreq logout
+```
+
+### `dotreq mcp-setup`
+
+Configure the MCP server for AI assistants (Claude Code, Cursor, etc.).
+
+```bash
+dotreq mcp-setup
+```
+
+### `dotreq mcp`
+
+Start the MCP server manually (typically not needed—AI assistants start it automatically after `mcp-setup`).
+
+```bash
+dotreq mcp
+```
+
+---
+
+## Test Harness
+
+The test harness tracks which requirements are exercised by your tests.
+
+### Setup with Vitest
+
+**vitest.config.ts:**
+
+```typescript
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globalSetup: './vitest.setup.ts',
+  },
+});
+```
+
+**vitest.setup.ts:**
+
+```typescript
+import { prepare, finalize } from '@popoverai/dotrequirements/test';
+
+// Named exports: Vitest calls setup() before tests, teardown() after
+export function setup() {
+  prepare();
+}
+
+export async function teardown() {
+  await finalize();
+}
+```
+
+Alternatively, you can use the default export pattern that returns a teardown function—see the [Vitest globalSetup docs](https://vitest.dev/config/globalsetup).
+
+### Setup with Jest
+
+**jest.config.cjs:**
+
+```javascript
+module.exports = {
+  globalSetup: './jest.setup.cjs',
+  globalTeardown: './jest.teardown.cjs',
+};
+```
+
+**jest.setup.cjs:**
+
+```javascript
+const { prepare } = require('@popoverai/dotrequirements/test');
+
+module.exports = async function setup() {
+  prepare();
+};
+```
+
+**jest.teardown.cjs:**
+
+```javascript
+const { finalize } = require('@popoverai/dotrequirements/test');
+
+module.exports = async function teardown() {
+  await finalize();
+};
+```
+
+> **Note:** Jest global setup/teardown files run in a separate process from your tests. If using ES modules, configure Jest's `transform` option accordingly.
+
+### Using `requirement()` in Tests
+
+The `requirement()` function returns a formatted string for test descriptions and tracks coverage:
+
+```typescript
+import { requirement } from '@popoverai/dotrequirements/test';
+
+// Reference root requirement
+test(requirement('AUTH-LOGIN-1'), () => {
+  // Returns: "A registered user, Jamie, can log in to their account"
+});
+
+// Reference by numeric path
+test(requirement('AUTH-LOGIN-1.0'), () => {
+  // Returns: "When Jamie provides a valid username and password..."
+});
+
+// Reference by label path (for requirements with labels)
+test(requirement('AUTH-LOGIN-2.given'), () => {
+  // Returns: "Given: Jamie has two-factor authentication enabled on their account"
+});
+
+// Track multiple requirements in one test
+test(requirement('AUTH-LOGIN-1', 'AUTH-SECURITY-1'), () => {
+  // Both requirements tracked; returns first one's content
+});
+```
+
+### Path Reference Patterns
+
+| Pattern | Example | Description |
+|---------|---------|-------------|
+| Root | `AUTH-LOGIN-1` | Root requirement |
+| Numeric | `AUTH-LOGIN-1.0` | First child (position 0) |
+| Numeric nested | `AUTH-LOGIN-1.2.0` | First child of third child |
+| Label | `AUTH-LOGIN-2.given` | First "Given" criterion |
+| Label disambiguated | `AUTH-LOGIN-2.given#1` | Second "Given" criterion |
+| Label nested | `AUTH-LOGIN-2.then.and` | First "And" under first "Then" |
+
+### Coverage Reporting
+
+#### Local Report
+
+After tests complete, a coverage summary prints to the console:
+
+```
+=== Requirements Coverage Report ===
+Total Requirements: 12
+Tested Requirements: 10
+Untested Requirements: 2
+Coverage: 83.3%
+
+Tested:
+  ✓ AUTH-LOGIN-1 (A registered user, Jamie, can log in to their account)
+  ✓ AUTH-LOGIN-1.0 (When Jamie provides a valid username and password...)
+  ...
+
+Untested:
+  ✗ AUTH-LOGIN-2
+  ✗ AUTH-SECURITY-1
+```
+
+#### Cloud Reporting
+
+With cloud credentials configured, coverage is automatically reported to dot•requirements cloud:
+
+- Historical tracking of when requirements were last tested
+- Branch-based coverage (tracks `main`, feature branches, etc.)
+- Query coverage via the MCP server
+
+Configure by adding to `.env.local`:
+
+```bash
+DOTREQUIREMENTS_PROJECT_ID=your-project-id
+DOTREQUIREMENTS_PROJECT_SECRET=your-project-secret
+```
+
+Cloud reporting is fire-and-forget—it never blocks or fails your tests.
+
+---
+
+## Requirements File Format
+
+Requirements use Markdown with YAML frontmatter and `dotrequirements` fenced code blocks.
+
+### File Naming
+
+Files must match the pattern `*.requirements.md`:
+
+```
+.requirements/
+  auth.requirements.md
+  checkout.requirements.md
+
+src/components/
+  Button.requirements.md    # Colocated with implementation
+  Button.tsx
+```
+
+### Structure
+
+```markdown
+---
+projectId: my-project
+version: 1
+document:
+  id: unique-doc-id
+  title: "Document Title"
+---
+
+# Optional Markdown Content
+
+You can include any Markdown here for context.
+
+## Requirement Heading
+
+```dotrequirements
+AUTH-LOGIN-1: A registered user, Jamie, can log in to their account
+  0. → When Jamie provides valid credentials, they are authenticated
+  1. → When Jamie provides an incorrect password, they see an error
+  2. → When Jamie's account is deactivated, they see a status message
+```
+
+More Markdown content between requirements...
+
+## Another Requirement (with labels)
+
+```dotrequirements
+AUTH-LOGIN-2: A user with two-factor auth must provide an OTP
+  0. Given → Jamie has two-factor authentication enabled
+  1. When → Jamie provides valid credentials
+  2. Then → Jamie is prompted to enter an OTP
+```
+```
+
+### Format Details
+
+- **Frontmatter**: YAML metadata (`projectId`, `version`, `document`)
+- **Headings**: Optional documentation (not parsed as requirement data)
+- **Fenced blocks**: `dotrequirements` blocks contain structured requirement data
+- **First line**: `KEY: content` — the requirement identifier and summary
+- **Criteria**: `position. → content` or `position. Label → content`
+- **Arrow delimiter**: `→` (Unicode) or `->` (ASCII) both work
+- **Labels**: Optional — use `Given`, `When`, `Then`, `And` if your team prefers BDD style
+
+See [MARKDOWN_SCHEMA.md](https://github.com/PopoverAI/dotrequirements/blob/main/docs/reference/MARKDOWN_SCHEMA.md) for the complete specification.
+
+---
+
+## MCP Server
+
+The package includes an MCP (Model Context Protocol) server for AI assistant integration. This enables AI coding assistants to search, validate, and work with your requirements.
+
+### Setup
+
+```bash
+dotreq mcp-setup
+```
+
+Follow the prompts to configure for your AI assistant (Claude Code, Cursor, etc.).
+
+### Available Tools
+
+**Exploration:**
+- `search_requirements` — Search by text or regex
+- `get_requirement` — Get a requirement with its children and coverage
+- `list_all_requirements` — List all requirements in the project
+- `list_untested_requirements` — Find requirements without test coverage
+- `get_requirements_by_test` — Get requirements referenced by a test file
+- `get_tests_by_requirement` — Get tests that reference a requirement
+
+**Authoring:**
+- `create_requirement_document` — Get a Markdown template with format examples
+- `validate_requirements` — Validate file schema (works offline)
+- `style_check` — AI-powered style feedback on requirements
+- `review_test` — Comprehensive test review (style + semantic correctness)
+
+**Cloud:**
+- `push_requirements` — Push to dot•requirements cloud
+- `get_requirement_coverage` — Query coverage data
+- `get_project_coverage_summary` — Project-wide coverage stats
+
+**Diagnostic:**
+- `debug_mcp_environment` — Debug MCP server configuration
+
+---
+
+## Package Exports
+
+```typescript
+// CLI (main entry point)
+import '@popoverai/dotrequirements';
+
+// Test harness
+import { requirement, prepare, finalize } from '@popoverai/dotrequirements/test';
+
+// Schema utilities
+import { parseRequirementsFile, validateRequirementsFile } from '@popoverai/dotrequirements/schema';
+
+// Browser-compatible schema (no Node.js dependencies)
+import { parseRequirementBlock } from '@popoverai/dotrequirements/schema/browser';
+
+// MCP server
+import '@popoverai/dotrequirements/mcp';
+```
+
+---
+
+## Configuration
+
+The CLI stores configuration in `.env.local`:
+
+```bash
+# Project credentials (from dotreq init or login)
+DOTREQUIREMENTS_PROJECT_ID=your-project-id
+DOTREQUIREMENTS_PROJECT_SECRET=your-project-secret
+```
+
+The `.env.local` file is automatically added to `.gitignore` during initialization.
+
+---
+
+## Links
+
+- [Documentation](https://docs.dotrequirements.io)
+- [Getting Started Guide](https://docs.dotrequirements.io/getting-started)
+- [Support](mailto:support@popover.ca)
+
+---
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { initCommand } from './commands/init.js';
+import { linkCommand } from './commands/link.js';
+import { pullCommand } from './commands/pull.js';
+import { pushCommand } from './commands/push.js';
+import { testCommand } from './commands/test.js';
+import { mcpCommand } from './commands/mcp.js';
+import { mcpSetupCommand } from './commands/mcp-setup.js';
+import { loginCommand } from './commands/login.js';
+import { logoutCommand } from './commands/logout.js';
+import { loadEnvFile } from './utils/env.js';
+// Load environment variables from .env.local if it exists
+loadEnvFile();
+/**
+ * Wrap command handlers to catch errors and display them cleanly
+ * without showing stack traces to users
+ */
+function wrapCommand(fn) {
+    return async (...args) => {
+        try {
+            await fn(...args);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                console.error(`\nError: ${error.message}\n`);
+            }
+            else {
+                console.error(`\nError: ${String(error)}\n`);
+            }
+            process.exit(1);
+        }
+    };
+}
+const program = new Command();
+program
+    .name('dotrequirements')
+    .description('Requirements tracking CLI with test harness and MCP server')
+    .version('0.1.0');
+program
+    .command('init')
+    .description('Initialize a new dotrequirements project')
+    .option('-n, --name <name>', 'Project name (defaults to package.json name or directory name)')
+    .action(wrapCommand(initCommand));
+program
+    .command('link')
+    .description('Link local environment to an existing project')
+    .action(wrapCommand(linkCommand));
+program
+    .command('pull')
+    .description('Sync requirements from cloud to local .requirements/ files')
+    .option('-p, --project <id>', 'Project ID to sync')
+    .option('-d, --document <id>', 'Specific document ID to sync')
+    .action(wrapCommand(pullCommand));
+program
+    .command('push [file]')
+    .description('Push local requirements from .requirements/ to cloud')
+    .option('-y, --yes', 'Skip confirmation prompt')
+    .action(wrapCommand(pushCommand));
+program
+    .command('test')
+    .description('Validate requirements files in .requirements/')
+    .option('-f, --file <path>', 'Specific file to validate')
+    .action(wrapCommand(testCommand));
+program
+    .command('mcp')
+    .description('Start the MCP (Model Context Protocol) server for AI assistant integration')
+    .action(wrapCommand(mcpCommand));
+program
+    .command('mcp-setup')
+    .description('Configure MCP server for your AI assistant (Claude Code, Claude Desktop, etc.)')
+    .action(wrapCommand(mcpSetupCommand));
+program
+    .command('login')
+    .description('Authenticate with dot•requirements and enable cloud features')
+    .action(wrapCommand(loginCommand));
+program
+    .command('logout')
+    .description('Clear stored authentication tokens')
+    .action(wrapCommand(logoutCommand));
+program.parse();
+//# sourceMappingURL=cli.js.map

package/dist/commands/init.d.ts

@@ -0,0 +1,6 @@
+interface InitOptions {
+    name?: string;
+}
+export declare function initCommand(options?: InitOptions): Promise<void>;
+export {};
+//# sourceMappingURL=init.d.ts.map