@popoverai/dotrequirements 0.11.0

package/dist/utils/local-project.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Utilities for detecting and working with local-only projects.
+ *
+ * Local-only projects use placeholder credentials and have no cloud features.
+ */
+/**
+ * Check if a project is local-only (no cloud features).
+ *
+ * Local-only projects have placeholder credentials:
+ * - DOTREQUIREMENTS_PROJECT_ID=local
+ * - DOTREQUIREMENTS_PROJECT_SECRET=local
+ *
+ * These projects can use local features (test harness, MCP local operations)
+ * but cannot use cloud features (coverage reporting, push/pull, AI features).
+ *
+ * @param projectId - The project ID to check
+ * @returns true if the project is local-only, false otherwise
+ */
+export declare function isLocalOnlyProject(projectId: string | undefined): boolean;
+/**
+ * Placeholder credentials for local-only projects.
+ */
+export declare const LOCAL_PROJECT_CREDENTIALS: {
+    readonly projectId: "local";
+    readonly secret: "local";
+};
+/**
+ * Error message for when cloud features are attempted on local-only projects.
+ */
+export declare const CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE = "Cloud features require authentication. Run `dotrequirements login` to enable cloud features.";
+//# sourceMappingURL=local-project.d.ts.map

package/dist/utils/local-project.js

@@ -0,0 +1,33 @@
+/**
+ * Utilities for detecting and working with local-only projects.
+ *
+ * Local-only projects use placeholder credentials and have no cloud features.
+ */
+/**
+ * Check if a project is local-only (no cloud features).
+ *
+ * Local-only projects have placeholder credentials:
+ * - DOTREQUIREMENTS_PROJECT_ID=local
+ * - DOTREQUIREMENTS_PROJECT_SECRET=local
+ *
+ * These projects can use local features (test harness, MCP local operations)
+ * but cannot use cloud features (coverage reporting, push/pull, AI features).
+ *
+ * @param projectId - The project ID to check
+ * @returns true if the project is local-only, false otherwise
+ */
+export function isLocalOnlyProject(projectId) {
+    return projectId === 'local';
+}
+/**
+ * Placeholder credentials for local-only projects.
+ */
+export const LOCAL_PROJECT_CREDENTIALS = {
+    projectId: 'local',
+    secret: 'local',
+};
+/**
+ * Error message for when cloud features are attempted on local-only projects.
+ */
+export const CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE = 'Cloud features require authentication. Run `dotrequirements login` to enable cloud features.';
+//# sourceMappingURL=local-project.js.map

package/dist/utils/oauth-callback-server.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Local HTTP server for OAuth callback handling.
+ *
+ * Creates a temporary server on localhost to receive the OAuth redirect.
+ * Implements AUTH-5: Local callback server for OAuth redirect
+ */
+import * as http from 'http';
+export interface CallbackResult {
+    code: string;
+    state: string;
+}
+export interface CallbackServerOptions {
+    port?: number;
+    timeoutMs?: number;
+}
+/**
+ * Start a local HTTP server and wait for OAuth callback
+ *
+ * Returns the authorization code and state from the callback URL
+ */
+export declare function startCallbackServer(options?: CallbackServerOptions): Promise<CallbackResult>;
+/**
+ * Get the callback URL for the OAuth flow
+ *
+ * Must be called after starting the server to get the actual port
+ */
+export declare function getCallbackUrl(server: http.Server): string;
+//# sourceMappingURL=oauth-callback-server.d.ts.map

package/dist/utils/oauth-callback-server.js

