fix(session-defaults): tighten clear semantics and profile handling

Make session_clear_defaults clear only the active profile by default, add\nexplicit profile targeting, and reserve all=true for full global+profile\nclears with guardrails.\n\nFix the session e2e profile flow to create named profiles intentionally and\nextract shared profile-name normalization to a single utility used by both\nconfig-store and project-config.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: cameroncooke

docs/TOOLS-CLI.md

@@ -189,4 +189,4 @@ XcodeBuildMCP provides 73 canonical tools organized into 13 workflow groups.
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-17T21:23:33.036Z UTC*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-17T21:48:36.993Z UTC*

docs/TOOLS.md

@@ -205,4 +205,4 @@ This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP prov
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-17T21:23:33.036Z UTC*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-17T21:48:36.993Z UTC*

src/mcp/tools/session-management/__tests__/session_clear_defaults.test.ts

@@ -49,25 +49,62 @@ describe('session-clear-defaults tool', () => {
       expect(current.arch).toBe('arm64');
     });
 
-    it('should clear all when all=true', async () => {
+    it('should clear all profiles only when all=true', async () => {
       sessionStore.setActiveProfile('ios');
       sessionStore.setDefaults({ scheme: 'IOS' });
       sessionStore.setActiveProfile(null);
       const result = await sessionClearDefaultsLogic({ all: true });
       expect(result.isError).toBe(false);
-      expect(result.content[0].text).toBe('Session defaults cleared');
+      expect(result.content[0].text).toBe('All session defaults cleared');
 
       const current = sessionStore.getAll();
       expect(Object.keys(current).length).toBe(0);
       expect(sessionStore.listProfiles()).toEqual([]);
       expect(sessionStore.getActiveProfile()).toBeNull();
     });
 
-    it('should clear all when no params provided', async () => {
+    it('should clear only active profile when no params provided', async () => {
+      sessionStore.setActiveProfile('ios');
+      sessionStore.setDefaults({ scheme: 'IOS', projectPath: '/ios/project.xcodeproj' });
+      sessionStore.setActiveProfile(null);
+      sessionStore.setDefaults({ scheme: 'Global' });
+      sessionStore.setActiveProfile('ios');
+
       const result = await sessionClearDefaultsLogic({});
       expect(result.isError).toBe(false);
-      const current = sessionStore.getAll();
-      expect(Object.keys(current).length).toBe(0);
+
+      expect(sessionStore.getAll()).toEqual({});
+      expect(sessionStore.listProfiles()).toEqual([]);
+
+      sessionStore.setActiveProfile(null);
+      expect(sessionStore.getAll().scheme).toBe('Global');
+    });
+
+    it('should clear a specific profile when profile is provided', async () => {
+      sessionStore.setActiveProfile('ios');
+      sessionStore.setDefaults({ scheme: 'IOS' });
+      sessionStore.setActiveProfile('watch');
+      sessionStore.setDefaults({ scheme: 'Watch' });
+      sessionStore.setActiveProfile('watch');
+
+      const result = await sessionClearDefaultsLogic({ profile: 'ios' });
+      expect(result.isError).toBe(false);
+      expect(result.content[0].text).toContain('profile "ios"');
+
+      expect(sessionStore.listProfiles()).toEqual(['watch']);
+      expect(sessionStore.getAll().scheme).toBe('Watch');
+    });
+
+    it('should error when the specified profile does not exist', async () => {
+      const result = await sessionClearDefaultsLogic({ profile: 'missing' });
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain('does not exist');
+    });
+
+    it('should reject all=true when combined with scoped arguments', async () => {
+      const result = await sessionClearDefaultsLogic({ all: true, profile: 'ios' });
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain('cannot be combined');
     });
 
     it('should validate keys enum', async () => {

src/mcp/tools/session-management/session_clear_defaults.ts

@@ -9,14 +9,73 @@ const keys = sessionDefaultKeys;
 
 const schemaObj = z.object({
   keys: z.array(z.enum(keys)).optional(),
-  all: z.boolean().optional(),
+  profile: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Clear defaults for this named profile instead of the active profile.'),
+  all: z
+    .boolean()
+    .optional()
+    .describe(
+      'Clear all defaults across global and named profiles. Cannot be combined with keys/profile.',
+    ),
 });
 
 type Params = z.infer<typeof schemaObj>;
 
 export async function sessionClearDefaultsLogic(params: Params): Promise<ToolResponse> {
-  if (params.all || !params.keys) sessionStore.clear();
-  else sessionStore.clear(params.keys);
+  if (params.all) {
+    if (params.profile !== undefined || params.keys !== undefined) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'all=true cannot be combined with profile or keys.',
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    sessionStore.clear();
+    return { content: [{ type: 'text', text: 'All session defaults cleared' }], isError: false };
+  }
+
+  const profile = params.profile?.trim();
+  if (profile !== undefined) {
+    if (profile.length === 0) {
+      return {
+        content: [{ type: 'text', text: 'Profile name cannot be empty.' }],
+        isError: true,
+      };
+    }
+
+    if (!sessionStore.listProfiles().includes(profile)) {
+      return {
+        content: [{ type: 'text', text: `Profile "${profile}" does not exist.` }],
+        isError: true,
+      };
+    }
+
+    if (params.keys) {
+      sessionStore.clearForProfile(profile, params.keys);
+    } else {
+      sessionStore.clearForProfile(profile);
+    }
+
+    return {
+      content: [{ type: 'text', text: `Session defaults cleared for profile "${profile}"` }],
+      isError: false,
+    };
+  }
+
+  if (params.keys) {
+    sessionStore.clear(params.keys);
+  } else {
+    sessionStore.clearForProfile(sessionStore.getActiveProfile());
+  }
+
   return { content: [{ type: 'text', text: 'Session defaults cleared' }], isError: false };
 }
 

src/smoke-tests/__tests__/e2e-mcp-sessions.test.ts

@@ -179,22 +179,24 @@ describe('MCP Session Management (e2e)', () => {
   });
 
   it('supports namespaced defaults by switching active profile', async () => {
-    await harness.client.callTool({
-      name: 'session_use_defaults_profile',
-      arguments: { profile: 'ios' },
-    });
     await harness.client.callTool({
       name: 'session_set_defaults',
-      arguments: { scheme: 'IOSScheme', projectPath: '/ios/project.xcodeproj' },
+      arguments: {
+        profile: 'ios',
+        createIfNotExists: true,
+        scheme: 'IOSScheme',
+        projectPath: '/ios/project.xcodeproj',
+      },
     });
 
-    await harness.client.callTool({
-      name: 'session_use_defaults_profile',
-      arguments: { profile: 'watch' },
-    });
     await harness.client.callTool({
       name: 'session_set_defaults',
-      arguments: { scheme: 'WatchScheme', projectPath: '/watch/project.xcodeproj' },
+      arguments: {
+        profile: 'watch',
+        createIfNotExists: true,
+        scheme: 'WatchScheme',
+        projectPath: '/watch/project.xcodeproj',
+      },
     });
 
     const activeWatch = await harness.client.callTool({

src/utils/config-store.ts

@@ -9,6 +9,7 @@ import {
 } from './project-config.ts';
 import type { DebuggerBackendKind } from './debugger/types.ts';
 import type { UiDebuggerGuardMode } from './runtime-config-types.ts';
+import { normalizeSessionDefaultsProfileName } from './session-defaults-profile.ts';
 
 export type RuntimeConfigOverrides = Partial<{
   enabledWorkflows: string[];
@@ -319,19 +320,6 @@ function getCurrentFileConfig(): ProjectConfig {
   return storeState.fileConfig ?? { schemaVersion: 1 };
 }
 
-function normalizeProfileNameForStore(profile?: string | null): string | null {
-  if (profile == null) {
-    return null;
-  }
-
-  const trimmed = profile.trim();
-  if (trimmed.length === 0) {
-    throw new Error('Profile name cannot be empty.');
-  }
-
-  return trimmed;
-}
-
 function applySessionDefaultsPatchToFileConfig(opts: {
   fileConfig: ProjectConfig;
   profile: string | null;
@@ -562,7 +550,7 @@ export async function persistSessionDefaultsPatch(opts: {
     throw new Error('Config store has not been initialized.');
   }
 
-  const normalizedProfile = normalizeProfileNameForStore(opts.profile);
+  const normalizedProfile = normalizeSessionDefaultsProfileName(opts.profile);
 
   const result = await persistSessionDefaultsToProjectConfig({
     fs: storeState.fs,
@@ -590,7 +578,7 @@ export async function persistActiveSessionDefaultsProfile(
     throw new Error('Config store has not been initialized.');
   }
 
-  const normalizedProfile = normalizeProfileNameForStore(profile);
+  const normalizedProfile = normalizeSessionDefaultsProfileName(profile);
 
   const result = await persistActiveSessionDefaultsProfileToProjectConfig({
     fs: storeState.fs,

src/utils/project-config.ts

@@ -6,6 +6,7 @@ import type { SessionDefaults } from './session-store.ts';
 import { log } from './logger.ts';
 import { removeUndefined } from './remove-undefined.ts';
 import { runtimeConfigFileSchema, type RuntimeConfigFile } from './runtime-config-schema.ts';
+import { normalizeSessionDefaultsProfileName } from './session-defaults-profile.ts';
 
 const CONFIG_DIR = '.xcodebuildmcp';
 const CONFIG_FILE = 'config.yaml';
@@ -216,17 +217,6 @@ function parseProjectConfig(rawText: string): RuntimeConfigFile {
   return runtimeConfigFileSchema.parse(parsed) as RuntimeConfigFile;
 }
 
-function normalizeProfileForPersistence(profile?: string | null): string | null {
-  if (profile == null) {
-    return null;
-  }
-  const trimmed = profile.trim();
-  if (trimmed.length === 0) {
-    throw new Error('Profile name cannot be empty.');
-  }
-  return trimmed;
-}
-
 async function readBaseConfigForPersistence(
   options: PersistenceTargetOptions,
 ): Promise<ProjectConfig> {
@@ -303,7 +293,7 @@ export async function persistSessionDefaultsToProjectConfig(
   const baseConfig = await readBaseConfigForPersistence({ fs: options.fs, configPath });
 
   const patch = removeUndefined(options.patch as Record<string, unknown>);
-  const targetProfile = normalizeProfileForPersistence(options.profile);
+  const targetProfile = normalizeSessionDefaultsProfileName(options.profile);
   const isGlobalProfile = targetProfile === null;
   const baseDefaults = isGlobalProfile
     ? (baseConfig.sessionDefaults ?? {})
@@ -341,7 +331,7 @@ export async function persistActiveSessionDefaultsProfileToProjectConfig(
   const baseConfig = await readBaseConfigForPersistence({ fs: options.fs, configPath });
 
   const nextConfig: ProjectConfig = { ...baseConfig, schemaVersion: 1 };
-  const activeProfile = normalizeProfileForPersistence(options.profile);
+  const activeProfile = normalizeSessionDefaultsProfileName(options.profile);
   if (activeProfile === null) {
     delete nextConfig.activeSessionDefaultsProfile;
   } else {

src/utils/session-defaults-profile.ts

@@ -0,0 +1,12 @@
+export function normalizeSessionDefaultsProfileName(profile?: string | null): string | null {
+  if (profile == null) {
+    return null;
+  }
+
+  const trimmed = profile.trim();
+  if (trimmed.length === 0) {
+    throw new Error('Profile name cannot be empty.');
+  }
+
+  return trimmed;
+}

src/utils/session-store.ts

@@ -112,10 +112,6 @@ class SessionStore {
     return this.getAllForProfile(this.activeProfile);
   }
 
-  getAllGlobal(): SessionDefaults {
-    return { ...this.globalDefaults };
-  }
-
   getAllForProfile(profile: string | null): SessionDefaults {
     if (profile === null) {
       return { ...this.globalDefaults };