>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588773. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The entire menu-builder failure class &mdash; misidentified Drupal success redirects, 64 minutes of dead time across 4 dispatch attempts, manual fallback for the footer menu &mdash; exists because menu management is forced through browser automation against the Drupal admin UI. The admin UI path is vulnerable to WAF redirects, cookie-auth expiry, and redirect ambiguity.</p> <p>The <code>menu:administer</code> OAuth scope (newly available in Acquia Source / canvas_oauth) was hypothesized to allow POST/PATCH/DELETE of menu items via API directly &mdash; eliminating the browser path entirely. With API access, menu mutation would be a direct OAuth-token API call: no browser, no admin UI, no auth-redirect ambiguity. The browser-automation logic in 2-01 and 2-02 would become a fallback path rather than the primary path.</p> <p>An empirical probe on 2026-05-01 against a live Acquia Source test instance confirmed the scope mints tokens but the corresponding write endpoints are NOT shipped. This issue is currently <strong>blocked-on-acquia-endpoint</strong>.</p> <p>Empirical probe results (live Acquia Source instance, 2026-05-01):</p> <ul> <li><code>menu:administer</code> scope minted an OAuth token (HTTP 200) &mdash; scope IS registered.</li> <li><code>GET /api/menu_items/main</code> &rarr; HTTP 200, returned 2 items &mdash; read access confirmed.</li> <li><code>POST /api/menu_items/main</code> &rarr; <strong>HTTP 405</strong> with header <code>Allow: GET, HEAD</code> &mdash; collection is read-only.</li> <li><code>POST /api/menu_link_content/menu_link_content</code> &rarr; <strong>HTTP 404</strong> &mdash; direct entity path does not exist on this release.</li> <li>PATCH on individual menu items &rarr; returned Drupal admin login HTML (admin UI redirect, not JSON:API response).</li> </ul> <p>Conclusion: <code>menu:administer</code> grants read access to existing menus but no JSON:API write endpoint is exposed. The browser-automation path through the <code>.canvas-browser/</code> profile remains the only write path on this release. The CLAUDE.md statement "Menu items are read-only via JSON:API" is empirically confirmed accurate as of 2026-05-01.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Request an OAuth token with <code>scope=menu:administer</code> against a current Acquia Source instance.</li> <li>Confirm: HTTP 200, valid <code>access_token</code> in response.</li> <li>POST to <code>/api/menu_items/main</code> with the token. Confirm: HTTP 405, <code>Allow: GET, HEAD</code>.</li> <li>POST to <code>/api/menu_link_content/menu_link_content</code> with the token. Confirm: HTTP 404.</li> <li>Conclude: write endpoints are not shipped; the API-first replacement is currently blocked.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p><strong>Step 1 &mdash; Re-probe on each Acquia Source release.</strong> Add the <code>menu:administer</code> probes to the Phase 0.5 scope-availability preflight (1-08). When <code>POST /api/menu_link_content/menu_link_content</code> first returns 200/201 on a future release, this issue unblocks.</p> <p><strong>Step 2 &mdash; When endpoints land, write API-first <code>scripts/create-menus.mjs</code>:</strong></p> <pre>// scripts/create-menus.mjs &mdash; API-first menu creation (blocked until endpoints ship) import { readFileSync } from 'fs'; const SITE_URL = process.env.CANVAS_SITE_URL; const CLIENT_ID = process.env.OAUTH_CLIENT_ID; const CLIENT_SECRET = process.env.OAUTH_CLIENT_SECRET; async function getToken() { const res = await fetch(`${SITE_URL}/oauth/token`, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ grant_type: 'client_credentials', client_id: CLIENT_ID, client_secret: CLIENT_SECRET, scope: 'menu:administer', }), }); const { access_token } = await res.json(); return access_token; } async function createMenuItem(token, { menuName, title, uri, weight = 0, parentId = null }) { const body = { data: { type: 'menu_link_content--menu_link_content', attributes: { title, link: { uri, title: '' }, menu_name: menuName, weight }, ...(parentId ? { relationships: { parent: { data: { type: 'menu_link_content--menu_link_content', id: parentId } } } } : {}), }, }; const res = await fetch(`${SITE_URL}/jsonapi/menu_link_content/menu_link_content`, { method: 'POST', headers: { 'Content-Type': 'application/vnd.api+json', Authorization: `Bearer ${token}` }, body: JSON.stringify(body), }); if (!res.ok) throw new Error(`Menu item POST failed: ${res.status} ${await res.text()}`); return res.json(); }</pre><p><strong>Step 3 &mdash; Restructure menu-builder agent (when unblocked):</strong></p> <pre>PRIMARY PATH (if menu:administer write confirmed by preflight): Use scripts/create-menus.mjs with OAuth token. No browser required. FALLBACK PATH (if menu:administer write denied or endpoint missing): Use browser automation with the redirect-detection logic from 2-01. Cap retries at 1. Write blocked.md on failure.</pre><p><strong>Step 4 &mdash; Update CLAUDE.md.</strong> When write endpoints land: replace the "Menu items are read-only via JSON:API" claim with the verified path and example payload. Until then: keep the existing claim because it is empirically accurate.</p> <p><strong>Step 5 &mdash; Document QE1/path_alias dependency.</strong> Menu items reference page paths. NEW-12 (issue 2-07) confirms <code>canvas:page:create</code> silently ignores <code>path.alias</code> inline. When menu items reference page paths, the path_alias must be set in a separate write &mdash; verify menu URIs resolve before adding pages to navigation.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Re-run the scope/endpoint probe on each new Acquia Source release. The probe is in <code>RESEARCH-2026-04-28/scripts/scope-probe.sh</code>.</li> <li>When write endpoints land: implement <code>scripts/create-menus.mjs</code> per Step 2.</li> <li>When endpoints land: restructure <code>.claude/agents/menu-builder.md</code> to API-first primary, browser fallback.</li> <li>When endpoints land: update <code>jamie-demo/canvas-storybook-ai/CLAUDE.md</code> Content API Types section.</li> <li>Until endpoints land: keep this issue tagged <code>blocked-on-acquia-endpoint</code> and update the empirical-results section after each re-probe.</li> <li>Verify done (when unblocked): API POST creates a test menu item without browser; the perennially-failed footer menu test succeeds via API in &lt; 60 seconds.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None.</p> <h3 id="summary-api-changes">API changes</h3> <p>This issue consumes (does not introduce) existing endpoints: <code>POST /oauth/token</code> with <code>scope=menu:administer</code>, plus the eventual <code>POST/PATCH/DELETE /jsonapi/menu_link_content/menu_link_content</code> endpoints when they land. The endpoint surface is currently incomplete.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>New artifact (when unblocked): <code>scripts/create-menus.mjs</code>. New <code>gotchas.md</code> entry: confirmed <code>menu:administer</code> endpoint surface and write payload format.</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-2-Determinism/05-NEW-7-menu-administer-api-replaces-browser.md</code> (id: NEW-7)</li> <li>Empirical probe results: <code>RESEARCH-2026-04-28/99-final/SCOPE-PROBE-FINDINGS-2026-05-01.md</code> &sect; 6 ("Menu items &mdash; read works, write does NOT")</li> <li>Probe script: <code>RESEARCH-2026-04-28/scripts/scope-probe.sh</code></li> <li>Scope reference: <code>RESEARCH-2026-04-28/99-final/SCOPE-REFERENCE-2026-05-01.md</code> &sect; "CRITICAL impact &mdash; menu:administer &rarr; P0-6, P1-9 (Sprint 2)"</li> <li>Browser-path bug this supersedes when unblocked: 2-01 (P0-6)</li> <li>Deterministic script design this would update when unblocked: 2-02 (P1-9)</li> <li>Preflight dependency: 1-08 (NEW-11)</li> <li>Compaction-persistence target: 1-07 (gotchas.md)</li> <li>Session evidence (footer menu permanently failed): <code>RESEARCH-2026-04-28/06-jamie-demo-old/95q5i-77cf5bb9-half2/findings.md</code></li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>Re-run the scope probe on each new Acquia Source release. When does the <code>menu_link_content</code> write endpoint land?</li> <li>When endpoints land: does <code>menu:administer</code> cover only top-level <code>menu</code> config, or also <code>menu_link_content</code> entity writes? Both are needed for ordered menu-item creation.</li> <li>When endpoints land: does the API allow setting <code>path_alias</code> directly on menu items, or does that require a separate <code>path_alias</code> entity write? (Same class of issue as 2-07's <code>canvas:page:create</code> path.alias gotcha.)</li> <li>Rate limit on <code>/oauth/token</code>: if <code>create-menus.mjs</code> requests one token per Phase 6 execution, well within any reasonable limit. If 1-08's preflight also requests tokens at phase start, the combined count matters.</li> </ul>