@vibescope/mcp-server 0.0.1

package/dist/utils.d.ts

@@ -0,0 +1,149 @@
+export declare const AGENT_PERSONAS: readonly ["Apex", "Arc", "Atlas", "Blaze", "Bolt", "Byte", "Cipher", "Core", "Dash", "Drift", "Echo", "Edge", "Ember", "Flux", "Forge", "Ghost", "Glitch", "Haze", "Hex", "Ion", "Iris", "Jade", "Jet", "Karma", "Kite", "Lux", "Mako", "Neon", "Nova", "Onyx", "Orbit", "Pixel", "Pulse", "Quest", "Rex", "Rune", "Shade", "Spark", "Storm", "Trace", "Turbo", "Vex", "Volt", "Warp", "Wave", "Zen", "Zero"];
+export type AgentPersona = typeof AGENT_PERSONAS[number];
+export declare const FALLBACK_ACTIVITIES: readonly [{
+    readonly activity: "feature_ideation";
+    readonly title: "Generate feature ideas";
+    readonly description: "Review the codebase and suggest improvements or new features. Use add_idea to record your findings.";
+    readonly prompt: "Explore the codebase, identify areas for improvement, and suggest 2-3 actionable feature ideas using add_idea.";
+}, {
+    readonly activity: "feature_planning";
+    readonly title: "Plan features from ideas";
+    readonly description: "Take raw ideas and develop them into planned features with documentation.";
+    readonly prompt: "Call get_ideas to find ideas with status \"raw\" or \"exploring\". Pick one and develop it: research requirements, identify implementation steps, write a feature spec. Use update_idea to change status to \"planned\" and add a doc_url if you create documentation.";
+}, {
+    readonly activity: "code_review";
+    readonly title: "Code standards review";
+    readonly description: "Check for inconsistencies, missing types, code smells, or patterns that could be improved.";
+    readonly prompt: "Review the codebase for code quality issues. Look for missing types, inconsistent patterns, or technical debt. Log findings with add_idea or add_task.";
+}, {
+    readonly activity: "performance_audit";
+    readonly title: "Performance audit";
+    readonly description: "Identify potential performance bottlenecks or optimization opportunities.";
+    readonly prompt: "Analyze the codebase for performance issues: N+1 queries, unnecessary re-renders, expensive operations. Create tasks for fixes with add_task.";
+}, {
+    readonly activity: "ux_review";
+    readonly title: "UX review";
+    readonly description: "Evaluate user flows and identify usability improvements.";
+    readonly prompt: "Review the UI components and user flows. Identify confusing interactions, missing feedback, or accessibility issues. Log improvements with add_idea.";
+}, {
+    readonly activity: "cost_analysis";
+    readonly title: "Cost analysis";
+    readonly description: "Review infrastructure and API usage for cost optimization opportunities.";
+    readonly prompt: "Analyze the codebase for expensive operations: unnecessary API calls, inefficient queries, large bundle sizes. Suggest cost-saving alternatives with add_idea.";
+}, {
+    readonly activity: "security_review";
+    readonly title: "Security review";
+    readonly description: "Check for common security issues: auth gaps, input validation, data exposure.";
+    readonly prompt: "Review the codebase for security concerns: authentication gaps, missing input validation, sensitive data handling. Create high-priority tasks for issues found.";
+}, {
+    readonly activity: "test_coverage";
+    readonly title: "Test coverage analysis";
+    readonly description: "Find untested code paths and suggest test cases.";
+    readonly prompt: "Identify areas of the codebase with missing or weak test coverage. Create tasks for writing tests using add_task.";
+}, {
+    readonly activity: "documentation_review";
+    readonly title: "Documentation review";
+    readonly description: "Identify missing or outdated documentation.";
+    readonly prompt: "Review existing docs and code comments. Identify gaps, outdated information, or confusing explanations. Log improvements with add_idea.";
+}, {
+    readonly activity: "dependency_audit";
+    readonly title: "Dependency audit";
+    readonly description: "Review dependencies for updates, security issues, or unused packages.";
+    readonly prompt: "Check package.json for outdated dependencies, security vulnerabilities, or unused packages. Create tasks for updates with add_task.";
+}, {
+    readonly activity: "validate_completed_tasks";
+    readonly title: "Validate completed tasks";
+    readonly description: "Review tasks completed by other agents to ensure quality.";
+    readonly prompt: "Call get_tasks_awaiting_validation to find completed tasks that need review. Validate each one by checking the implementation and running tests if applicable.";
+}];
+export type FallbackActivity = typeof FALLBACK_ACTIVITIES[number];
+/**
+ * Get a random fallback activity
+ */
+export declare function getRandomFallbackActivity(): FallbackActivity;
+/**
+ * Select an available persona from the pool (randomly)
+ * @param usedPersonas Set of personas currently in use
+ * @param instanceId The instance ID for fallback naming
+ * @returns The selected persona name
+ */
+export declare function selectPersona(usedPersonas: Set<string>, instanceId: string): string;
+export interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    resetIn: number;
+}
+export declare class RateLimiter {
+    private requests;
+    private readonly maxRequests;
+    private readonly windowMs;
+    constructor(maxRequests?: number, windowMs?: number);
+    check(key: string): RateLimitResult;
+    cleanup(): void;
+    getRequestCount(key: string): number | undefined;
+}
+/**
+ * Check if a task can be validated by the given session
+ * @param task The task to validate
+ * @param validatorSessionId The session trying to validate
+ * @returns Object with canValidate boolean and reason if not allowed
+ */
+export declare function canValidateTask(task: {
+    status: string;
+    validated_at: string | null;
+    working_agent_session_id: string | null;
+}, validatorSessionId: string | null): {
+    canValidate: boolean;
+    reason?: string;
+};
+/**
+ * Check if a task status transition is valid
+ * @param currentStatus Current task status
+ * @param newStatus Desired new status
+ * @returns Object with isValid boolean and reason if not valid
+ */
+export declare function isValidStatusTransition(currentStatus: string, newStatus: string): {
+    isValid: boolean;
+    reason?: string;
+};
+/**
+ * Check if a deployment status transition is valid
+ * @param currentStatus Current deployment status
+ * @param newStatus Desired new status
+ * @returns Object with isValid boolean and reason if not valid
+ */
+export declare function isValidDeploymentStatusTransition(currentStatus: string, newStatus: string): {
+    isValid: boolean;
+    reason?: string;
+};
+/**
+ * Extract project name from a git URL.
+ * Handles various git URL formats:
+ * - https://github.com/user/repo -> repo
+ * - https://github.com/user/repo.git -> repo
+ * - git@github.com:user/repo.git -> repo
+ * - https://gitlab.com/user/repo -> repo
+ * - ssh://git@github.com/user/repo.git -> repo
+ *
+ * @param gitUrl The git URL to parse
+ * @returns The extracted project name, or 'my-project' if parsing fails
+ */
+export declare function extractProjectNameFromGitUrl(gitUrl: string): string;
+/**
+ * Normalize a git URL to a consistent HTTPS format.
+ * - Removes .git suffix
+ * - Converts SSH URLs (git@host:path) to HTTPS format
+ *
+ * Supports GitHub, GitLab, and Bitbucket.
+ *
+ * @param gitUrl The git URL to normalize
+ * @returns The normalized URL, or the original if no normalization needed
+ *
+ * @example
+ * normalizeGitUrl('git@github.com:user/repo.git')
+ * // returns 'https://github.com/user/repo'
+ *
+ * normalizeGitUrl('https://github.com/user/repo.git')
+ * // returns 'https://github.com/user/repo'
+ */
+export declare function normalizeGitUrl(gitUrl: string): string;

