@popoverai/dotrequirements 0.11.0

package/dist/commands/logout.js

@@ -0,0 +1,17 @@
+/**
+ * Logout command - clear stored authentication tokens.
+ */
+import { deleteTokens, hasValidTokens } from '../utils/token-storage.js';
+export async function logoutCommand() {
+    const wasLoggedIn = await hasValidTokens();
+    await deleteTokens();
+    if (wasLoggedIn) {
+        console.log('Logged out successfully.');
+    }
+    else {
+        console.log('No active session found.');
+    }
+    console.log('\nYour project credentials in .env.local are unchanged.');
+    console.log('Run "dotrequirements login" to authenticate again.');
+}
+//# sourceMappingURL=logout.js.map

package/dist/commands/mcp-setup.d.ts

@@ -0,0 +1,5 @@
+/**
+ * MCP setup command - configures the MCP server for AI assistants
+ */
+export declare function mcpSetupCommand(): Promise<void>;
+//# sourceMappingURL=mcp-setup.d.ts.map

package/dist/commands/mcp-setup.js

@@ -0,0 +1,367 @@
+import { execSync } from 'child_process';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { join, dirname } from 'path';
+import prompts from 'prompts';
+import { findUp } from 'find-up';
+import { loadPlatformTemplate, loadTestWritingTemplate, loadOverviewTemplate } from '../utils/templates.js';
+import { brand } from '../utils/brand.js';
+/**
+ * Platform-specific skills directory paths (relative to git root)
+ */
+const PLATFORM_SKILLS_DIRS = {
+    'claude-code': '.claude/skills',
+    'cursor': '.cursor/skills',
+    'antigravity': '.agent/skills',
+    'codex': '.codex/skills',
+    'github-copilot': '.github/skills',
+};
+/**
+ * Load skill content by name
+ */
+function loadSkillContent(skillName) {
+    switch (skillName) {
+        case 'dotreq-requirements':
+            return loadPlatformTemplate('claude-code-skill.md');
+        case 'dotreq-tests':
+            return loadTestWritingTemplate('claude-code-test-skill.md');
+        case 'dotreq-overview':
+            return loadOverviewTemplate('claude-code-overview-skill.md');
+    }
+}
+/**
+ * Install a single skill to the specified base directory
+ */
+async function installSkill(skillName, baseDir, gitRoot) {
+    const content = loadSkillContent(skillName);
+    const skillDir = join(gitRoot, baseDir, skillName);
+    const skillPath = join(skillDir, 'SKILL.md');
+    if (!existsSync(skillDir)) {
+        mkdirSync(skillDir, { recursive: true });
+    }
+    writeFileSync(skillPath, content, 'utf-8');
+    console.log(`   Created: ${skillPath}`);
+}
+/**
+ * Prompt user to install workflow guidance
+ */
+async function promptForGuidanceInstall(installPath) {
+    const response = await prompts({
+        type: 'confirm',
+        name: 'install',
+        message: `Install workflow guidance? (recommended)\n  → ${installPath}`,
+        initial: true,
+    });
+    return response.install ?? false;
+}
+/**
+ * Install all three skills to a platform's skills directory
+ */
+async function installAllSkills(platform, customPath) {
+    const gitDir = await findUp('.git', { type: 'directory' });
+    if (!gitDir) {
+        console.error('\n❌ Could not find git root directory.');
+        console.log('   Make sure you are inside a git repository.');
+        return;
+    }
+    const gitRoot = dirname(gitDir);
+    const baseDir = customPath || PLATFORM_SKILLS_DIRS[platform];
+    if (!baseDir) {
+        console.error(`\n❌ Unknown platform: ${platform}`);
+        return;
+    }
+    // Prompt for each skill
+    const skills = [
+        { name: 'dotreq-overview', label: 'Overview' },
+        { name: 'dotreq-requirements', label: 'Requirements capture' },
+        { name: 'dotreq-tests', label: 'Test writing' },
+    ];
+    for (const skill of skills) {
+        const skillPath = join(gitRoot, baseDir, skill.name, 'SKILL.md');
+        const shouldInstall = await promptForGuidanceInstall(skillPath);
+        if (shouldInstall) {
+            try {
+                await installSkill(skill.name, baseDir, gitRoot);
+                console.log(`✅ ${skill.label} guidance installed\n`);
+            }
+            catch (error) {
+                console.error(`❌ Failed to install ${skill.label} guidance`);
+                console.log(`   Error: ${error instanceof Error ? error.message : String(error)}\n`);
+            }
+        }
+        else {
+            console.log('');
+        }
+    }
+}
+/**
+ * MCP setup command - configures the MCP server for AI assistants
+ */
+export async function mcpSetupCommand() {
+    console.log(`🔧 Setting up ${brand} MCP server\n`);
+    // Interactive client selector
+    const response = await prompts({
+        type: 'select',
+        name: 'client',
+        message: 'Which AI assistant are you using?',
+        choices: [
+            { title: 'Claude Code', value: 'claude-code' },
+            { title: 'Cursor', value: 'cursor' },
+            { title: 'Google Antigravity', value: 'antigravity' },
+            { title: 'OpenAI Codex', value: 'codex' },
+            { title: 'GitHub Copilot', value: 'github-copilot' },
+            { title: 'Other (custom path)', value: 'other' },
+        ],
+        initial: 0,
+    });
+    if (!response.client) {
+        console.log('\nSetup cancelled.');
+        return;
+    }
+    switch (response.client) {
+        case 'claude-code':
+            await setupClaudeCode();
+            break;
+        case 'cursor':
+            await setupCursor();
+            break;
+        case 'antigravity':
+            await setupAntigravity();
+            break;
+        case 'codex':
+            await setupCodex();
+            break;
+        case 'github-copilot':
+            await setupGitHubCopilot();
+            break;
+        case 'other':
+            await setupOther();
+            break;
+        default:
+            console.log(`\n❌ ${response.client} is not yet supported.`);
+            console.log('Please refer to the documentation for manual setup.');
+    }
+}
+async function setupClaudeCode() {
+    console.log('\n📦 Configuring MCP for Claude Code...\n');
+    const command = `claude mcp add-json dotrequirements '{"type":"stdio","command":"npx","args":["-y","@popoverai/dotrequirements","mcp"]}'`;
+    let mcpConfigured = false;
+    try {
+        execSync(command, { stdio: 'pipe' });
+        console.log('✅ MCP configured successfully for Claude Code!');
+        mcpConfigured = true;
+    }
+    catch (error) {
+        const stderr = error.stderr?.toString() || '';
+        const errorMessage = error.message || '';
+        const combinedError = stderr + errorMessage;
+        if (combinedError.includes('already exists')) {
+            console.log('✅ MCP server already configured for Claude Code');
+            mcpConfigured = true;
+        }
+        else {
+            console.error('❌ Failed to configure MCP automatically.');
+            console.log('\nYou can manually run:');
+            console.log(`  ${command}`);
+            if (stderr) {
+                console.log(`\nError: ${stderr}`);
+            }
+        }
+    }
+    if (mcpConfigured) {
+        console.log('\n⚠️  Important: Restart Claude Code for changes to take effect.');
+        console.log('\nYou can now ask your AI assistant to help write requirements!\n');
+        await installAllSkills('claude-code');
+    }
+}
+async function setupCursor() {
+    console.log('\n📦 Configuring MCP for Cursor (project-specific)...\n');
+    const configPath = join(process.cwd(), '.cursor', 'mcp.json');
+    const configDir = join(process.cwd(), '.cursor');
+    const mcpServerConfig = {
+        command: 'npx',
+        args: ['-y', '@popoverai/dotrequirements', 'mcp'],
+    };
+    try {
+        if (!existsSync(configDir)) {
+            console.log('Creating Cursor config directory...');
+            mkdirSync(configDir, { recursive: true });
+        }
+        let config = {};
+        if (existsSync(configPath)) {
+            try {
+                const existingContent = readFileSync(configPath, 'utf-8');
+                if (existingContent.trim()) {
+                    config = JSON.parse(existingContent);
+                }
+            }
+            catch (parseError) {
+                console.log('⚠️  Existing config file is invalid, creating fresh config...');
+                config = {};
+            }
+        }
+        if (!config.mcpServers) {
+            config.mcpServers = {};
+        }
+        config.mcpServers['dotrequirements'] = mcpServerConfig;
+        writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+        console.log(`✅ MCP configured successfully!`);
+        console.log(`   Config file: ${configPath}\n`);
+        console.log('⚠️  Important: Reload or restart Cursor for changes to take effect.');
+        console.log('\nYou can now ask your AI assistant to help write requirements!\n');
+        await installAllSkills('cursor');
+    }
+    catch (error) {
+        console.error('❌ Failed to configure MCP automatically.');
+        console.log(`\nError: ${error instanceof Error ? error.message : String(error)}`);
+        console.log('\nYou can manually edit the config file at:');
+        console.log(`  ${configPath}\n`);
+        console.log('Add the following configuration:');
+        const manualConfig = {
+            mcpServers: {
+                dotrequirements: mcpServerConfig,
+            },
+        };
+        console.log(JSON.stringify(manualConfig, null, 2));
+    }
+}
+async function setupAntigravity() {
+    console.log('\n📦 Configuring MCP for Google Antigravity...\n');
+    const configPath = join(homedir(), '.gemini', 'antigravity', 'mcp_config.json');
+    const configDir = join(homedir(), '.gemini', 'antigravity');
+    // Check if we're in a dotrequirements project directory
+    const envLocalPath = join(process.cwd(), '.env.local');
+    let projectId = null;
+    let projectPath = null;
+    if (existsSync(envLocalPath)) {
+        try {
+            const envContent = readFileSync(envLocalPath, 'utf-8');
+            const lines = envContent.split('\n');
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (trimmed.startsWith('DOTREQUIREMENTS_PROJECT_ID=')) {
+                    projectId = trimmed.split('=')[1]?.trim().replace(/['"]/g, '');
+                    projectPath = process.cwd();
+                    break;
+                }
+            }
+        }
+        catch (error) {
+            // .env.local exists but couldn't read it - continue with global setup
+        }
+    }
+    try {
+        if (!existsSync(configDir)) {
+            console.log('Creating Antigravity config directory...');
+            mkdirSync(configDir, { recursive: true });
+        }
+        let config = {};
+        if (existsSync(configPath)) {
+            try {
+                const existingContent = readFileSync(configPath, 'utf-8');
+                if (existingContent.trim()) {
+                    config = JSON.parse(existingContent);
+                }
+            }
+            catch (parseError) {
+                console.log('⚠️  Existing config file is invalid, creating fresh config...');
+                config = {};
+            }
+        }
+        if (!config.mcpServers) {
+            config.mcpServers = {};
+        }
+        if (!config.mcpServers['dotrequirements']) {
+            config.mcpServers['dotrequirements'] = {
+                command: 'npx',
+                args: ['-y', '@popoverai/dotrequirements', 'mcp'],
+                env: {},
+            };
+        }
+        const dotreqServer = config.mcpServers['dotrequirements'];
+        if (!dotreqServer.env) {
+            dotreqServer.env = {};
+        }
+        if (projectId && projectPath) {
+            const envKey = `PROJ_${projectId}`;
+            dotreqServer.env[envKey] = projectPath;
+            console.log(`✅ Added project to MCP config: ${envKey}`);
+            console.log(`   Path: ${projectPath}\n`);
+        }
+        else {
+            console.log(`ℹ️  Not in a ${brand} project directory (no .env.local with DOTREQUIREMENTS_PROJECT_ID found)`);
+            console.log('   Setting up global MCP server only.\n');
+        }
+        writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+        console.log(`✅ MCP configured successfully!`);
+        console.log(`   Config file: ${configPath}\n`);
+        console.log('⚠️  Important: Reload or restart Google Antigravity for changes to take effect.');
+        console.log('\nYou can now ask your AI assistant to help write requirements!');
+        if (projectId) {
+            console.log(`\n💡 To add more projects, run \`dotreq mcp-setup\` from each project directory.\n`);
+        }
+        else {
+            console.log('');
+        }
+        await installAllSkills('antigravity');
+    }
+    catch (error) {
+        console.error('❌ Failed to configure MCP automatically.');
+        console.log(`\nError: ${error instanceof Error ? error.message : String(error)}`);
+        console.log('\nYou can manually edit the config file at:');
+        console.log(`  ${configPath}`);
+    }
+}
+async function setupCodex() {
+    console.log('\n📦 Configuring MCP for OpenAI Codex...\n');
+    const command = `codex mcp add dotrequirements -- npx -y @popoverai/dotrequirements mcp`;
+    try {
+        execSync(command, { stdio: 'inherit' });
+        console.log('\n✅ MCP configured successfully for Codex!');
+        console.log('\n⚠️  Important: Restart Codex for changes to take effect.');
+        console.log('\nYou can now ask your AI assistant to help write requirements!\n');
+        await installAllSkills('codex');
+    }
+    catch (error) {
+        console.error('\n❌ Failed to configure MCP automatically.');
+        console.log('\nYou can manually run:');
+        console.log(`  ${command}`);
+        console.log('\nOr manually edit ~/.codex/config.toml and add:');
+        console.log('[mcp_servers.dotrequirements]');
+        console.log('command = "npx"');
+        console.log('args = ["-y", "@popoverai/dotrequirements", "mcp"]');
+    }
+}
+async function setupGitHubCopilot() {
+    console.log('\n📦 Configuring skills for GitHub Copilot...\n');
+    console.log('ℹ️  GitHub Copilot discovers MCP servers from your IDE configuration.');
+    console.log('   Please configure the MCP server in VS Code settings or GitHub settings.\n');
+    console.log('   MCP server command: npx -y @popoverai/dotrequirements mcp\n');
+    await installAllSkills('github-copilot');
+}
+async function setupOther() {
+    console.log('\n📦 Custom Agent Skills Setup\n');
+    console.log('ℹ️  Agent Skills are installed as SKILL.md files in a skills directory.');
+    console.log('   Common locations:');
+    console.log('   - .claude/skills/  (Claude Code)');
+    console.log('   - .cursor/skills/  (Cursor)');
+    console.log('   - .agent/skills/   (Antigravity)');
+    console.log('   - .codex/skills/   (Codex)');
+    console.log('   - .github/skills/  (GitHub Copilot)\n');
+    const response = await prompts({
+        type: 'text',
+        name: 'path',
+        message: 'Enter the skills directory path (relative to git root):',
+        initial: '.skills',
+    });
+    if (!response.path) {
+        console.log('\nSetup cancelled.');
+        return;
+    }
+    console.log('\n📝 MCP Server Setup\n');
+    console.log('Configure your AI assistant to run the MCP server:');
+    console.log('   Command: npx');
+    console.log('   Args: -y @popoverai/dotrequirements mcp\n');
+    await installAllSkills('other', response.path);
+}
+//# sourceMappingURL=mcp-setup.js.map

package/dist/commands/mcp.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP command - starts the Model Context Protocol server
+ * This allows AI assistants to query requirements data
+ */
+export declare function mcpCommand(): Promise<void>;
+//# sourceMappingURL=mcp.d.ts.map

package/dist/commands/mcp.js

@@ -0,0 +1,10 @@
+/**
+ * MCP command - starts the Model Context Protocol server
+ * This allows AI assistants to query requirements data
+ */
+export async function mcpCommand() {
+    // Import the MCP server - this starts it automatically
+    // The server handles stdio transport and runs until process termination
+    await import('../mcp/index.js');
+}
+//# sourceMappingURL=mcp.js.map

package/dist/commands/pull.d.ts

@@ -0,0 +1,7 @@
+interface PullOptions {
+    project?: string;
+    document?: string;
+}
+export declare function pullCommand(options: PullOptions): Promise<void>;
+export {};
+//# sourceMappingURL=pull.d.ts.map

package/dist/commands/pull.js

@@ -0,0 +1,171 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { ConvexHttpClient } from 'convex/browser';
+import { getConvexUrl } from '../config.js';
+import { buildRequirementsFile } from '../schema/index.js';
+import { api } from '../convex.js';
+import { isLocalOnlyProject, CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE } from '../utils/local-project.js';
+import { brand } from '../utils/brand.js';
+export async function pullCommand(options) {
+    try {
+        console.log(`Syncing requirements from ${brand} cloud...`);
+        // Connect to Convex
+        const convexUrl = getConvexUrl();
+        const client = new ConvexHttpClient(convexUrl);
+        // Determine project ID
+        let projectId = options.project;
+        // If no project flag provided, try to read from .env.local
+        if (!projectId && !options.document) {
+            projectId = loadProjectIdFromEnv();
+            if (!projectId) {
+                throw new Error('Project ID not found. Either:\n' +
+                    '  1. Run "dotreq init" to initialize the project, or\n' +
+                    '  2. Use --project flag to specify the project ID');
+            }
+            // AUTHZ-2.0: Check if project is local-only
+            if (isLocalOnlyProject(projectId)) {
+                throw new Error(CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE);
+            }
+        }
+        // Load project secret for authentication
+        const projectSecret = process.env.DOTREQUIREMENTS_PROJECT_SECRET;
+        if (!projectSecret) {
+            throw new Error('DOTREQUIREMENTS_PROJECT_SECRET not found. Either:\n' +
+                '  1. Run "dotrequirements init" or "dotrequirements login" to set up authentication, or\n' +
+                '  2. Set DOTREQUIREMENTS_PROJECT_SECRET in .env.local');
+        }
+        // Fetch documents
+        let documents;
+        if (options.document) {
+            // Fetch specific document
+            const doc = await client.query(api.documents.queries.exportForCli, {
+                projectAuth: {
+                    projectSlug: projectId,
+                    projectSecret,
+                },
+                target: { type: 'document', id: options.document },
+                documentId: options.document,
+            });
+            documents = doc ? [doc] : [];
+        }
+        else if (projectId) {
+            // Fetch all documents for project
+            // SYNC-ARCH-3.1: Use projectSlug (not projectId) since env stores the slug
+            documents = await client.query(api.documents.queries.exportProjectForCli, {
+                projectAuth: {
+                    projectSlug: projectId,
+                    projectSecret,
+                },
+                target: { type: 'project', slug: projectId },
+            });
+        }
+        else {
+            throw new Error('Either --project or --document must be specified');
+        }
+        if (documents.length === 0) {
+            console.log('No documents found.');
+            return;
+        }
+        // Ensure .requirements/ directory exists
+        const requirementsDir = path.join(process.cwd(), '.requirements');
+        if (!fs.existsSync(requirementsDir)) {
+            fs.mkdirSync(requirementsDir, { recursive: true });
+        }
+        // Build index of existing files by document ID
+        const existingFilesByDocId = buildDocumentIdIndex(requirementsDir);
+        // Write each document as a Markdown file
+        for (const doc of documents) {
+            // Check if an existing file has this document ID
+            const existingFilePath = existingFilesByDocId.get(doc.documentId);
+            const filePath = existingFilePath ?? path.join(requirementsDir, sanitizeFileName(doc.title) + '.requirements.md');
+            const fileName = path.basename(filePath);
+            // Build metadata with pulledAt for conflict detection
+            // SYNC-CLI-EDIT-2: pulledAt is compared with cloud updatedAt during push
+            // Use the slug we authenticated with (not the Convex ID from the response)
+            const metadata = {
+                projectId: projectId,
+                pulledAt: new Date().toISOString(),
+                version: doc.version,
+                document: {
+                    id: doc.documentId,
+                    title: doc.title,
+                    defaultPrefix: doc.defaultPrefix,
+                },
+            };
+            // SYNC-ARCH-1: Use markdownContent directly from cloud (source of truth)
+            // No need to rebuild from requirements - just combine with frontmatter
+            const fileContent = buildRequirementsFile(metadata, doc.markdownContent);
+            fs.writeFileSync(filePath, fileContent, 'utf-8');
+            console.log(`✓ Synced: ${fileName} (version ${doc.version})`);
+        }
+        console.log(`\nSuccessfully synced ${documents.length} document(s) to .requirements/`);
+    }
+    catch (error) {
+        // Re-throw to let the CLI error handler display it cleanly
+        throw error;
+    }
+}
+/**
+ * Sanitize document title for use as filename
+ */
+function sanitizeFileName(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * Load project ID from process.env (already loaded from .env.local by CLI)
+ */
+function loadProjectIdFromEnv() {
+    return process.env.DOTREQUIREMENTS_PROJECT_ID;
+}
+/**
+ * Build an index mapping document IDs to their file paths.
+ * Scans existing .requirements.md files and extracts document.id from frontmatter.
+ */
+function buildDocumentIdIndex(requirementsDir) {
+    const index = new Map();
+    if (!fs.existsSync(requirementsDir)) {
+        return index;
+    }
+    const files = fs.readdirSync(requirementsDir);
+    for (const file of files) {
+        if (!file.endsWith('.requirements.md')) {
+            continue;
+        }
+        const filePath = path.join(requirementsDir, file);
+        const docId = extractDocumentIdFromFile(filePath);
+        if (docId) {
+            index.set(docId, filePath);
+        }
+    }
+    return index;
+}
+/**
+ * Extract document.id from a requirements file's frontmatter.
+ * Returns undefined if the file can't be read or doesn't have a document ID.
+ */
+function extractDocumentIdFromFile(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        // Match document.id in YAML frontmatter - handles both inline and nested formats
+        // Inline: document: { id: "abc123", ... }
+        // Nested:
+        //   document:
+        //     id: abc123
+        const inlineMatch = content.match(/document:\s*\{[^}]*id:\s*["']?([^"',}\s]+)/);
+        if (inlineMatch) {
+            return inlineMatch[1];
+        }
+        const nestedMatch = content.match(/document:\s*\n\s+id:\s*["']?([^"'\s\n]+)/);
+        if (nestedMatch) {
+            return nestedMatch[1];
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=pull.js.map

package/dist/commands/push.d.ts

@@ -0,0 +1,11 @@
+interface PushOptions {
+    yes?: boolean;
+}
+export declare function pushCommand(file: string | undefined, options: PushOptions): Promise<void>;
+/**
+ * Extract markdown content from a file, stripping YAML frontmatter.
+ * Exported for testing.
+ */
+export declare function extractMarkdownContent(rawContent: string): string;
+export {};
+//# sourceMappingURL=push.d.ts.map