@@ -0,0 +1,156 @@
+/**
+ * Local HTTP server for OAuth callback handling.
+ *
+ * Creates a temporary server on localhost to receive the OAuth redirect.
+ * Implements AUTH-5: Local callback server for OAuth redirect
+ */
+import * as http from 'http';
+import { URL } from 'url';
+/**
+ * Start a local HTTP server and wait for OAuth callback
+ *
+ * Returns the authorization code and state from the callback URL
+ */
+export async function startCallbackServer(options = {}) {
+    const { port = 0, timeoutMs = 120000 } = options; // Default 2 minute timeout
+    return new Promise((resolve, reject) => {
+        let timeout;
+        const server = http.createServer((req, res) => {
+            // Only handle GET requests to the callback path
+            if (req.method !== 'GET' || !req.url) {
+                res.writeHead(404);
+                res.end('Not Found');
+                return;
+            }
+            try {
+                // Parse the callback URL
+                const address = server.address();
+                const port = address && typeof address !== 'string' ? address.port : 3000;
+                const callbackUrl = new URL(req.url, `http://localhost:${port}`);
+                const code = callbackUrl.searchParams.get('code');
+                const state = callbackUrl.searchParams.get('state');
+                const error = callbackUrl.searchParams.get('error');
+                const errorDescription = callbackUrl.searchParams.get('error_description');
+                // Handle OAuth errors
+                if (error) {
+                    const message = errorDescription || error;
+                    res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+                    res.end(`
+            <!DOCTYPE html>
+            <html>
+              <head>
+                <meta charset="utf-8">
+                <title>Authentication Failed</title>
+                <style>
+                  body { font-family: system-ui; max-width: 600px; margin: 100px auto; padding: 20px; }
+                  .error { color: #c00; }
+                </style>
+              </head>
+              <body>
+                <h1 class="error">Authentication Failed</h1>
+                <p>${escapeHtml(message)}</p>
+                <p>You can close this window and try again.</p>
+              </body>
+            </html>
+          `);
+                    clearTimeout(timeout);
+                    server.close();
+                    reject(new Error(`OAuth error: ${message}`));
+                    return;
+                }
+                // Validate required parameters
+                if (!code || !state) {
+                    res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+                    res.end(`
+            <!DOCTYPE html>
+            <html>
+              <head>
+                <meta charset="utf-8">
+                <title>Invalid Callback</title>
+                <style>
+                  body { font-family: system-ui; max-width: 600px; margin: 100px auto; padding: 20px; }
+                  .error { color: #c00; }
+                </style>
+              </head>
+              <body>
+                <h1 class="error">Invalid Callback</h1>
+                <p>Missing required parameters (code or state).</p>
+                <p>You can close this window and try again.</p>
+              </body>
+            </html>
+          `);
+                    clearTimeout(timeout);
+                    server.close();
+                    reject(new Error('Invalid callback: missing code or state'));
+                    return;
+                }
+                // Success response
+                res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+                res.end(`
+          <!DOCTYPE html>
+          <html>
+            <head>
+              <meta charset="utf-8">
+              <title>Authentication Successful</title>
+              <style>
+                body { font-family: system-ui; max-width: 600px; margin: 100px auto; padding: 20px; }
+                .success { color: #0a0; }
+              </style>
+            </head>
+            <body>
+              <h1 class="success">✓ Authentication Successful</h1>
+              <p>You can close this window and return to the terminal.</p>
+            </body>
+          </html>
+        `);
+                // Close server and resolve with callback data
+                clearTimeout(timeout);
+                server.close();
+                resolve({ code, state });
+            }
+            catch (err) {
+                res.writeHead(500, { 'Content-Type': 'text/plain' });
+                res.end('Internal Server Error');
+                clearTimeout(timeout);
+                server.close();
+                reject(err);
+            }
+        });
+        // Set timeout
+        timeout = setTimeout(() => {
+            server.close();
+            reject(new Error('OAuth callback timeout: no response received within 2 minutes'));
+        }, timeoutMs);
+        // Handle server errors
+        server.on('error', (err) => {
+            clearTimeout(timeout);
+            reject(err);
+        });
+        // Start listening on specified port (0 = random available port)
+        server.listen(port, 'localhost');
+    });
+}
+/**
+ * Get the callback URL for the OAuth flow
+ *
+ * Must be called after starting the server to get the actual port
+ */
+export function getCallbackUrl(server) {
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        throw new Error('Server is not listening on a network address');
+    }
+    return `http://localhost:${address.port}/callback`;
+}
+/**
+ * Simple HTML escaping to prevent XSS in error messages
+ */
+function escapeHtml(str) {
+    return str
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#039;');
+}
+//# sourceMappingURL=oauth-callback-server.js.map

package/dist/utils/oauth-flow.d.ts

@@ -0,0 +1,22 @@
+/**
+ * OAuth flow orchestration for WorkOS AuthKit.
+ *
+ * Coordinates browser launch, callback server, and token exchange.
+ * Implements AUTH-24: OAuth flow orchestration
+ */
+export interface OAuthResult {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+}
+/**
+ * Execute the full OAuth flow:
+ * 1. Start local callback server
+ * 2. Generate authorization URL with PKCE
+ * 3. Open browser for user authentication
+ * 4. Wait for callback with authorization code
+ * 5. Exchange code for tokens via WorkOS SDK
+ * 6. Store tokens securely
+ */
+export declare function executeOAuthFlow(): Promise<OAuthResult>;
+//# sourceMappingURL=oauth-flow.d.ts.map

package/dist/utils/oauth-flow.js