package/dist/utils.js

@@ -0,0 +1,317 @@
+// ============================================================================
+// Utilities Module - Extracted from index.ts for testability
+// ============================================================================
+// ============================================================================
+// Agent Persona Pool
+// Short, memorable names for distinguishing agents on the dashboard
+// ============================================================================
+export const AGENT_PERSONAS = [
+    'Apex',
+    'Arc',
+    'Atlas',
+    'Blaze',
+    'Bolt',
+    'Byte',
+    'Cipher',
+    'Core',
+    'Dash',
+    'Drift',
+    'Echo',
+    'Edge',
+    'Ember',
+    'Flux',
+    'Forge',
+    'Ghost',
+    'Glitch',
+    'Haze',
+    'Hex',
+    'Ion',
+    'Iris',
+    'Jade',
+    'Jet',
+    'Karma',
+    'Kite',
+    'Lux',
+    'Mako',
+    'Neon',
+    'Nova',
+    'Onyx',
+    'Orbit',
+    'Pixel',
+    'Pulse',
+    'Quest',
+    'Rex',
+    'Rune',
+    'Shade',
+    'Spark',
+    'Storm',
+    'Trace',
+    'Turbo',
+    'Vex',
+    'Volt',
+    'Warp',
+    'Wave',
+    'Zen',
+    'Zero',
+];
+// ============================================================================
+// Fallback Activities for Idle Agents
+// Suggested productive activities when no pending tasks exist
+// ============================================================================
+export const FALLBACK_ACTIVITIES = [
+    {
+        activity: 'feature_ideation',
+        title: 'Generate feature ideas',
+        description: 'Review the codebase and suggest improvements or new features. Use add_idea to record your findings.',
+        prompt: 'Explore the codebase, identify areas for improvement, and suggest 2-3 actionable feature ideas using add_idea.',
+    },
+    {
+        activity: 'feature_planning',
+        title: 'Plan features from ideas',
+        description: 'Take raw ideas and develop them into planned features with documentation.',
+        prompt: 'Call get_ideas to find ideas with status "raw" or "exploring". Pick one and develop it: research requirements, identify implementation steps, write a feature spec. Use update_idea to change status to "planned" and add a doc_url if you create documentation.',
+    },
+    {
+        activity: 'code_review',
+        title: 'Code standards review',
+        description: 'Check for inconsistencies, missing types, code smells, or patterns that could be improved.',
+        prompt: 'Review the codebase for code quality issues. Look for missing types, inconsistent patterns, or technical debt. Log findings with add_idea or add_task.',
+    },
+    {
+        activity: 'performance_audit',
+        title: 'Performance audit',
+        description: 'Identify potential performance bottlenecks or optimization opportunities.',
+        prompt: 'Analyze the codebase for performance issues: N+1 queries, unnecessary re-renders, expensive operations. Create tasks for fixes with add_task.',
+    },
+    {
+        activity: 'ux_review',
+        title: 'UX review',
+        description: 'Evaluate user flows and identify usability improvements.',
+        prompt: 'Review the UI components and user flows. Identify confusing interactions, missing feedback, or accessibility issues. Log improvements with add_idea.',
+    },
+    {
+        activity: 'cost_analysis',
+        title: 'Cost analysis',
+        description: 'Review infrastructure and API usage for cost optimization opportunities.',
+        prompt: 'Analyze the codebase for expensive operations: unnecessary API calls, inefficient queries, large bundle sizes. Suggest cost-saving alternatives with add_idea.',
+    },
+    {
+        activity: 'security_review',
+        title: 'Security review',
+        description: 'Check for common security issues: auth gaps, input validation, data exposure.',
+        prompt: 'Review the codebase for security concerns: authentication gaps, missing input validation, sensitive data handling. Create high-priority tasks for issues found.',
+    },
+    {
+        activity: 'test_coverage',
+        title: 'Test coverage analysis',
+        description: 'Find untested code paths and suggest test cases.',
+        prompt: 'Identify areas of the codebase with missing or weak test coverage. Create tasks for writing tests using add_task.',
+    },
+    {
+        activity: 'documentation_review',
+        title: 'Documentation review',
+        description: 'Identify missing or outdated documentation.',
+        prompt: 'Review existing docs and code comments. Identify gaps, outdated information, or confusing explanations. Log improvements with add_idea.',
+    },
+    {
+        activity: 'dependency_audit',
+        title: 'Dependency audit',
+        description: 'Review dependencies for updates, security issues, or unused packages.',
+        prompt: 'Check package.json for outdated dependencies, security vulnerabilities, or unused packages. Create tasks for updates with add_task.',
+    },
+    {
+        activity: 'validate_completed_tasks',
+        title: 'Validate completed tasks',
+        description: 'Review tasks completed by other agents to ensure quality.',
+        prompt: 'Call get_tasks_awaiting_validation to find completed tasks that need review. Validate each one by checking the implementation and running tests if applicable.',
+    },
+];
+/**
+ * Get a random fallback activity
+ */
+export function getRandomFallbackActivity() {
+    const index = Math.floor(Math.random() * FALLBACK_ACTIVITIES.length);
+    return FALLBACK_ACTIVITIES[index];
+}
+/**
+ * Select an available persona from the pool (randomly)
+ * @param usedPersonas Set of personas currently in use
+ * @param instanceId The instance ID for fallback naming
+ * @returns The selected persona name
+ */
+export function selectPersona(usedPersonas, instanceId) {
+    const availablePersonas = AGENT_PERSONAS.filter((p) => !usedPersonas.has(p));
+    if (availablePersonas.length === 0) {
+        return `Agent-${instanceId.slice(0, 6)}`;
+    }
+    const randomIndex = Math.floor(Math.random() * availablePersonas.length);
+    return availablePersonas[randomIndex];
+}
+export class RateLimiter {
+    requests = new Map();
+    maxRequests;
+    windowMs;
+    constructor(maxRequests = 60, windowMs = 60000) {
+        this.maxRequests = maxRequests;
+        this.windowMs = windowMs;
+    }
+    check(key) {
+        const now = Date.now();
+        const record = this.requests.get(key);
+        // If no record or window expired, create new record
+        if (!record || now >= record.resetAt) {
+            this.requests.set(key, { count: 1, resetAt: now + this.windowMs });
+            return { allowed: true, remaining: this.maxRequests - 1, resetIn: this.windowMs };
+        }
+        // Check if limit exceeded
+        if (record.count >= this.maxRequests) {
+            return { allowed: false, remaining: 0, resetIn: record.resetAt - now };
+        }
+        // Increment count
+        record.count++;
+        return { allowed: true, remaining: this.maxRequests - record.count, resetIn: record.resetAt - now };
+    }
+    // Clean up expired entries periodically
+    cleanup() {
+        const now = Date.now();
+        for (const [key, record] of this.requests.entries()) {
+            if (now >= record.resetAt) {
+                this.requests.delete(key);
+            }
+        }
+    }
+    // Expose for testing
+    getRequestCount(key) {
+        return this.requests.get(key)?.count;
+    }
+}
+// ============================================================================
+// Task Validation Helpers
+// ============================================================================
+/**
+ * Check if a task can be validated by the given session
+ * @param task The task to validate
+ * @param validatorSessionId The session trying to validate
+ * @returns Object with canValidate boolean and reason if not allowed
+ */
+export function canValidateTask(task, validatorSessionId) {
+    if (task.status !== 'completed') {
+        return { canValidate: false, reason: 'Can only validate completed tasks' };
+    }
+    if (task.validated_at) {
+        return { canValidate: false, reason: 'Task has already been validated' };
+    }
+    // Note: Self-validation check would go here if we tracked who completed the task
+    // Currently, working_agent_session_id is cleared on completion
+    return { canValidate: true };
+}
+/**
+ * Check if a task status transition is valid
+ * @param currentStatus Current task status
+ * @param newStatus Desired new status
+ * @returns Object with isValid boolean and reason if not valid
+ */
+export function isValidStatusTransition(currentStatus, newStatus) {
+    const validTransitions = {
+        pending: ['in_progress', 'cancelled'],
+        in_progress: ['completed', 'pending', 'cancelled'],
+        completed: ['in_progress'], // Can reopen via validation failure
+        cancelled: ['pending'], // Can reactivate cancelled tasks
+    };
+    const allowed = validTransitions[currentStatus];
+    if (!allowed) {
+        return { isValid: false, reason: `Unknown current status: ${currentStatus}` };
+    }
+    if (!allowed.includes(newStatus)) {
+        return {
+            isValid: false,
+            reason: `Cannot transition from '${currentStatus}' to '${newStatus}'. Valid transitions: ${allowed.join(', ')}`
+        };
+    }
+    return { isValid: true };
+}
+/**
+ * Check if a deployment status transition is valid
+ * @param currentStatus Current deployment status
+ * @param newStatus Desired new status
+ * @returns Object with isValid boolean and reason if not valid
+ */
+export function isValidDeploymentStatusTransition(currentStatus, newStatus) {
+    const validTransitions = {
+        pending: ['validating', 'failed'], // Can claim validation or cancel
+        validating: ['ready', 'failed'], // Validation passes or fails
+        ready: ['deploying', 'failed'], // Start deployment or cancel
+        deploying: ['deployed', 'failed'], // Deployment succeeds or fails
+        deployed: [], // Terminal state
+        failed: [], // Terminal state (create new deployment to retry)
+    };
+    const allowed = validTransitions[currentStatus];
+    if (!allowed) {
+        return { isValid: false, reason: `Unknown current status: ${currentStatus}` };
+    }
+    if (!allowed.includes(newStatus)) {
+        return {
+            isValid: false,
+            reason: `Cannot transition deployment from '${currentStatus}' to '${newStatus}'. Valid transitions: ${allowed.length ? allowed.join(', ') : 'none (terminal state)'}`
+        };
+    }
+    return { isValid: true };
+}
+// ============================================================================
+// Git URL Parsing
+// ============================================================================
+/**
+ * Extract project name from a git URL.
+ * Handles various git URL formats:
+ * - https://github.com/user/repo -> repo
+ * - https://github.com/user/repo.git -> repo
+ * - git@github.com:user/repo.git -> repo
+ * - https://gitlab.com/user/repo -> repo
+ * - ssh://git@github.com/user/repo.git -> repo
+ *
+ * @param gitUrl The git URL to parse
+ * @returns The extracted project name, or 'my-project' if parsing fails
+ */
+export function extractProjectNameFromGitUrl(gitUrl) {
+    if (!gitUrl) {
+        return 'my-project';
+    }
+    // Match the last path segment, optionally removing .git suffix
+    // Works for:
+    // - /user/repo (https URLs)
+    // - /user/repo.git
+    // - :user/repo (ssh URLs like git@github.com:user/repo)
+    // - :user/repo.git
+    const match = gitUrl.match(/[/:]([^/:]+?)(?:\.git)?$/);
+    if (match && match[1]) {
+        return match[1];
+    }
+    return 'my-project';
+}
+/**
+ * Normalize a git URL to a consistent HTTPS format.
+ * - Removes .git suffix
+ * - Converts SSH URLs (git@host:path) to HTTPS format
+ *
+ * Supports GitHub, GitLab, and Bitbucket.
+ *
+ * @param gitUrl The git URL to normalize
+ * @returns The normalized URL, or the original if no normalization needed
+ *
+ * @example
+ * normalizeGitUrl('git@github.com:user/repo.git')
+ * // returns 'https://github.com/user/repo'
+ *
+ * normalizeGitUrl('https://github.com/user/repo.git')
+ * // returns 'https://github.com/user/repo'
+ */
+export function normalizeGitUrl(gitUrl) {
+    if (!gitUrl) {
+        return gitUrl;
+    }
+    return gitUrl
+        .replace(/\.git$/, '')
+        .replace(/^git@github\.com:/, 'https://github.com/')
+        .replace(/^git@gitlab\.com:/, 'https://gitlab.com/')
+        .replace(/^git@bitbucket\.org:/, 'https://bitbucket.org/');
+}

package/dist/utils.test.d.ts

@@ -0,0 +1 @@
+export {};