Skip to content

ZenUml/conf-app / .claude/skills/find-macros-on-page

find-macros-on-page

Verified

List ZenUML (and other) macros on any Confluence page in render order, with their customContentId, type, title, and ADF localId — and fetch a chosen macro's stored body (DrawIO XML / Mermaid / PlantUML / ZenUML DSL / OpenAPI). Two operations, one skill. Use whenever investigating a customer page, locating which macro to inspect/reproduce, correlating "the third diagram on page X" to a specific customContentId, or extracting a stored macro source for rebuild. Triggers on "what macros are on this page", "find the macro at <URL>", "fetch the macro source", "extract macro XML", "rebuild this customer's macro", or any starting step of a customer-page investigation.

FileKindSize
SKILL.mdskill md8.9 KB
scripts/fetch-source-snippet.jsscript2.2 KB
scripts/fetch.mjsscript3.3 KB
scripts/list.mjsscript5.3 KB
scripts/snippet.jsscript2.4 KB
---
name: find-macros-on-page
description: List ZenUML (and other) macros on any Confluence page in render order, with their customContentId, type, title, and ADF localId — and fetch a chosen macro's stored body (DrawIO XML / Mermaid / PlantUML / ZenUML DSL / OpenAPI). Two operations, one skill. Use whenever investigating a customer page, locating which macro to inspect/reproduce, correlating "the third diagram on page X" to a specific customContentId, or extracting a stored macro source for rebuild. Triggers on "what macros are on this page", "find the macro at <URL>", "fetch the macro source", "extract macro XML", "rebuild this customer's macro", or any starting step of a customer-page investigation.
---

# Find Macros on Page

Two atomic operations against the Confluence v2 REST API, both available as a browser snippet (universal) or a Node CLI (our tenants):

| Step | What | Output |
|---|---|---|
| 1. **list** | Walk the page ADF, join with `/custom-content` listing. | Per-extension row: pos, moduleKey, customContentId, title, localId. |
| 2. **fetch** | Pull one customContent body, parse the JSON wrapper. | `{ diagramType, graphXml \| code \| spec, ... }`. |

Use **list** to identify which macro to inspect, then **fetch** to get its source.

## Why this exists

Locating + extracting a macro on a customer page used to mean ~10 fragile tool calls: visual scrolling, iframe DOM inspection, decoding the `_ctx_` payload (red herring), listing custom-content, picking the right one by visually correlating IDs, then fighting the claude-in-chrome proxy filter and clipboard-hopping to actually get the bytes out. This skill collapses both halves to two REST calls each.

## Two recipes — pick by tenant

| Recipe | When | Auth |
|---|---|---|
| **A. Browser snippet** (default) | Any tenant the user can view in their browser, including customer sites where they're a guest. | Page cookies — no token needed. |
| **B. Node CLI** | Our tenants (`lite-dev`, `lite-stg`, `zenuml-stg`, `zenuml`). | API token in `.env.forge.local`. |

Try A first when access is uncertain. Fall back to B for piping into bash workflows on our own tenants.

### Why Recipe A works on customer tenants

