specweave 0.32.10 → 0.33.3

package/dist/src/utils/platform-utils.js

@@ -0,0 +1,366 @@
+/**
+ * Platform Utilities - Cross-platform OS operations
+ *
+ * Abstracts platform-specific operations for macOS, Linux, and Windows
+ * Enhanced for process lifecycle management with async API, logger injection,
+ * and system notifications
+ */
+import { execSync } from 'child_process';
+import { stat, mkdir, rmdir } from 'fs/promises';
+import { consoleLogger } from './logger.js';
+/**
+ * Gets the current platform
+ */
+export function getCurrentPlatform() {
+    return process.platform;
+}
+/**
+ * Checks if a process exists (cross-platform)
+ *
+ * @param pid - Process ID to check
+ * @returns true if process exists
+ */
+export function checkProcessExists(pid) {
+    try {
+        if (process.platform === 'win32') {
+            const output = execSync(`tasklist /FI "PID eq ${pid}" /NH`, {
+                encoding: 'utf-8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+            return output.includes(String(pid));
+        }
+        else {
+            execSync(`kill -0 ${pid}`, { stdio: 'ignore' });
+            return true;
+        }
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Gets file modification time in seconds since epoch (cross-platform)
+ *
+ * @param filePath - Path to file
+ * @returns Modification time in seconds since epoch
+ */
+export function getFileMtime(filePath) {
+    try {
+        if (process.platform === 'darwin') {
+            const output = execSync(`stat -f %m "${filePath}"`, { encoding: 'utf-8' });
+            return parseInt(output.trim(), 10);
+        }
+        else if (process.platform === 'win32') {
+            const output = execSync(`powershell -Command "(Get-Item '${filePath}').LastWriteTime.ToFileTimeUtc()"`, { encoding: 'utf-8' });
+            const fileTime = parseInt(output.trim(), 10);
+            return Math.floor((fileTime - 116444736000000000) / 10000000);
+        }
+        else {
+            const output = execSync(`stat -c %Y "${filePath}"`, { encoding: 'utf-8' });
+            return parseInt(output.trim(), 10);
+        }
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Kills a process (cross-platform)
+ *
+ * @param pid - Process ID to kill
+ * @param signal - Signal to send (default: SIGTERM)
+ */
+export function killProcess(pid, signal = 'SIGTERM') {
+    try {
+        if (process.platform === 'win32') {
+            execSync(`taskkill /F /PID ${pid}`, { stdio: 'ignore' });
+        }
+        else {
+            process.kill(pid, signal);
+        }
+    }
+    catch {
+        // Process may not exist, ignore
+    }
+}
+/**
+ * Acquires a file lock using atomic directory creation (cross-platform)
+ *
+ * @param lockPath - Path to lock directory
+ * @returns true if lock acquired
+ */
+export function acquireFileLock(lockPath) {
+    const fs = require('fs');
+    try {
+        fs.mkdirSync(lockPath, { recursive: false });
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            return false; // Lock already exists
+        }
+        throw err;
+    }
+}
+/**
+ * Enhanced cross-platform utility functions with async API and logger injection
+ */
+export class PlatformUtils {
+    constructor(options = {}) {
+        this.platform = process.platform;
+        this.logger = options.logger ?? consoleLogger;
+    }
+    /**
+     * Get current platform
+     */
+    getPlatform() {
+        return this.platform;
+    }
+    /**
+     * Check if current platform is Windows
+     */
+    isWindows() {
+        return this.platform === 'win32';
+    }
+    /**
+     * Check if current platform is POSIX (macOS or Linux)
+     */
+    isPosix() {
+        return this.platform === 'darwin' || this.platform === 'linux';
+    }
+    /**
+     * Check if a process exists by PID (async)
+     *
+     * - macOS/Linux: kill -0 $pid (signal 0 = existence check)
+     * - Windows: tasklist /FI "PID eq $pid"
+     *
+     * @param pid Process ID to check
+     * @returns true if process exists, false otherwise
+     */
+    async checkProcessExistsAsync(pid) {
+        try {
+            if (this.isWindows()) {
+                const output = execSync(`tasklist /FI "PID eq ${pid}" /NH`, {
+                    encoding: 'utf-8',
+                    stdio: ['pipe', 'pipe', 'ignore'],
+                    windowsHide: true
+                });
+                return output.includes(pid.toString());
+            }
+            else {
+                // Signal 0 = check existence without actually sending a signal
+                process.kill(pid, 0);
+                return true;
+            }
+        }
+        catch (err) {
+            if (err.code === 'ESRCH') {
+                // No such process
+                return false;
+            }
+            if (err.code === 'EPERM') {
+                // Process exists but we don't have permission to signal it
+                return true;
+            }
+            this.logger.error(`Error checking process ${pid}:`, err);
+            return false;
+        }
+    }
+    /**
+     * Get file modification time (async, uses fs.stat for cross-platform)
+     *
+     * @param path File path
+     * @returns Modification time in seconds since epoch
+     */
+    async getFileMtimeAsync(path) {
+        try {
+            const stats = await stat(path);
+            return Math.floor(stats.mtimeMs / 1000);
+        }
+        catch (err) {
+            this.logger.error(`Error getting mtime for ${path}:`, err);
+            throw err;
+        }
+    }
+    /**
+     * Acquire file lock using atomic mkdir (async)
+     *
+     * @param lockPath Path to lock directory
+     * @param timeoutMs Maximum time to wait for lock (default: 5000ms)
+     * @returns true if lock acquired, false if timeout
+     */
+    async acquireFileLockAsync(lockPath, timeoutMs = 5000) {
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeoutMs) {
+            try {
+                await mkdir(lockPath, { recursive: false });
+                return true; // Lock acquired
+            }
+            catch (err) {
+                if (err.code === 'EEXIST') {
+                    // Lock exists, wait and retry
+                    await new Promise(resolve => setTimeout(resolve, 100));
+                    continue;
+                }
+                this.logger.error(`Error acquiring lock at ${lockPath}:`, err);
+                throw err;
+            }
+        }
+        this.logger.warn(`Lock acquisition timeout after ${timeoutMs}ms: ${lockPath}`);
+        return false;
+    }
+    /**
+     * Release file lock (async)
+     *
+     * @param lockPath Path to lock directory
+     */
+    async releaseFileLockAsync(lockPath) {
+        try {
+            await rmdir(lockPath);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT') {
+                this.logger.error(`Error releasing lock at ${lockPath}:`, err);
+                throw err;
+            }
+        }
+    }
+    /**
+     * Kill process with signal (async)
+     *
+     * @param pid Process ID to kill
+     * @param signal Signal to send (default: SIGTERM)
+     */
+    async killProcessAsync(pid, signal = 'SIGTERM') {
+        try {
+            if (this.isWindows()) {
+                execSync(`taskkill /PID ${pid} /F`, {
+                    stdio: 'ignore',
+                    windowsHide: true
+                });
+                this.logger.debug(`Killed process ${pid} (Windows taskkill /F)`);
+            }
+            else {
+                process.kill(pid, signal);
+                this.logger.debug(`Killed process ${pid} with signal ${signal}`);
+            }
+        }
+        catch (err) {
+            if (err.code === 'ESRCH') {
+                this.logger.debug(`Process ${pid} doesn't exist (already terminated)`);
+                return;
+            }
+            this.logger.error(`Error killing process ${pid}:`, err);
+            throw err;
+        }
+    }
+    /**
+     * Kill process with graceful fallback (SIGTERM → SIGKILL)
+     *
+     * @param pid Process ID to kill
+     * @param gracePeriodMs Time to wait after SIGTERM before SIGKILL (default: 2000ms)
+     */
+    async killProcessGracefully(pid, gracePeriodMs = 2000) {
+        const exists = await this.checkProcessExistsAsync(pid);
+        if (!exists) {
+            this.logger.debug(`Process ${pid} doesn't exist, skipping kill`);
+            return;
+        }
+        try {
+            // Step 1: Send SIGTERM (graceful shutdown)
+            await this.killProcessAsync(pid, 'SIGTERM');
+            this.logger.debug(`Sent SIGTERM to process ${pid}, waiting ${gracePeriodMs}ms`);
+            // Step 2: Wait for grace period
+            await new Promise(resolve => setTimeout(resolve, gracePeriodMs));
+            // Step 3: Check if process still exists
+            const stillExists = await this.checkProcessExistsAsync(pid);
+            if (!stillExists) {
+                this.logger.debug(`Process ${pid} terminated gracefully after SIGTERM`);
+                return;
+            }
+            // Step 4: Force kill with SIGKILL
+            this.logger.warn(`Process ${pid} didn't terminate after SIGTERM, sending SIGKILL`);
+            await this.killProcessAsync(pid, 'SIGKILL');
+            this.logger.debug(`Sent SIGKILL to process ${pid}`);
+        }
+        catch (err) {
+            this.logger.error(`Error during graceful kill of process ${pid}:`, err);
+            throw err;
+        }
+    }
+    /**
+     * Send system notification
+     *
+     * - macOS: osascript (AppleScript)
+     * - Linux: notify-send (if available)
+     * - Windows: PowerShell toast notification
+     *
+     * Fails gracefully if notification system is unavailable
+     *
+     * @param title Notification title
+     * @param body Notification body text
+     */
+    async sendNotification(title, body) {
+        try {
+            if (this.platform === 'darwin') {
+                await this.sendNotificationMacOS(title, body);
+            }
+            else if (this.platform === 'linux') {
+                await this.sendNotificationLinux(title, body);
+            }
+            else if (this.platform === 'win32') {
+                await this.sendNotificationWindows(title, body);
+            }
+            this.logger.debug(`Sent notification: ${title}`);
+        }
+        catch (err) {
+            this.logger.warn(`Failed to send notification "${title}": ${err}`);
+        }
+    }
+    /**
+     * macOS notification using osascript
+     */
+    async sendNotificationMacOS(title, body) {
+        const escapedTitle = title.replace(/"/g, '\\"');
+        const escapedBody = body.replace(/"/g, '\\"');
+        const cmd = `osascript -e 'display notification "${escapedBody}" with title "${escapedTitle}"'`;
+        execSync(cmd, { stdio: 'ignore' });
+    }
+    /**
+     * Linux notification using notify-send
+     */
+    async sendNotificationLinux(title, body) {
+        try {
+            execSync('command -v notify-send', { stdio: 'ignore' });
+            const escapedTitle = title.replace(/"/g, '\\"');
+            const escapedBody = body.replace(/"/g, '\\"');
+            execSync(`notify-send "${escapedTitle}" "${escapedBody}"`, { stdio: 'ignore' });
+        }
+        catch (err) {
+            throw new Error('notify-send not available on this system');
+        }
+    }
+    /**
+     * Windows notification using PowerShell toast
+     */
+    async sendNotificationWindows(title, body) {
+        const escapedTitle = title.replace(/'/g, "''");
+        const escapedBody = body.replace(/'/g, "''");
+        const psScript = `
+      [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null;
+      $template = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02);
+      $xml = [xml]$template.GetXml();
+      $xml.GetElementsByTagName('text')[0].AppendChild($xml.CreateTextNode('${escapedTitle}')) | Out-Null;
+      $xml.GetElementsByTagName('text')[1].AppendChild($xml.CreateTextNode('${escapedBody}')) | Out-Null;
+      $toast = [Windows.UI.Notifications.ToastNotification]::new($xml);
+      [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('SpecWeave').Show($toast);
+    `;
+        execSync(`powershell -Command "${psScript}"`, {
+            stdio: 'ignore',
+            windowsHide: true
+        });
+    }
+}
+// Export singleton instance for convenience
+export const platformUtils = new PlatformUtils();
+//# sourceMappingURL=platform-utils.js.map

package/dist/src/utils/platform-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-utils.js","sourceRoot":"","sources":["../../../src/utils/platform-utils.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/project-resolver.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Project Resolver
+ *
+ * Smart utility that auto-resolves project/board for user stories
+ * based on context analysis:
+ * - Single project → auto-select
+ * - Keyword matching → suggest with confidence
+ * - Cross-cutting detection → split across projects
+ * - Learned patterns from existing specs
+ *
+ * Part of increment 0137: Per-US Project/Board Enforcement
+ *
+ * @module utils/project-resolver
+ * @since v0.34.0
+ */
+import { type ProjectInfo, type BoardInfo } from './structure-level-detector.js';
+import { Logger } from './logger.js';
+import { CrossCuttingDetector, type CrossCuttingResult, type DetectedPattern } from './cross-cutting-detector.js';
+/**
+ * Resolution result for a single user story
+ */
+export interface ProjectResolution {
+    /** Whether project was successfully resolved */
+    resolved: boolean;
+    /** Resolved project ID (if resolved) */
+    projectId?: string;
+    /** Resolved board ID (for 2-level structures) */
+    boardId?: string;
+    /** Confidence level */
+    confidence: 'high' | 'medium' | 'low';
+    /** Reason for resolution decision */
+    reason: string;
+    /** Keywords that matched (if any) */
+    matchedKeywords?: string[];
+}
+/**
+ * Resolution result for an entire increment
+ */
+export interface IncrementResolution {
+    /** Whether this is a cross-project increment */
+    isCrossProject: boolean;
+    /** Default project for USs without explicit assignment */
+    defaultProject: string;
+    /** Default board for 2-level (optional) */
+    defaultBoard?: string;
+    /** Suggested project for each US type */
+    suggestions: Map<string, ProjectResolution>;
+    /** Structure level detected */
+    structureLevel: 1 | 2;
+    /** Cross-cutting detection result (when detected) */
+    crossCuttingResult?: CrossCuttingResult;
+    /** Detected patterns for display/logging */
+    detectedPatterns?: DetectedPattern[];
+}
+/**
+ * Project Resolver
+ *
+ * Resolves project/board context for user stories based on:
+ * 1. Single project auto-selection
+ * 2. Learned patterns from existing specs
+ * 3. Keyword-based matching
+ * 4. Cross-cutting detection
+ */
+export declare class ProjectResolver {
+    private projectRoot;
+    private logger;
+    private structureConfig;
+    private learnedPatterns;
+    private keywordPatterns;
+    private crossCuttingDetector;
+    constructor(projectRoot: string, options?: {
+        logger?: Logger;
+    });
+    /**
+     * Get structure level (1 or 2)
+     */
+    getStructureLevel(): 1 | 2;
+    /**
+     * Get available projects
+     */
+    getProjects(): ProjectInfo[];
+    /**
+     * Get boards for a project (2-level only)
+     */
+    getBoards(projectId: string): BoardInfo[];
+    /**
+     * Learn keyword patterns from existing spec.md files
+     */
+    learnFromExistingSpecs(): Promise<void>;
+    /**
+     * Extract keyword → project patterns from a spec file
+     */
+    private extractPatternsFromSpec;
+    /**
+     * Check if word is in default patterns
+     */
+    private isDefaultPattern;
+    /**
+     * Resolve project for a single user story
+     */
+    resolveForUserStory(usContent: string): ProjectResolution;
+    /**
+     * Map suggested project type (frontend, backend, etc.) to actual project ID
+     */
+    private mapSuggestedTypeToProject;
+    /**
+     * Resolve board for a user story (2-level structures only)
+     */
+    resolveBoard(usContent: string, projectId: string): ProjectResolution;
+    /**
+     * Match content against project keywords
+     */
+    private matchProjectsByKeywords;
+    /**
+     * Resolve project context for an entire increment description
+     */
+    resolveForIncrement(incrementDescription: string): IncrementResolution;
+    /**
+     * Detect if description indicates cross-project work
+     */
+    private detectCrossProject;
+    /**
+     * Check if content matches any keywords
+     */
+    private matchesKeywords;
+    /**
+     * Detect cross-cutting concerns using the integrated detector
+     * Returns full detection result for advanced use cases
+     */
+    detectCrossCuttingConcerns(description: string): CrossCuttingResult;
+    /**
+     * Get the cross-cutting detector instance for direct access
+     */
+    getCrossCuttingDetector(): CrossCuttingDetector;
+    /**
+     * Format available projects for display
+     */
+    formatProjectsForDisplay(): string;
+}
+/**
+ * Create a project resolver instance (sync - no pattern learning)
+ */
+export declare function createProjectResolver(projectRoot: string, options?: {
+    logger?: Logger;
+}): ProjectResolver;
+/**
+ * Create a project resolver instance with pattern learning (async)
+ *
+ * This awaits learnFromExistingSpecs() to ensure patterns are available
+ * before the resolver is used.
+ */
+export declare function createProjectResolverWithPatterns(projectRoot: string, options?: {
+    logger?: Logger;
+}): Promise<ProjectResolver>;
+export type { CrossCuttingResult, DetectedPattern };
+//# sourceMappingURL=project-resolver.d.ts.map

package/dist/src/utils/project-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-resolver.d.ts","sourceRoot":"","sources":["../../../src/utils/project-resolver.ts"],"names":[],"mappings":"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"}