kiro-spec-engine 1.20.5 → 1.21.1

package/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.21.1] - 2026-02-01
+
+### Fixed
+- **Test Suite Compatibility**: Fixed test failures introduced in v1.21.0
+  - Updated tests to reflect optional version field (now defaults to "1.0")
+  - Added `skipFilesystemValidation` option to `loadConfig()` for testing scenarios
+  - Mocked `_validateRepositoryPath` in handler tests to avoid filesystem dependency
+  - All 1697 tests now pass successfully
+
+### Technical Details
+- Modified `ConfigManager.loadConfig()` to accept optional `skipFilesystemValidation` parameter
+- Updated test expectations for optional version field validation
+- Enhanced test isolation by mocking filesystem validation in unit tests
+- No functional changes to production code behavior
+
+## [1.21.0] - 2026-02-01
+
+### Added
+- **Manual Configuration Support**: Users can now manually create and edit `.kiro/project-repos.json` without relying solely on auto-scan
+  - Version field is now optional (defaults to "1.0" if omitted)
+  - Only `name` and `path` are required for each repository entry
+  - All other fields (`remote`, `defaultBranch`, `description`, `tags`, `group`, `parent`) are optional
+  - Filesystem validation ensures paths exist and contain valid `.git` directories
+  - Clear, actionable error messages guide users in fixing configuration issues
+  - Comprehensive documentation in `docs/multi-repo-management-guide.md` with examples and troubleshooting
+
+### Changed
+- **Enhanced Validation**: Configuration validation now performs filesystem checks when loading from disk
+  - Validates that repository paths exist on the filesystem
+  - Verifies each path contains a `.git` directory (not file)
+  - Detects and rejects Git worktrees with helpful error messages
+  - Reports all validation errors together (not just the first one)
+  - Maintains backward compatibility with all v1.18.0+ configurations
+
+### Fixed
+- **Manual Configuration Rejection**: Fixed issue where manually-created configurations were rejected even when valid
+  - Users can now manually curate repository lists
+  - Users can remove false positives from auto-scan results
+  - Users can add repositories that weren't auto-detected
+  - Minimal configurations (name + path only) now pass validation
+  - User-reported issue: 8 real Git repositories rejected by validation
+
+### Documentation
+- Added comprehensive "Manual Configuration" section to multi-repo management guide
+- Documented minimal configuration format with examples
+- Added troubleshooting guide for common validation errors
+- Included step-by-step instructions for creating manual configurations
+
 ## [1.20.5] - 2026-02-01 🔥 HOTFIX
 
 ### Fixed

package/docs/multi-repo-management-guide.md

