fix: auto-detect code wiki branch for wiki page safe outputs

[jamesadevine]

Problem

The create-wiki-page and update-wiki-page safe output executors fail with HTTP 400 when targeting Azure DevOps code wikis (type 1):

The versionType should be 'branch' and version cannot not be null
Parameter name: versionDescriptor

The ADO Wiki Pages API requires an explicit versionDescriptor (branch + versionType) for write operations on code wikis. Project wikis (type 0) work without it because the server handles branching internally via wikiMaster.

Solution

Rather than requiring users to manually configure a branch field, the executor now auto-detects the wiki type at runtime:

1. Calls GET /_apis/wiki/wikis/{id}?api-version=7.0 to fetch wiki metadata
2. If type == 1 (code wiki), extracts the published branch from versions[0].version
3. Includes versionDescriptor.version and versionDescriptor.versionType=branch in both GET and PUT requests
4. Project wikis (type 0) continue to work unchanged — no versionDescriptor is sent

An optional branch config field is also available as an explicit override (e.g. for targeting a non-default branch on a code wiki).

Changes

• src/tools/mod.rs — Added resolve_wiki_branch() shared helper that queries wiki metadata and returns the resolved branch
• src/tools/create_wiki_page.rs — Added branch config field; GET and PUT now use resolved branch
• src/tools/update_wiki_page.rs — Same changes as create
• AGENTS.md — Updated docs for both wiki tools to describe auto-detection and the optional branch override

Example

Before (required for code wikis, easy to forget):

safe-outputs:
  update-wiki-page:
    wiki-name: "Azure Sphere"
    branch: "main"              # had to know this

After (just works):

safe-outputs:
  update-wiki-page:
    wiki-name: "Azure Sphere"   # code wiki branch auto-detected

Testing

• All 78 existing wiki page tests pass
• All 4 compiler integration tests pass
• Full test suite green, no new clippy warnings
• New unit tests for branch config deserialization added

[github-actions]

🔍 Rust PR Review

Summary: Looks good with two actionable concerns around silent failure modes in resolve_wiki_branch.

---

Findings

🐛 Bugs / Logic Issues

• src/tools/mod.rs:47-52 — HTTP failure silently degrades to None with a debug! log

  When the wiki metadata fetch fails (network error, 403, 404, etc.), resolve_wiki_branch returns None and logs at DEBUG level. For a code wiki, this means the subsequent GET and PUT proceed without a versionDescriptor. The GET may silently query the wrong branch, and the PUT will fail with a cryptic ADO error — with no trace in any meaningful log level pointing back to branch auto-detection as the root cause.

  // mod.rs line 47
  if !resp.status().is_success() {
      debug!(  // ← should be warn! for production diagnosability
          "Wiki metadata request returned HTTP {} — skipping branch auto-detection",
          resp.status()
      );
      return None;
  }

  Suggest warn! here. Operators who misconfigure permissions on the wiki metadata API endpoint will be left chasing a confusing ADO PUT error.

• src/tools/mod.rs:64-74 — Code wiki with missing/empty versions silently returns None

  If wiki_type == 1 but versions is absent or empty, branch is None and the only log output is "resolved branch: None". There's no indication that detection was attempted and failed for a code wiki. This will cause the PUT to fail for the same reason as above, equally hard to diagnose.

  // After the chain of and_then, add:
  if wiki_type == 1 && branch.is_none() {
      warn!("Code wiki detected but versions array is empty — branch detection failed");
  }

  Additionally, note that use log::debug; is the only import — warn! would require adding warn to that import line.

---

✅ What Looks Good

• Clean extraction of the shared resolve_wiki_branch helper into mod.rs — avoids duplicating the auto-detection logic across create_wiki_page.rs and update_wiki_page.rs.
• Consistent use of the resolved branch for both the pre-flight GET and the PUT — prevents a subtle bug where the two calls could query different branches.
• Correct percent-encoding of wiki_name and project in the metadata URL (matching the encoding already applied in base_url).
• The unwrap_or(0) default for wiki_type is a safe and sensible fallback (unknown type → treat as project wiki → no branch needed).
• Config struct tests updated correctly; AGENTS.md documentation is accurate and complete.

Generated by Rust PR Reviewer for issue #115 · ◷