commandmate 0.1.10 → 0.1.11

package/dist/cli/utils/input-validators.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * Input Validators
+ * Issue #136: Phase 1 - Foundation
+ *
+ * Provides input validation functions for worktree-related operations.
+ * These validators are critical for security (command injection prevention).
+ *
+ * @module input-validators
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_BRANCH_NAME_LENGTH = exports.BRANCH_NAME_PATTERN = exports.MAX_ISSUE_NO = void 0;
+exports.validateIssueNo = validateIssueNo;
+exports.validateBranchName = validateBranchName;
+exports.validatePortNumber = validatePortNumber;
+exports.isValidIssueNo = isValidIssueNo;
+exports.validateIssueNoResult = validateIssueNoResult;
+exports.isValidBranchName = isValidBranchName;
+/**
+ * Maximum allowed issue number (2^31 - 1)
+ * NTH-SEC-002: Prevent integer overflow
+ */
+exports.MAX_ISSUE_NO = 2147483647;
+/**
+ * Branch name whitelist pattern
+ * MF-SEC-001: Only allow safe characters to prevent command injection
+ * Allowed: a-z, A-Z, 0-9, underscore, hyphen, forward slash
+ */
+exports.BRANCH_NAME_PATTERN = /^[a-zA-Z0-9_/-]+$/;
+/**
+ * Maximum branch name length
+ * Prevents DoS via overly long input
+ */
+exports.MAX_BRANCH_NAME_LENGTH = 255;
+/**
+ * Validate issue number
+ * SEC-001: Strict positive integer validation
+ *
+ * @param issueNo - The issue number to validate
+ * @throws Error with code 'INVALID_ISSUE_NO' if not a valid integer
+ * @throws Error with code 'ISSUE_NO_OUT_OF_RANGE' if out of range
+ *
+ * @example
+ * ```typescript
+ * validateIssueNo(135); // OK
+ * validateIssueNo('135'); // throws INVALID_ISSUE_NO
+ * validateIssueNo(-1); // throws ISSUE_NO_OUT_OF_RANGE
+ * ```
+ */
+function validateIssueNo(issueNo) {
+    if (typeof issueNo !== 'number' ||
+        !Number.isInteger(issueNo) ||
+        !Number.isFinite(issueNo)) {
+        throw new Error('INVALID_ISSUE_NO');
+    }
+    if (issueNo <= 0 || issueNo > exports.MAX_ISSUE_NO) {
+        throw new Error('ISSUE_NO_OUT_OF_RANGE');
+    }
+}
+/**
+ * Validate branch name
+ * MF-SEC-001: Whitelist validation to prevent command injection
+ *
+ * @param branchName - The branch name to validate
+ * @throws Error with code 'INVALID_BRANCH_NAME' if contains invalid characters
+ * @throws Error with code 'BRANCH_NAME_TOO_LONG' if exceeds max length
+ *
+ * @example
+ * ```typescript
+ * validateBranchName('feature/136-worktree'); // OK
+ * validateBranchName('feature`rm -rf /`'); // throws INVALID_BRANCH_NAME
+ * ```
+ */
+function validateBranchName(branchName) {
+    if (!branchName || !exports.BRANCH_NAME_PATTERN.test(branchName)) {
+        throw new Error('INVALID_BRANCH_NAME');
+    }
+    if (branchName.length > exports.MAX_BRANCH_NAME_LENGTH) {
+        throw new Error('BRANCH_NAME_TOO_LONG');
+    }
+}
+/**
+ * Validate port number
+ * SEC-003: Port validation for worktree servers
+ *
+ * @param port - The port number to validate
+ * @param minPort - Minimum allowed port (default: 1024, non-privileged)
+ * @param maxPort - Maximum allowed port (default: 65535)
+ * @throws Error with code 'INVALID_PORT' if not a valid port number
+ *
+ * @example
+ * ```typescript
+ * validatePortNumber(3001); // OK
+ * validatePortNumber(80); // throws INVALID_PORT (privileged)
+ * ```
+ */
+function validatePortNumber(port, minPort = 1024, maxPort = 65535) {
+    if (typeof port !== 'number' ||
+        !Number.isInteger(port) ||
+        !Number.isFinite(port)) {
+        throw new Error('INVALID_PORT');
+    }
+    if (port < minPort || port > maxPort) {
+        throw new Error('INVALID_PORT');
+    }
+}
+/**
+ * Type guard for checking if a value is a valid issue number
+ *
+ * @param value - Value to check
+ * @returns true if value is a valid issue number
+ */
+function isValidIssueNo(value) {
+    try {
+        validateIssueNo(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate issue number and return result (for CLI commands)
+ * Issue #136: CLI-friendly validation that returns result instead of throwing
+ *
+ * @param issueNo - The issue number to validate
+ * @returns Validation result with error message if invalid
+ */
+function validateIssueNoResult(issueNo) {
+    try {
+        validateIssueNo(issueNo);
+        return { valid: true };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        switch (message) {
+            case 'INVALID_ISSUE_NO':
+                return { valid: false, error: 'Issue number must be a positive integer' };
+            case 'ISSUE_NO_OUT_OF_RANGE':
+                return { valid: false, error: `Issue number must be between 1 and ${exports.MAX_ISSUE_NO}` };
+            default:
+                return { valid: false, error: 'Invalid issue number' };
+        }
+    }
+}
+/**
+ * Type guard for checking if a value is a valid branch name
+ *
+ * @param value - Value to check
+ * @returns true if value is a valid branch name
+ */
+function isValidBranchName(value) {
+    if (typeof value !== 'string') {
+        return false;
+    }
+    try {
+        validateBranchName(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cli/utils/install-context.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Install Context Utility
+ * Issue #136: DRY refactoring - extract common install detection functions
+ *
+ * This module provides centralized functions for detecting the install type
+ * (global vs local npm install) and resolving configuration directories.
+ *
+ * Extracted from env-setup.ts to solve circular import issues and follow DRY principle.
+ *
+ * @module install-context
+ */
+/**
+ * Check if running as global npm package
+ * Issue #119: Determine .env location based on install type
+ * Issue #136: Extracted to avoid circular imports
+ *
+ * @returns true if running as global npm package
+ *
+ * @example
+ * ```typescript
+ * if (isGlobalInstall()) {
+ *   // Use ~/.commandmate for config
+ * } else {
+ *   // Use current working directory
+ * }
+ * ```
+ */
+export declare function isGlobalInstall(): boolean;
+/**
+ * Get the config directory path
+ * Issue #119: Returns ~/.commandmate for global, cwd for local
+ * Issue #125: Added symlink resolution for security (path traversal protection)
+ * Issue #136: Extracted to avoid circular imports
+ *
+ * @returns Path to config directory (absolute, with symlinks resolved)
+ * @throws Error if config directory resolves outside home directory (for global install)
+ *
+ * @example
+ * ```typescript
+ * const configDir = getConfigDir();
+ * // Global: /Users/username/.commandmate
+ * // Local: /path/to/project (resolved from symlinks)
+ * ```
+ */
+export declare function getConfigDir(): string;
+/**
+ * Ensure the config directory exists with proper permissions
+ * Issue #136: Utility for creating config directory if needed
+ *
+ * @returns Path to config directory (created if needed)
+ */
+export declare function ensureConfigDir(): string;
+//# sourceMappingURL=install-context.d.ts.map

package/dist/cli/utils/install-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-context.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/install-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAYzC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAqBrC;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAUxC"}

package/dist/cli/utils/install-context.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * Install Context Utility
+ * Issue #136: DRY refactoring - extract common install detection functions
+ *
+ * This module provides centralized functions for detecting the install type
+ * (global vs local npm install) and resolving configuration directories.
+ *
+ * Extracted from env-setup.ts to solve circular import issues and follow DRY principle.
+ *
+ * @module install-context
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isGlobalInstall = isGlobalInstall;
+exports.getConfigDir = getConfigDir;
+exports.ensureConfigDir = ensureConfigDir;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
+/**
+ * Check if running as global npm package
+ * Issue #119: Determine .env location based on install type
+ * Issue #136: Extracted to avoid circular imports
+ *
+ * @returns true if running as global npm package
+ *
+ * @example
+ * ```typescript
+ * if (isGlobalInstall()) {
+ *   // Use ~/.commandmate for config
+ * } else {
+ *   // Use current working directory
+ * }
+ * ```
+ */
+function isGlobalInstall() {
+    // Check if running from global node_modules
+    // Global installs typically have paths like:
+    // - /usr/local/lib/node_modules/
+    // - /Users/xxx/.npm-global/lib/node_modules/
+    // - C:\Users\xxx\AppData\Roaming\npm\node_modules\
+    const currentPath = (0, path_1.dirname)(__dirname);
+    return (currentPath.includes('/lib/node_modules/') ||
+        currentPath.includes('\\node_modules\\') ||
+        currentPath.includes('/node_modules/commandmate'));
+}
+/**
+ * Get the config directory path
+ * Issue #119: Returns ~/.commandmate for global, cwd for local
+ * Issue #125: Added symlink resolution for security (path traversal protection)
+ * Issue #136: Extracted to avoid circular imports
+ *
+ * @returns Path to config directory (absolute, with symlinks resolved)
+ * @throws Error if config directory resolves outside home directory (for global install)
+ *
+ * @example
+ * ```typescript
+ * const configDir = getConfigDir();
+ * // Global: /Users/username/.commandmate
+ * // Local: /path/to/project (resolved from symlinks)
+ * ```
+ */
+function getConfigDir() {
+    if (isGlobalInstall()) {
+        const configDir = (0, path_1.join)((0, os_1.homedir)(), '.commandmate');
+        // Verify config directory is within home directory (security check)
+        // Only validate if the directory exists (it may not exist yet during init)
+        if ((0, fs_1.existsSync)(configDir)) {
+            const realPath = (0, fs_1.realpathSync)(configDir);
+            const realHome = (0, fs_1.realpathSync)((0, os_1.homedir)());
+            if (!realPath.startsWith(realHome)) {
+                throw new Error(`Security error: Config directory ${configDir} is outside home directory`);
+            }
+            return realPath;
+        }
+        return configDir;
+    }
+    // Local install - resolve symlinks in cwd
+    const cwd = process.cwd();
+    return (0, fs_1.realpathSync)(cwd);
+}
+/**
+ * Ensure the config directory exists with proper permissions
+ * Issue #136: Utility for creating config directory if needed
+ *
+ * @returns Path to config directory (created if needed)
+ */
+function ensureConfigDir() {
+    const configDir = isGlobalInstall()
+        ? (0, path_1.join)((0, os_1.homedir)(), '.commandmate')
+        : process.cwd();
+    if (!(0, fs_1.existsSync)(configDir)) {
+        (0, fs_1.mkdirSync)(configDir, { recursive: true, mode: 0o700 });
+    }
+    return getConfigDir();
+}

package/dist/cli/utils/pid-manager.d.ts

@@ -1,6 +1,7 @@
 /**
  * PID File Manager
  * Issue #96: npm install CLI support
+ * Issue #136: Phase 2 - Task 2.4 - Added factory functions for Issue number support
  * SF-1: SRP - Separated from daemon.ts for single responsibility
  * MF-SEC-2: TOCTOU protection with O_EXCL atomic writes
  */
@@ -39,4 +40,37 @@ export declare class PidManager {
      */
     isProcessRunning(): boolean;
 }
+/**
+ * Factory function to create PidManager instance
+ * Issue #136: Uses PidPathResolver for path resolution
+ *
+ * @param issueNo - Optional issue number for worktree-specific PID
+ * @returns PidManager instance
+ *
+ * @example
+ * ```typescript
+ * // Main server PID manager
+ * const mainManager = createPidManager();
+ *
+ * // Worktree-specific PID manager
+ * const issueManager = createPidManager(135);
+ * ```
+ */
+export declare function createPidManager(issueNo?: number): PidManager;
+/**
+ * Factory function to create PidManager for a specific issue
+ * Issue #136: Convenience function for worktree PID management
+ *
+ * @param issueNo - Issue number
+ * @returns PidManager instance for the specified issue
+ *
+ * @example
+ * ```typescript
+ * const manager = createIssuePidManager(135);
+ * if (manager.isProcessRunning()) {
+ *   console.log('Worktree server for issue #135 is running');
+ * }
+ * ```
+ */
+export declare function createIssuePidManager(issueNo: number): PidManager;
 //# sourceMappingURL=pid-manager.d.ts.map

package/dist/cli/utils/pid-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pid-manager.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/pid-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH;;GAEG;AACH,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAAX,WAAW,EAAE,MAAM;IAEhD;;OAEG;IACH,MAAM,IAAI,OAAO;IAIjB;;;OAGG;IACH,OAAO,IAAI,MAAM,GAAG,IAAI;IAmBxB;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAwB9B;;OAEG;IACH,SAAS,IAAI,IAAI;IAUjB;;;;;OAKG;IACH,gBAAgB,IAAI,OAAO;CAmB5B"}
+{"version":3,"file":"pid-manager.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/pid-manager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH;;GAEG;AACH,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAAX,WAAW,EAAE,MAAM;IAEhD;;OAEG;IACH,MAAM,IAAI,OAAO;IAIjB;;;OAGG;IACH,OAAO,IAAI,MAAM,GAAG,IAAI;IAmBxB;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAwB9B;;OAEG;IACH,SAAS,IAAI,IAAI;IAUjB;;;;;OAKG;IACH,gBAAgB,IAAI,OAAO;CAmB5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU,CAI7D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAEjE"}

package/dist/cli/utils/pid-manager.js

@@ -2,12 +2,16 @@
 /**
  * PID File Manager
  * Issue #96: npm install CLI support
+ * Issue #136: Phase 2 - Task 2.4 - Added factory functions for Issue number support
  * SF-1: SRP - Separated from daemon.ts for single responsibility
  * MF-SEC-2: TOCTOU protection with O_EXCL atomic writes
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PidManager = void 0;
+exports.createPidManager = createPidManager;
+exports.createIssuePidManager = createIssuePidManager;
 const fs_1 = require("fs");
+const resource_resolvers_1 = require("./resource-resolvers");
 /**
  * PID file manager for daemon process tracking
  */
@@ -109,3 +113,42 @@ class PidManager {
     }
 }
 exports.PidManager = PidManager;
+/**
+ * Factory function to create PidManager instance
+ * Issue #136: Uses PidPathResolver for path resolution
+ *
+ * @param issueNo - Optional issue number for worktree-specific PID
+ * @returns PidManager instance
+ *
+ * @example
+ * ```typescript
+ * // Main server PID manager
+ * const mainManager = createPidManager();
+ *
+ * // Worktree-specific PID manager
+ * const issueManager = createPidManager(135);
+ * ```
+ */
+function createPidManager(issueNo) {
+    const resolver = new resource_resolvers_1.PidPathResolver();
+    const pidPath = resolver.resolve(issueNo);
+    return new PidManager(pidPath);
+}
+/**
+ * Factory function to create PidManager for a specific issue
+ * Issue #136: Convenience function for worktree PID management
+ *
+ * @param issueNo - Issue number
+ * @returns PidManager instance for the specified issue
+ *
+ * @example
+ * ```typescript
+ * const manager = createIssuePidManager(135);
+ * if (manager.isProcessRunning()) {
+ *   console.log('Worktree server for issue #135 is running');
+ * }
+ * ```
+ */
+function createIssuePidManager(issueNo) {
+    return createPidManager(issueNo);
+}

package/dist/cli/utils/port-allocator.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Port Allocator
+ * Issue #136: Phase 1 - Foundation
+ *
+ * Provides automatic port allocation for worktree servers.
+ * SF-SEC-002: Implements MAX_WORKTREES limit to prevent port exhaustion attacks.
+ *
+ * @module port-allocator
+ */
+/**
+ * Default port range for worktree servers
+ * Main server uses 3000, worktrees use 3001-3100
+ */
+export declare const DEFAULT_PORT_RANGE: {
+    readonly min: 3001;
+    readonly max: 3100;
+};
+/**
+ * Maximum number of concurrent worktree servers
+ * SF-SEC-002: Prevents port exhaustion attacks
+ */
+export declare const MAX_WORKTREES = 10;
+/**
+ * Port range configuration
+ */
+export interface PortRange {
+    min: number;
+    max: number;
+}
+/**
+ * Port allocator for managing worktree server ports
+ *
+ * @example
+ * ```typescript
+ * const allocator = new PortAllocator();
+ * const port = await allocator.findAvailablePort();
+ * allocator.markAllocated(port);
+ * // ... start server on port ...
+ * allocator.release(port);
+ * ```
+ */
+export declare class PortAllocator {
+    private static instance;
+    private readonly range;
+    private readonly allocatedPorts;
+    private readonly issuePortMap;
+    constructor(range?: PortRange);
+    /**
+     * Get singleton instance
+     * Issue #136: Singleton pattern for CLI commands
+     */
+    static getInstance(): PortAllocator;
+    /**
+     * Allocate a port for a specific issue (synchronous, deterministic)
+     * Issue #136: Simple port allocation based on issue number
+     *
+     * @param issueNo - Issue number
+     * @returns Allocated port number
+     */
+    allocate(issueNo: number): number;
+    /**
+     * Find an available port in the configured range
+     *
+     * @returns Available port number
+     * @throws AppError with code PORT_EXHAUSTED if no ports available
+     * @throws AppError with code MAX_WORKTREES_EXCEEDED if limit reached
+     */
+    findAvailablePort(): Promise<number>;
+    /**
+     * Check if a specific port is available
+     *
+     * @param port - Port number to check
+     * @returns true if port is available
+     */
+    isPortAvailable(port: number): Promise<boolean>;
+    /**
+     * Mark a port as allocated
+     *
+     * @param port - Port number to mark as allocated
+     */
+    markAllocated(port: number): void;
+    /**
+     * Release an allocated port
+     *
+     * @param port - Port number to release
+     */
+    release(port: number): void;
+    /**
+     * Get the count of allocated ports
+     */
+    getAllocatedCount(): number;
+    /**
+     * Check if a port is currently allocated (in-memory tracking)
+     *
+     * @param port - Port number to check
+     * @returns true if port is allocated
+     */
+    isAllocated(port: number): boolean;
+    /**
+     * Get all allocated ports
+     */
+    getAllocatedPorts(): number[];
+}
+/**
+ * Create a port allocator with default settings
+ */
+export declare function createPortAllocator(range?: PortRange): PortAllocator;
+//# sourceMappingURL=port-allocator.d.ts.map

package/dist/cli/utils/port-allocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-allocator.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/port-allocator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;CAGrB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAc;IAC7C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;gBAEvC,KAAK,GAAE,SAA8B;IAMjD;;;OAGG;IACH,MAAM,CAAC,WAAW,IAAI,aAAa;IAOnC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAcjC;;;;;;OAMG;IACG,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IA4B1C;;;;;OAKG;IACG,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBrD;;;;OAIG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIjC;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI3B;;OAEG;IACH,iBAAiB,IAAI,MAAM;IAI3B;;;;;OAKG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIlC;;OAEG;IACH,iBAAiB,IAAI,MAAM,EAAE;CAG9B;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,aAAa,CAEpE"}