@@ -0,0 +1,120 @@
+/**
+ * OAuth flow orchestration for WorkOS AuthKit.
+ *
+ * Coordinates browser launch, callback server, and token exchange.
+ * Implements AUTH-24: OAuth flow orchestration
+ */
+import { randomBytes } from 'crypto';
+import { ConvexHttpClient } from 'convex/browser';
+import { startCallbackServer } from './oauth-callback-server.js';
+import { openBrowserWithFallback } from './browser-launch.js';
+import { storeTokens } from './token-storage.js';
+import { getConvexUrl } from '../config.js';
+import { api } from '../convex.js';
+const WORKOS_CLIENT_ID = 'client_01KCM6WPYX201P7DRV5DHF4TR7';
+const WORKOS_AUTHORIZE_URL = 'https://api.workos.com/user_management/authorize';
+/**
+ * Execute the full OAuth flow:
+ * 1. Start local callback server
+ * 2. Generate authorization URL with PKCE
+ * 3. Open browser for user authentication
+ * 4. Wait for callback with authorization code
+ * 5. Exchange code for tokens via WorkOS SDK
+ * 6. Store tokens securely
+ */
+export async function executeOAuthFlow() {
+    // Generate PKCE code verifier and challenge
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = await generateCodeChallenge(codeVerifier);
+    const state = generateState();
+    console.log('Starting authentication flow...');
+    // Start local callback server on port 3010 (WorkOS requires pre-configured redirect URI)
+    const redirectUri = 'http://localhost:3010/callback';
+    const callbackPromise = startCallbackServer({ port: 3010, timeoutMs: 120000 });
+    // Build authorization URL
+    const authUrl = buildAuthorizationUrl({
+        clientId: WORKOS_CLIENT_ID,
+        redirectUri,
+        state,
+        codeChallenge,
+    });
+    // Open browser for user authentication
+    await openBrowserWithFallback(authUrl);
+    console.log('Waiting for authentication in browser...');
+    // Wait for OAuth callback
+    const { code, state: returnedState } = await callbackPromise;
+    // Verify state to prevent CSRF attacks
+    if (state !== returnedState) {
+        throw new Error('Invalid state parameter: possible CSRF attack');
+    }
+    console.log('Authentication successful, exchanging code for tokens...');
+    // Exchange authorization code for tokens via Convex action (server-side WorkOS call)
+    const client = new ConvexHttpClient(getConvexUrl());
+    const result = await client.action(api.lib.authActions.exchangeAuthorizationCode, {
+        code,
+        codeVerifier,
+    });
+    if (!result.success) {
+        throw new Error(`Token exchange failed: ${result.error}`);
+    }
+    const { accessToken, refreshToken, expiresAt } = result;
+    // Store tokens securely
+    const tokens = {
+        accessToken,
+        refreshToken,
+        expiresAt,
+    };
+    await storeTokens(tokens);
+    console.log('✓ Authentication complete!');
+    return {
+        accessToken,
+        refreshToken,
+        expiresAt,
+    };
+}
+/**
+ * Build the WorkOS authorization URL
+ */
+function buildAuthorizationUrl(params) {
+    const url = new URL(WORKOS_AUTHORIZE_URL);
+    url.searchParams.set('client_id', params.clientId);
+    url.searchParams.set('redirect_uri', params.redirectUri);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('state', params.state);
+    url.searchParams.set('code_challenge', params.codeChallenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+    url.searchParams.set('scope', 'openid profile email offline_access');
+    url.searchParams.set('provider', 'authkit');
+    return url.toString();
+}
+/**
+ * Generate a random code verifier for PKCE
+ */
+function generateCodeVerifier() {
+    return base64UrlEncode(randomBytes(32));
+}
+/**
+ * Generate code challenge from verifier using SHA-256
+ */
+async function generateCodeChallenge(verifier) {
+    const { createHash } = await import('crypto');
+    const hash = createHash('sha256').update(verifier).digest();
+    return base64UrlEncode(hash);
+}
+/**
+ * Generate a random state parameter for CSRF protection
+ */
+function generateState() {
+    return base64UrlEncode(randomBytes(16));
+}
+/**
+ * Base64 URL-safe encoding (without padding)
+ */
+function base64UrlEncode(buffer) {
+    return buffer
+        .toString('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=/g, '');
+}
+//# sourceMappingURL=oauth-flow.js.map

package/dist/utils/project-discovery.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Represents a configured dotrequirements project
+ */
+export interface DotreqProject {
+    /** Absolute path to the project root directory */
+    path: string;
+    /** Project ID from .env.local */
+    projectId: string;
+    /** Project secret from .env.local */
+    projectSecret: string;
+}
+/**
+ * Result of project discovery - either a single project or multiple projects
+ */
+export type ProjectDiscoveryResult = {
+    type: 'none';
+    message: string;
+} | {
+    type: 'single';
+    project: DotreqProject;
+} | {
+    type: 'multiple';
+    projects: DotreqProject[];
+};
+/**
+ * Check if a directory is a configured dotrequirements project
+ * A project is configured if:
+ * 1. It has a package.json that includes "dotreq" (in dependencies or devDependencies)
+ * 2. It has a .env.local with DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET
+ */
+export declare function isConfiguredProject(dir: string): DotreqProject | null;
+/**
+ * Find all configured dotrequirements projects within a directory tree
+ * Searches recursively, respecting ignore patterns
+ */
+export declare function findConfiguredProjects(startDir: string): Promise<DotreqProject[]>;
+/**
+ * Discover dotrequirements project(s) from the MCP working directory
+ * Implements the 4-case discovery logic:
+ * 1. No configured projects → error message
+ * 2. Working directory itself is configured → use it
+ * 3. Exactly one child is configured → use it
+ * 4. Multiple children configured → return all with projectId parameter support
+ */
+export declare function discoverProjects(workingDir?: string): Promise<ProjectDiscoveryResult>;
+/**
+ * Resolve a single project from discovery result
+ * If projectId is provided and multiple projects exist, returns the matching project
+ * Otherwise returns the single project or throws an error
+ */
+export declare function resolveProject(result: ProjectDiscoveryResult, projectId?: string): DotreqProject;
+/**
+ * Convenience function to discover and resolve a single project
+ * Combines discoverProjects() and resolveProject() for common use case
+ */
+export declare function getProject(workingDir?: string, projectId?: string): Promise<DotreqProject>;
+//# sourceMappingURL=project-discovery.d.ts.map

package/dist/utils/project-discovery.js

@@ -0,0 +1,146 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { glob } from 'glob';
+/**
+ * Check if a directory is a configured dotrequirements project
+ * A project is configured if:
+ * 1. It has a package.json that includes "dotreq" (in dependencies or devDependencies)
+ * 2. It has a .env.local with DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET
+ */
+export function isConfiguredProject(dir) {
+    const pkgPath = path.join(dir, 'package.json');
+    const envPath = path.join(dir, '.env.local');
+    // Check for package.json with dotreq
+    if (!fs.existsSync(pkgPath)) {
+        return null;
+    }
+    try {
+        const pkgContent = fs.readFileSync(pkgPath, 'utf-8');
+        // Look for "dotreq" anywhere in the file (flexible matching)
+        if (!pkgContent.includes('dotreq')) {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    // Check for .env.local with required vars
+    if (!fs.existsSync(envPath)) {
+        return null;
+    }
+    let projectId;
+    let projectSecret;
+    try {
+        const envContent = fs.readFileSync(envPath, '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, '');
+            }
+            if (trimmed.startsWith('DOTREQUIREMENTS_PROJECT_SECRET=')) {
+                projectSecret = trimmed.split('=')[1]?.trim().replace(/['"]/g, '');
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    if (!projectId || !projectSecret) {
+        return null;
+    }
+    return {
+        path: dir,
+        projectId,
+        projectSecret,
+    };
+}
+/**
+ * Find all configured dotrequirements projects within a directory tree
+ * Searches recursively, respecting ignore patterns
+ */
+export async function findConfiguredProjects(startDir) {
+    const projects = [];
+    // Find all package.json files, but allow .env.local despite being in .gitignore
+    const packageJsonFiles = await glob('**/package.json', {
+        cwd: startDir,
+        absolute: true,
+        ignore: ['**/node_modules/**', '**/dist/**', '**/.git/**', '**/build/**'],
+    });
+    for (const pkgPath of packageJsonFiles) {
+        const dir = path.dirname(pkgPath);
+        const project = isConfiguredProject(dir);
+        if (project) {
+            projects.push(project);
+        }
+    }
+    return projects;
+}
+/**
+ * Discover dotrequirements project(s) from the MCP working directory
+ * Implements the 4-case discovery logic:
+ * 1. No configured projects → error message
+ * 2. Working directory itself is configured → use it
+ * 3. Exactly one child is configured → use it
+ * 4. Multiple children configured → return all with projectId parameter support
+ */
+export async function discoverProjects(workingDir = process.cwd()) {
+    // Case 2: Check if working directory itself is configured
+    const selfProject = isConfiguredProject(workingDir);
+    if (selfProject) {
+        return { type: 'single', project: selfProject };
+    }
+    // Find all configured projects in descendants
+    const childProjects = await findConfiguredProjects(workingDir);
+    // Case 1: No projects found
+    if (childProjects.length === 0) {
+        return {
+            type: 'none',
+            message: `No dotrequirements projects found in ${workingDir} or its children.\n\nA project must have:\n1. package.json with "dotreq" dependency\n2. .env.local with DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET`,
+        };
+    }
+    // Case 3: Exactly one child project
+    if (childProjects.length === 1) {
+        return { type: 'single', project: childProjects[0] };
+    }
+    // Case 4: Multiple child projects
+    return { type: 'multiple', projects: childProjects };
+}
+/**
+ * Resolve a single project from discovery result
+ * If projectId is provided and multiple projects exist, returns the matching project
+ * Otherwise returns the single project or throws an error
+ */
+export function resolveProject(result, projectId) {
+    if (result.type === 'none') {
+        throw new Error(result.message);
+    }
+    if (result.type === 'single') {
+        return result.project;
+    }
+    // Multiple projects case
+    if (!projectId) {
+        const projectList = result.projects
+            .map((p) => {
+            const relativePath = path.relative(process.cwd(), p.path);
+            return `  - ${relativePath || '.'}: ${p.projectId}`;
+        })
+            .join('\n');
+        throw new Error(`Multiple dotrequirements projects found. Please specify projectId parameter:\n\n${projectList}`);
+    }
+    const project = result.projects.find((p) => p.projectId === projectId);
+    if (!project) {
+        const availableIds = result.projects.map((p) => p.projectId).join(', ');
+        throw new Error(`Project "${projectId}" not found. Available projects: ${availableIds}`);
+    }
+    return project;
+}
+/**
+ * Convenience function to discover and resolve a single project
+ * Combines discoverProjects() and resolveProject() for common use case
+ */
+export async function getProject(workingDir, projectId) {
+    const result = await discoverProjects(workingDir);
+    return resolveProject(result, projectId);
+}
+//# sourceMappingURL=project-discovery.js.map

package/dist/utils/project-name.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Detect project name from various sources
+ * Priority: --name flag > package.json > directory name > user prompt
+ */
+export declare function detectProjectName(options: {
+    name?: string;
+}): Promise<string>;
+//# sourceMappingURL=project-name.d.ts.map

package/dist/utils/project-name.js

@@ -0,0 +1,48 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as readline from 'readline';
+/**
+ * Detect project name from various sources
+ * Priority: --name flag > package.json > directory name > user prompt
+ */
+export async function detectProjectName(options) {
+    // 1. Check --name flag
+    if (options.name) {
+        return options.name;
+    }
+    // 2. Try package.json
+    try {
+        const pkgPath = path.join(process.cwd(), 'package.json');
+        const pkgContent = fs.readFileSync(pkgPath, 'utf-8');
+        const pkg = JSON.parse(pkgContent);
+        if (pkg.name) {
+            return pkg.name;
+        }
+    }
+    catch {
+        // Ignore errors - package.json might not exist
+    }
+    // 3. Use directory name
+    const dirName = path.basename(process.cwd());
+    if (dirName && dirName !== '/' && dirName !== '.') {
+        return dirName;
+    }
+    // 4. Fallback to user prompt
+    return await promptForProjectName();
+}
+/**
+ * Prompt user for project name interactively
+ */
+async function promptForProjectName() {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question('Project name: ', (answer) => {
+            rl.close();
+            resolve(answer.trim() || 'my-project');
+        });
+    });
+}
+//# sourceMappingURL=project-name.js.map

package/dist/utils/project-selector.d.ts

@@ -0,0 +1,25 @@
+import { ConvexHttpClient } from 'convex/browser';
+export interface SelectedProject {
+    projectId: string;
+    projectName: string;
+    projectSlug: string | null;
+}
+/**
+ * Prompt user to select a team from their available teams.
+ * Returns the team ID, or null if user cancels.
+ */
+export declare function selectTeam(client: ConvexHttpClient): Promise<string | null>;
+/**
+ * Prompt user to select a project from a team.
+ * Returns the selected project info, or null if user cancels or no projects exist.
+ */
+export declare function selectProject(client: ConvexHttpClient, teamId: string): Promise<SelectedProject | null>;
+/**
+ * Get or create a user-scoped secret for a project.
+ * Returns the secret and whether it was newly created.
+ */
+export declare function getOrCreateProjectSecret(client: ConvexHttpClient, projectId: string): Promise<{
+    secret: string;
+    created: boolean;
+}>;
+//# sourceMappingURL=project-selector.d.ts.map