@@ -193,6 +193,260 @@ Paths can be specified as:
   "path": "packages/frontend"   // Unix/Mac
   ```
 
+## Manual Configuration
+
+### Overview
+
+Starting with v1.21.0, you can manually create and edit the `.kiro/project-repos.json` configuration file without relying solely on `kse repo init`. This is useful for:
+
+- Curating a specific list of repositories
+- Removing false positives from auto-scan
+- Adding repositories that weren't auto-detected
+- Creating configurations for repositories that don't exist yet
+
+### Minimal Configuration Format
+
+The simplest valid configuration requires only `name` and `path` for each repository:
+
+```json
+{
+  "repositories": [
+    {
+      "name": "my-repo",
+      "path": "./my-repo"
+    },
+    {
+      "name": "another-repo",
+      "path": "./another-repo"
+    }
+  ]
+}
+```
+
+**Key points:**
+- The `version` field is optional (defaults to "1.0")
+- Only `name` and `path` are required for each repository
+- All other fields (`remote`, `defaultBranch`, `description`, `tags`, `group`) are optional
+
+### Complete Configuration Example
+
+For more detailed configurations, you can include all optional fields:
+
+```json
+{
+  "version": "1.0",
+  "repositories": [
+    {
+      "name": "frontend",
+      "path": "./packages/frontend",
+      "remote": "https://github.com/user/frontend.git",
+      "defaultBranch": "main",
+      "description": "React frontend application",
+      "tags": ["ui", "react"],
+      "group": "client"
+    },
+    {
+      "name": "backend",
+      "path": "./packages/backend",
+      "remote": "https://github.com/user/backend.git",
+      "defaultBranch": "develop",
+      "description": "Node.js API server",
+      "tags": ["api", "nodejs"],
+      "group": "server"
+    },
+    {
+      "name": "local-only",
+      "path": "./local-repo"
+    }
+  ],
+  "groups": {
+    "client": {
+      "description": "Client-side applications"
+    },
+    "server": {
+      "description": "Server-side services"
+    }
+  }
+}
+```
+
+### Field Requirements
+
+#### Required Fields
+- **name**: Unique identifier for the repository
+  - Must contain only alphanumeric characters, hyphens, underscores, and dots
+  - Examples: `"frontend"`, `"my-repo"`, `"repo.1"`, `".github"`
+
+- **path**: Path to the repository directory
+  - Can be relative (e.g., `"./my-repo"`) or absolute (e.g., `"/home/user/my-repo"`)
+  - Must point to an existing directory containing a `.git` directory
+  - Cannot point to a Git worktree (`.git` file instead of directory)
+
+#### Optional Fields
+- **remote**: Git remote URL (can be omitted for local-only repositories)
+- **defaultBranch**: Default branch name (e.g., `"main"`, `"develop"`)
+- **description**: Human-readable description
+- **tags**: Array of tags for categorization
+- **group**: Group name for logical organization
+- **parent**: Parent repository path (for nested repositories)
+
+### Validation Rules
+
+When you manually create or edit the configuration, `kse` validates:
+
+1. **File Format**: Must be valid JSON
+2. **Structure**: Must have a `repositories` array
+3. **Required Fields**: Each repository must have `name` and `path`
+4. **Path Existence**: Each path must exist on the filesystem
+5. **Git Repository**: Each path must contain a `.git` directory (not file)
+6. **No Duplicates**: Repository names and paths must be unique
+7. **No Worktrees**: Paths cannot point to Git worktrees
+
+### Creating a Manual Configuration
+
+**Step 1: Create the directory structure**
+
+```bash
+mkdir -p .kiro
+```
+
+**Step 2: Create the configuration file**
+
+Create `.kiro/project-repos.json` with your repositories:
+
+```json
+{
+  "repositories": [
+    {
+      "name": "repo1",
+      "path": "./repo1"
+    },
+    {
+      "name": "repo2",
+      "path": "./repo2"
+    }
+  ]
+}
+```
+
+**Step 3: Verify the configuration**
+
+```bash
+kse repo status
+```
+
+If there are validation errors, `kse` will display clear error messages:
+
+```
+Error: Repository path validation failed
+  - Repository "repo1": path "./repo1" does not exist. Please check the path is correct.
+  - Repository "repo2": path "./repo2" is not a Git repository (no .git directory found). Please ensure this is a Git repository.
+```
+
+### Editing an Existing Configuration
+
+You can manually edit the auto-generated configuration to:
+
+**Remove repositories:**
+```json
+{
+  "repositories": [
+    // Remove unwanted entries from this array
+    {
+      "name": "keep-this",
+      "path": "./keep-this"
+    }
+    // Deleted: { "name": "remove-this", "path": "./remove-this" }
+  ]
+}
+```
+
+**Add new repositories:**
+```json
+{
+  "repositories": [
+    {
+      "name": "existing-repo",
+      "path": "./existing-repo"
+    },
+    {
+      "name": "new-repo",
+      "path": "./new-repo"
+    }
+  ]
+}
+```
+
+**Simplify to minimal format:**
+```json
+{
+  "repositories": [
+    {
+      "name": "repo1",
+      "path": "./repo1"
+      // Removed: remote, defaultBranch, description, tags, group
+    }
+  ]
+}
+```
+
+### Troubleshooting
+
+#### Error: "path does not exist"
+
+**Cause**: The specified path doesn't exist on the filesystem.
+
+**Solution**: Check the path is correct and the directory exists:
+```bash
+ls -la ./my-repo  # Unix/Mac
+dir .\my-repo     # Windows
+```
+
+#### Error: "is not a Git repository"
+
+**Cause**: The path exists but doesn't contain a `.git` directory.
+
+**Solution**: Initialize the directory as a Git repository:
+```bash
+cd ./my-repo
+git init
+```
+
+#### Error: "appears to be a Git worktree"
+
+**Cause**: The path contains a `.git` file instead of a directory (Git worktree).
+
+**Solution**: Use the main repository path instead of the worktree path:
+```json
+{
+  "name": "my-repo",
+  "path": "./main-repo"  // Use main repo, not worktree
+}
+```
+
+#### Error: "Duplicate repository name"
+
+**Cause**: Two repositories have the same name.
+
+**Solution**: Ensure each repository has a unique name:
+```json
+{
+  "repositories": [
+    { "name": "repo1", "path": "./path1" },
+    { "name": "repo2", "path": "./path2" }  // Changed from "repo1"
+  ]
+}
+```
+
+#### Error: "Configuration file contains invalid JSON"
+
+**Cause**: The JSON syntax is incorrect (missing comma, bracket, etc.).
+
+**Solution**: Validate your JSON using a JSON validator or IDE:
+- Check for missing commas between array elements
+- Ensure all brackets and braces are properly closed
+- Use a JSON formatter to identify syntax errors
+
 ## Nested Repository Support
 
 ### Overview

package/lib/repo/config-manager.js

@@ -46,10 +46,13 @@ class ConfigManager {
 
   /**
    * Load and validate configuration from disk
+   * @param {Object} options - Load options
+   * @param {boolean} options.skipFilesystemValidation - Skip filesystem validation (for testing)
    * @returns {Promise<Object>} The loaded and validated configuration
    * @throws {ConfigError} If file is missing, invalid JSON, or validation fails
    */
-  async loadConfig() {
+  async loadConfig(options = {}) {
+    const { skipFilesystemValidation = false } = options;
     const configPath = this.getConfigPath();
 
     // Check if file exists
@@ -78,8 +81,8 @@ class ConfigManager {
       );
     }
 
-    // Validate configuration
-    const validation = this.validateConfig(configData);
+    // Validate configuration structure
+    const validation = this.validateConfig(configData, { validateFilesystem: false });
     if (!validation.valid) {
       throw new ConfigError(
         'Configuration validation failed',
@@ -87,6 +90,24 @@ class ConfigManager {
       );
     }
 
+    // Perform filesystem validation for each repository (unless skipped)
+    if (!skipFilesystemValidation) {
+      const filesystemErrors = [];
+      for (const repo of configData.repositories) {
+        if (repo.path && repo.name) {
+          const pathErrors = await this._validateRepositoryPath(repo.path, repo.name);
+          filesystemErrors.push(...pathErrors);
+        }
+      }
+
+      if (filesystemErrors.length > 0) {
+        throw new ConfigError(
+          'Repository path validation failed',
+          { errors: filesystemErrors }
+        );
+      }
+    }
+
     return configData;
   }
 
@@ -127,9 +148,11 @@ class ConfigManager {
   /**
    * Validate configuration structure and content
    * @param {Object} config - The configuration object to validate
+   * @param {Object} options - Validation options
+   * @param {boolean} options.validateFilesystem - Whether to validate paths on filesystem (default: false)
    * @returns {{valid: boolean, errors: string[]}} Validation result
    */
-  validateConfig(config) {
+  validateConfig(config, options = {}) {
     const errors = [];
 
     // Check if config is an object
@@ -137,14 +160,13 @@ class ConfigManager {
       return { valid: false, errors: ['Configuration must be an object'] };
     }
 
-    // Validate version field
-    if (!config.version) {
-      errors.push('Missing required field: version');
-    } else if (typeof config.version !== 'string') {
+    // Validate version field (optional, defaults to '1.0')
+    const version = config.version || '1.0';
+    if (typeof version !== 'string') {
       errors.push('Field "version" must be a string');
-    } else if (!this._isSupportedVersion(config.version)) {
+    } else if (!this._isSupportedVersion(version)) {
       errors.push(
-        `Unsupported configuration version: ${config.version}. ` +
+        `Unsupported configuration version: ${version}. ` +
         'Please upgrade to the latest version of kse.'
       );
     }
@@ -165,7 +187,7 @@ class ConfigManager {
     const repoPaths = [];
 
     config.repositories.forEach((repo, index) => {
-      const repoErrors = this._validateRepository(repo, index, config.repositories);
+      const repoErrors = this._validateRepository(repo, index, config.repositories, options.validateFilesystem);
       errors.push(...repoErrors);
 
       // Collect names and paths for duplicate checking
@@ -454,6 +476,94 @@ class ConfigManager {
     return validPattern.test(name);
   }
 
+  /**
+   * Check if a path is a valid Git repository
+   * @private
+   * @param {string} dirPath - Directory path to check
+   * @returns {Promise<boolean>} True if path contains a .git directory (not file)
+   */
+  async _isGitRepository(dirPath) {
+    try {
+      const gitPath = path.join(dirPath, '.git');
+      const stats = await fs.stat(gitPath);
+      // Return true only if .git is a directory (not a file, which indicates a Git worktree)
+      return stats.isDirectory();
+    } catch (error) {
+      // Path doesn't exist, no permissions, or other error
+      return false;
+    }
+  }
+
+  /**
+   * Validate that a repository path exists and is a valid Git repository
+   * @private
+   * @param {string} repoPath - Repository path to validate
+   * @param {string} repoName - Repository name (for error messages)
+   * @returns {Promise<string[]>} Array of validation errors
+   */
+  async _validateRepositoryPath(repoPath, repoName) {
+    const errors = [];
+    
+    // Resolve path relative to project root
+    const absolutePath = path.isAbsolute(repoPath) 
+      ? repoPath 
+      : path.join(this.projectRoot, repoPath);
+
+    // Check if path exists
+    try {
+      await fs.access(absolutePath);
+    } catch (error) {
+      errors.push(
+        `Repository "${repoName}": path "${repoPath}" does not exist. ` +
+        'Please check the path is correct.'
+      );
+      return errors; // Can't continue validation if path doesn't exist
+    }
+
+    // Check if it's a directory
+    try {
+      const stats = await fs.stat(absolutePath);
+      if (!stats.isDirectory()) {
+        errors.push(
+          `Repository "${repoName}": path "${repoPath}" is not a directory.`
+        );
+        return errors;
+      }
+    } catch (error) {
+      errors.push(
+        `Repository "${repoName}": cannot access path "${repoPath}". ${error.message}`
+      );
+      return errors;
+    }
+
+    // Check if .git exists
+    const gitPath = path.join(absolutePath, '.git');
+    try {
+      const gitStats = await fs.stat(gitPath);
+      
+      if (gitStats.isFile()) {
+        // .git is a file, which indicates a Git worktree
+        errors.push(
+          `Repository "${repoName}": path "${repoPath}" appears to be a Git worktree (not supported). ` +
+          'Please use the main repository path instead.'
+        );
+      } else if (!gitStats.isDirectory()) {
+        errors.push(
+          `Repository "${repoName}": path "${repoPath}" has an invalid .git entry.`
+        );
+      }
+      // If .git is a directory, it's valid - no error
+    } catch (error) {
+      // .git doesn't exist
+      errors.push(
+        `Repository "${repoName}": path "${repoPath}" is not a Git repository (no .git directory found). ` +
+        'Please ensure this is a Git repository.'
+      );
+    }
+
+    return errors;
+  }
+
   /**
    * Check if configuration version is supported
    * @private

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-spec-engine",
-  "version": "1.20.5",
+  "version": "1.21.1",
   "description": "kiro-spec-engine (kse) - A CLI tool and npm package for spec-driven development with AI coding assistants. NOT the Kiro IDE desktop application.",
   "main": "index.js",
   "bin": {