feat(config): add permission cleanup and merging functionality

Author: WitMiao

.claude/plan/permission-cleanup-task.md

@@ -0,0 +1,40 @@
+# Permission Cleanup Task Plan
+
+## Context
+ZCF v2.0 之前的版本中，用户配置可能包含无效的权限项 `"mcp__.*"`（已被官方确认无法生效），以及冗余的权限项（如同时存在 `Bash` 和 `Bash(*)`）。需要在配置合并时自动清理这些无效和冗余的权限。
+
+## Implementation Plan
+
+### 1. Create Permission Cleanup Utility
+- **File**: `src/utils/permission-cleaner.ts`
+- **Functions**:
+  - `cleanupPermissions()`: Core cleanup logic
+  - `mergeAndCleanPermissions()`: Wrapper for merge operations
+- **Cleanup Rules**:
+  - Remove literal `"mcp__.*"` (invalid from v2.0 and earlier)
+  - Remove permissions that start with template permissions (e.g., remove `Bash(*)` if template has `Bash`)
+
+### 2. Update Config Merge Logic
+- **File**: `src/utils/config.ts`
+- **Function**: `mergeSettingsFile()`
+- **Change**: Replace `mergeArraysUnique()` with `mergeAndCleanPermissions()`
+
+### 3. Update Simple Config Import
+- **File**: `src/utils/simple-config.ts`  
+- **Function**: `importRecommendedPermissions()`
+- **Change**: Apply cleanup when importing permissions
+
+### 4. Test Coverage
+- Verify cleanup of `"mcp__.*"` literal
+- Verify removal of redundant permissions
+- Ensure valid permissions are preserved
+
+## Expected Results
+- Automatic cleanup of invalid `"mcp__.*"` permissions during config updates
+- Prevention of permission redundancy (e.g., both `Bash` and `Bash(*)`)
+- Clean and effective permission lists
+
+## Files Modified
+1. `/Users/miaoda/Documents/code/zcf/src/utils/permission-cleaner.ts` (created)
+2. `/Users/miaoda/Documents/code/zcf/src/utils/config.ts` (modified)
+3. `/Users/miaoda/Documents/code/zcf/src/utils/simple-config.ts` (modified)

src/index.ts

@@ -5,4 +5,5 @@ export { getPlatform, commandExists } from './utils/platform'
 export * from './utils/installer'
 export * from './utils/config'
 export * from './utils/mcp'
-export { importRecommendedEnv, importRecommendedPermissions, openSettingsJson } from './utils/simple-config'
+export { importRecommendedEnv, importRecommendedPermissions, openSettingsJson } from './utils/simple-config'
+export { cleanupPermissions, mergeAndCleanPermissions } from './utils/permission-cleaner'

src/utils/config.ts

@@ -12,9 +12,10 @@ import {
   type CopyDirOptions 
 } from './fs-operations';
 import { readJsonConfig, writeJsonConfig } from './json-config';
-import { deepMerge, mergeArraysUnique } from './object-utils';
+import { deepMerge } from './object-utils';
 import type { ClaudeSettings, ApiConfig } from '../types/config';
 import { readZcfConfig } from './zcf-config';
+import { mergeAndCleanPermissions } from './permission-cleaner';
 export type { ApiConfig } from '../types/config';
 
 export function ensureClaudeDir() {
@@ -211,11 +212,11 @@ export function mergeSettingsFile(templatePath: string, targetPath: string): voi
     // Ensure user's env vars are preserved
     mergedSettings.env = mergedEnv;
 
-    // Handle permissions.allow array specially to avoid duplicates
+    // Handle permissions.allow array specially to avoid duplicates and clean invalid entries
     if (mergedSettings.permissions && mergedSettings.permissions.allow) {
-      mergedSettings.permissions.allow = mergeArraysUnique(
-        templateSettings.permissions?.allow || [],
-        existingSettings.permissions?.allow || []
+      mergedSettings.permissions.allow = mergeAndCleanPermissions(
+        templateSettings.permissions?.allow,
+        existingSettings.permissions?.allow
       );
     }
 

src/utils/permission-cleaner.ts

@@ -0,0 +1,69 @@
+/**
+ * Clean up and deduplicate permissions array
+ * Removes invalid and redundant permissions based on template
+ */
+
+/**
+ * Clean up permissions array by removing invalid and redundant entries
+ * @param templatePermissions - Permissions from template (source of truth)
+ * @param userPermissions - User's existing permissions
+ * @returns Cleaned permissions array
+ */
+export function cleanupPermissions(templatePermissions: string[], userPermissions: string[]): string[] {
+  // Create a set for template permissions for O(1) lookup
+  const templateSet = new Set(templatePermissions);
+
+  // Filter user permissions
+  const cleanedPermissions = userPermissions.filter((permission) => {
+    // Remove literal "mcp__.*" (invalid wildcard from v2.0 and earlier)
+    if (['mcp__.*', 'mcp__*', 'mcp__(*)'].includes(permission)) {
+      return false;
+    }
+
+    // Check if this permission is redundant (covered by a template permission)
+    // For example, if template has "Bash", remove "Bash(*)", "Bash(mkdir:*)", etc.
+    for (const templatePerm of templatePermissions) {
+      // Skip if it's the exact same permission (will be handled by mergeArraysUnique)
+      if (permission === templatePerm) {
+        continue;
+      }
+
+      // Check if user permission starts with template permission followed by "("
+      // This catches patterns like "Bash(*)", "Bash(mkdir:*)" when template has "Bash"
+      if (permission.startsWith(templatePerm)) {
+        return false; // Remove this redundant permission
+      }
+    }
+
+    // Keep all other permissions
+    return true;
+  });
+
+  // Merge template and cleaned user permissions, removing duplicates
+  const merged = [...templateSet];
+
+  for (const permission of cleanedPermissions) {
+    if (!templateSet.has(permission)) {
+      merged.push(permission);
+    }
+  }
+
+  return merged;
+}
+
+/**
+ * Merge and clean permissions arrays
+ * Combines template and user permissions while removing invalid/redundant entries
+ * @param templatePermissions - Permissions from template
+ * @param userPermissions - User's existing permissions
+ * @returns Merged and cleaned permissions array
+ */
+export function mergeAndCleanPermissions(
+  templatePermissions: string[] | undefined,
+  userPermissions: string[] | undefined
+): string[] {
+  const template = templatePermissions || [];
+  const user = userPermissions || [];
+
+  return cleanupPermissions(template, user);
+}

src/utils/simple-config.ts

@@ -5,6 +5,7 @@ import { SETTINGS_FILE, CLAUDE_DIR } from '../constants.js';
 import { ensureDir } from './fs-operations.js';
 import { exec } from 'tinyexec';
 import { getPlatform } from './platform.js';
+import { mergeAndCleanPermissions } from './permission-cleaner.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -54,8 +55,18 @@ export async function importRecommendedPermissions(): Promise<void> {
   const templateSettings = getTemplateSettings();
   const currentSettings = loadCurrentSettings();
 
-  // Merge permissions
-  currentSettings.permissions = templateSettings.permissions;
+  // Merge permissions with cleanup
+  if (templateSettings.permissions && templateSettings.permissions.allow) {
+    currentSettings.permissions = {
+      ...templateSettings.permissions,
+      allow: mergeAndCleanPermissions(
+        templateSettings.permissions.allow,
+        currentSettings.permissions?.allow
+      )
+    };
+  } else {
+    currentSettings.permissions = templateSettings.permissions;
+  }
 
   saveSettings(currentSettings);
 }