feat(session): support extraArgs as a session default

[jknlsn]

Add extraArgs as a first-class session-default value, so common xcodebuild flags can be configured once via .xcodebuildmcp/config.yaml (or the session management tools) and applied to every build/test call that already accepts extraArgs.

Configured defaults come from explicit inputs such as .xcodebuildmcp/config.yaml profiles or session management calls. Per-call args replace configured arguments with the same option or build-setting key. Non-matching configured arguments remain in their original order, followed by the explicit argument list unchanged. Repeated values supplied explicitly are preserved, and an explicit empty array (extraArgs: []) clears the defaults for that one call without changing stored defaults.

The session management tools show, set, sync, and clear extraArgs alongside the other defaults. This registers the new field in the shared structured-output schema (schemas/structured-output/_defs/common.schema.json); the published public schema mirror is generated on merge and was not edited by hand. Existing configs/profiles without extraArgs are unchanged, and tools that do not accept extraArgs are unaffected. For CLI/script usage, the intended deterministic path remains explicit args or checked-in config/profile inputs rather than relying on prior session-default writes.

Closes #462.

---

Validated locally with npm run lint, npm run format:check, npm run typecheck, npm run build, and npm test. Focused session-default suites (session-default-args, session-store, session-aware-tool-factory, CLI session-defaults, and session_set/show/clear_defaults) all pass, plus the full unit/integration suite (214 files, 2689 tests).

CHANGELOG entry included under ## [Unreleased] -> ### Added. Precedent: #147 (feat: Add suppressWarnings option) merged the same change shape — new session-defaults key added to session_set_defaults.ts + session-store.ts with tests. Snapshot fixture diffs for the session management tools are intentional; they reflect the new extraArgs field in set/show/clear/sync output.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/xcodebuildmcp@463

commit: 96b17de

[cameroncooke]

Thanks for this, it's almost there, but we need to think about duplicate arguments. If the user/agent adds explicit extraArgs to a tool call that already has those argument(s) defined as a session default then I would expect the explicit argument(s) to win. Not be duplicated as that will likely cause xcodebuild error.

[cameroncooke]

@jknlsn I saw you've doubled down on supporting duplicate arguments, just wondering what your reasoning is?

From my PoV I'm not aware of any xcodebuild arguments that should be provided multiple times. In testing while depending on the argument it will just ignore the earlier argument without throwing an error, but in other cases it will throw an error like passing -scheme twice for example.

I think it would be better to do:

session default args: -quiet, -skipMacroValidation, -destination "id=x"
explicit args: -quiet, -destination "ix=y"
merged: xcodebuild ... -skipMacroValidation -quiet -destination ="id=y"

I'm not stuck on this, if there is a good reason for supporting the following, can you give me some use-cases where this is useful?:
merged: xcodebuild ... -quiet -skipMacroValidation -destination "id=x" -quiet -destination "id=y"

[jknlsn]

Thanks for taking a look @cameroncooke!

Fair points, I think I may be overthinking this. If something is passed explicitly in extraArgs, treating it as replacing the matching session-default arg is probably the simpler and less surprising UX.

It's late here, so I'm going to leave it here for the moment rather than keep pinging the PR while I'm still working through it. I'll revisit tomorrow and update with the simpler merge behaviour!

[jknlsn]

Thanks again @cameroncooke, I've updated this now!

Explicit extraArgs now replace matching session-default arguments. Non-matching defaults keep their original order, then the explicit argument list is appended unchanged. This gives the merge you suggested:

-skipMacroValidation -quiet -destination id=y

Repeated values passed explicitly are preserved, and extraArgs: [] still clears defaults for that call. I've added focused tests around the merge behaviour and the xcodebuild argument forms it handles.

[cameroncooke]

@jknlsn LGTM!