Atlassian returns `404 NOT_FOUND` for permission-denied (it deliberately won't leak existence). An API token authenticates as the account that owns it (e.g. `support@zenuml.com`); customer pages typically aren't shared with that account. The user's **browser session** is their personal Atlassian identity, often a guest on customer tenants. Driving the v2 REST API from within that authenticated page context inherits the cookies, so the API behaves exactly as the browser does.

Confirmed end-to-end on a customer tenant where the API-token route 404'd.

---

## Recipe A — Browser snippets

### Prereqs

In agent-browser (`A(){ agent-browser --session conf-app --restore=stg "$@"; }`; Playwright MCP is the fallback), `A open` **any page on the target tenant**. The list snippet pulls the page id from `location.pathname`; the fetch snippet needs a specific customContentId you've already chosen.

### A1 — list

Read `.claude/skills/find-macros-on-page/scripts/snippet.js` and run it with `A eval -b "$(base64 < .claude/skills/find-macros-on-page/scripts/snippet.js)"` (or `A eval --stdin < …/snippet.js`); fallback `browser_evaluate` (Playwright MCP). Returns `{ renderedCount, rendered, orphans, totalCC }`. `rendered` is in page document order; filter `moduleKey` matching `/^zenuml-.*-macro/` for just our macros.

### A2 — fetch

Read `.claude/skills/find-macros-on-page/scripts/fetch-source-snippet.js`. **Replace the `<CC_ID>` placeholder** with the customContentId you picked from A1, then run it the same way (`A eval -b …`; fallback `browser_evaluate`). Returns a summary; the full body is stashed on `window.__macroBody` (raw string) and `window.__macroBodyParsed` (parsed object).

#### Getting the bytes out

- **Via agent-browser** (primary): no output filter. `eval` prints strings JSON-quoted (`"a\nb"`), so decode before writing: `A eval "window.__macroBody" | python3 -c 'import json,sys; sys.stdout.write(json.load(sys.stdin))' > /path/to/output.xml`.
- **Via Playwright MCP** (fallback): no output filter. `browser_evaluate(() => window.__macroBody)` returns the full string.
- claude-in-chrome is not used here: its proxy blocks long base64-shaped output (`[BLOCKED: ...]`).

---

## Recipe B — Node CLIs

### One-time setup

```
# .env.forge.local
FORGE_EMAIL=<your-email>
FORGE_API_TOKEN=<token>
```

Token: https://id.atlassian.com/manage-profile/security/api-tokens.

### B1 — list

```bash
set -a; source .env.forge.local; set +a
node .claude/skills/find-macros-on-page/scripts/list.mjs \
  --site lite-dev --page 16941057
```

Output:

```
# Page 16941057 on lite-dev.atlassian.net
# 1 macro(s) in body, 0 other custom content

pos  module                       customContentId  title                                              localId
---  ---------------------------  ---------------  -------------------------------------------------  ------------------------------------
1    zenuml-graph-macro-lite      16973825         graph test content                                 ec16f5c5-df4f-47af-a6bd-13baad92b73b
```

| Flag | Notes |
|---|---|
| `--site` (required) | `lite-dev`, `lite-stg`, `zenuml-stg`, `zenuml`, or a hostname (`example-tenant-h` → `example-tenant-h.atlassian.net`). On unknown hosts the call usually 404s — fall back to A1. |
| `--page` (required) | Page ID (digits in `/pages/<id>/...`). |
| `--json` | JSON output instead of the table. |
| `--include-orphans` | Also list custom content owned by the page but unreferenced in its ADF body. |

### B2 — fetch

```bash
set -a; source .env.forge.local; set +a
node .claude/skills/find-macros-on-page/scripts/fetch.mjs \
  --site lite-dev --id 16973825 --out /tmp/diagram.xml
```

Writes the auto-detected body field (graphXml / code / spec) to `--out`. Metadata (type, title, diagramType, bytes) goes to stderr so stdout/`--out` stays clean for piping. Confirmed bit-exact: hashes match between fetched-back and the original XML used to seed the test page.

| Flag | Notes |
|---|---|
| `--site` (required) | Same conventions as B1. |
| `--id` (required) | The customContentId from B1. |
| `--out` | Path to write the body field to. If omitted, written to stdout. |
| `--field` | Force a specific body field (`graphXml`, `code`, `spec`, or any other key). Auto-detected by default. |
| `--json` | Emit the entire parsed body as JSON instead of just one field. |

---

## End-to-end: rebuild a customer macro on lite-dev

```bash
# 1. From agent-browser (browser snippet A1) on the customer page:
#    → got customContentId 6445039617 for the diagram of interest.

# 2. Fetch its body. For a customer tenant, use A2 (browser snippet) + clipboard;
#    for our tenants, B2:
node .claude/skills/find-macros-on-page/scripts/fetch.mjs \
  --site <site> --id 6445039617 --out /tmp/diagram.xml

# 3. Rebuild on lite-dev:
node .claude/skills/create-test-page/scripts/create-test-page.mjs \
  --site lite-dev --space SD --title "customer repro" \
  --macro graph:/tmp/diagram.xml
```

The endpoint prints the new page URL on success — open it to verify.

---

## Output schema reference

**A1 / B1 (list):**

```jsonc
{
  "rendered": [
    {
      "pos": 1,                                // 1-indexed render order, includes third-party extensions
      "moduleKey": "zenuml-graph-macro-lite",  // last path segment of extensionKey
      "customContentId": "6445039617",
      "title": ".",
      "contentType": "zenuml-content-sequence",
      "localId": "72887d79-..."
    }
  ],
  "orphans": [{ "id": "5553291585", "type": "zenuml-content-graph", "title": "..." }]
}
```

**A2 (browser fetch):**

```jsonc
{
  "ok": true,
  "contentType": "zenuml-content-sequence",
  "title": ".",
  "rawLen": 23751,
  "summary": {
    "diagramType": { "type": "string", "len": 5, "first120": "graph" },
    "graphXml":    { "type": "string", "len": 21817, "first120": "<mxfile host=\"...\"..." }
  },
  "full": null  // populated only if rawLen < 4000; otherwise read window.__macroBody
}
```

**B2 (CLI fetch):** writes the body string to `--out` (or stdout). Metadata on stderr.

## Caveats

- **`rendered` includes third-party extensions.** Other Forge apps (`details`, `lref-box-file`, etc.) get counted so `pos` matches visual order. Filter `moduleKey` if you want only ours.
- **`contentType` reflects the storage slot, not the rendered diagram type.** A diagram of `diagramType: graph` may be stored under `zenuml-content-sequence` for historical reasons. The body's `diagramType` field is authoritative.
- **Pre-Forge legacy macros not listed.** Connect-era `<ac:structured-macro>` storage nodes don't appear as ADF `extension` nodes. All current installs are Forge — only matters on very old pages.
- **claude-in-chrome proxy filter.** Base64-shaped output gets blocked. Use agent-browser (no filter) and redirect `eval` output to a file.

## Related

- `create-test-page` — rebuild a fetched body as a new page on a target tenant.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall