ZenUml/conf-app / .claude/skills/joint-debug
joint-debug
VerifiedEnable, launch, monitor, troubleshoot, and stop the local joint-debug environment across conf-app, its Cloudflare Worker, ngrok, Forge tunnel, and diagramly.ai. Use for requests mentioning joint-debug, join-debug, combined local AI Repair testing, starting or monitoring the five-service stack, or closing that stack.
Joint Debug
Run a local five-service stack:
- Diagramly AI service on
http://localhost:3000 - Cloudflare Pages Worker on
http://localhost:8789 - ngrok forwarding the configured HTTPS domain to port
8789 - conf-app frontend on
http://127.0.0.1:8080 - Forge tunnel
Guardrails
- Preserve unrelated working-tree and staged changes.
- Never print the ngrok token or database password.
- Keep
'/diagramly'infunctions/_middleware.tsAUTHENTICATED_PATHS. AI routes require verified Forge JWT data indata.forgeContext. - Keep AI Repair visibility on its existing feature-flag/runtime path. Never force
isAiRepairEnabledorshouldShowAiRepairtotrue. - Use a local PostgreSQL database for Diagramly. Do not point local joint-debug at staging or production.
- Do not claim a service is ready until its log or health endpoint proves readiness.
Enable configuration
- Inspect
git status, staged and unstaged diffs. Joint-debug must not edit tracked application source to configure local endpoints. - Obtain the full Diagramly checkout path. Discover likely sibling checkouts first; ask only when multiple plausible paths remain.
- Verify
wrangler.tomlcontainsNGROK_AUTHTOKENandNGROK_DOMAINwithout displaying the token. Validate the domain as a hostname; the frontend override must be an HTTPS origin with no path. - Use
VITE_JOINT_DEBUG_REMOTE_BASE_URL=https://<NGROK_DOMAIN>on the Vite process.forgeGlobal.tsuses it only for aDEVELOPMENTForge context in Vite dev mode, including the AsyncAPI variant. Do not changeDEVELOPMENT_*constants. - Pass
--binding=DIAGRAMLY_BACKEND_API_BASE_URL=http://127.0.0.1:3000topnpm wrangler:serve:raw. This overrides the local Worker binding without changing the ignoredwrangler.toml. - Check the ignored
.env.forge/.env.forge.localconfiguration: it must select the Diagramly development app. PutBACKEND_API_BASE_URL=https://<NGROK_DOMAIN>in.env.forge.localfor the variant-aware deploy below. SetJOINT_DEBUG_BACKEND_API_BASE_URL=https://<NGROK_DOMAIN>on the Forge tunnel command;scripts/forgexapplies it after loading those files. The frontend override and deployedconnectremote must match exactly. These ignored settings are local configuration; do not edit tracked application source to switch URLs. - Do not change middleware authentication or AI Repair feature flags to make the stack work. If runtime evidence identifies a product bug there, handle it as a separate source fix.
- Run
git diff --checkand inspect the final diff before launching services. A normal joint-debug setup has no tracked source diff.
Prepare the Diagramly local database
First inspect packages/database/prisma/schema.prisma; Diagramly uses PostgreSQL-specific migrations and cannot be switched to SQLite as a startup-only change.
-
Reuse an existing
DATABASE_URLonly when its hostname islocalhostor127.0.0.1. -
Check ports and existing containers before starting anything. Never stop an unknown PostgreSQL, Supabase, or user-owned container.
-
If no suitable local PostgreSQL exists, create a dedicated
diagramly-postgresPostgreSQL 16 container. Prefer host port5432; use5433or another free port when occupied.docker run -d --name diagramly-postgres \ -e POSTGRES_USER=test_user \ -e POSTGRES_PASSWORD=test_pass \ -e POSTGRES_DB=diagramly_test \ -p 127.0.0.1:<free-port>:5432 \ postgres:16 -
Initialize the empty local database from the Diagramly root:
DATABASE_URL='<local-url>' \ pnpm --filter database exec prisma db push \ --skip-generate --schema prisma/schema.prisma -
Keep the chosen URL as a runtime override; do not rewrite Diagramly
.envunless the user explicitly asks. -
After Diagramly starts, require
GET http://127.0.0.1:3000/api/health?deep=1to reportdb: "up".
The repository's .env.test.example local defaults are suitable for a dedicated test database. Treat any remote, staging, or production database URL as a configuration error for this workflow.
Before launch
Verify the selected Forge environment is a development environment. The installed app's deployed connect remote must already use https://<NGROK_DOMAIN>. A forge tunnel process variable changes manifest parsing locally, but does not update the deployed manifest; changing the remote hostname requires a development deployment. If the deployed remote differs, ask the user before running the variant-aware Diagramly build → deploy → upgrade flow (requires yq):
pnpm forge-wizard --app diagramly --env development --site '<test-site>.atlassian.net' --tunnel no
The wizard builds the Diagramly variant, removes its unused DrawIO asset tree, strips modules belonging to other variants from a temporary manifest, deploys, upgrades the installation, and restores the original manifest. The simpler forge:upgrade:diagramly:dev script does not strip the manifest and can hit macro-key conflicts on a shared site. If the user declines a required deployment, do not claim Forge remote requests can reach this local Worker. Backend-only checks can still continue if useful.
Launch mode
Choose based on the user's request.
Frontend mode invariants
- Treat
pnpm start:localas a standalone Lite frontend. It runs Vite inservemode and intentionally aliases@forge/bridgetosrc/stubs/forge-bridge.ts. - Treat
pnpm start:sitas local D1 migration + Wrangler +start:local. It still uses the Forge bridge stub, and it also starts its own Worker. Never substitute it for the separately managed Worker + frontend in this stack. - Start a frontend consumed by Forge tunnel with
FORGE_TUNNEL=1; this is the explicit signal invite.config.mjsthat retains the real@forge/bridgepackage. - Set
PRODUCT_TYPE=diagramlyon the Vite command itself. Do not rely on a parent environment variable when a nested package script setsPRODUCT_TYPE=liteexplicitly. - Expect the Confluence iframe source to use
http://localhost:8000: Forge tunnel owns that proxy origin and forwards Custom UI assets to Vite on127.0.0.1:8080. Seeing port8000is not evidence of a failure.
Before UI testing, inspect the transformed frontend module without printing secrets:
curl -fsS http://127.0.0.1:8080/src/model/globals/forgeGlobal.ts \
| rg 'node_modules/.vite/deps/@forge_bridge|src/stubs/forge-bridge|PRODUCT_TYPE'
Require the real @forge_bridge dependency, no src/stubs/forge-bridge import,
and PRODUCT_TYPE: "diagramly". If a real Forge iframe reports
Forge context missing extension, check these invariants first. Do not weaken
the context guard or manufacture a Forge context in application code.
Macro identity versus local build identity
An existing Forge macro stores its module key, configuration, and content; it does not pin a copy of the frontend bundle used when the macro was created. Every view or edit loads the app resource again. While a Forge tunnel is active, an existing macro can therefore execute the bundle currently served by the local Vite process.
- Treat
context.moduleKeyas the macro identity. For example, a key ending in-liteis a Lite macro. - Treat
import.meta.env.PRODUCT_TYPEas the local bundle identity only. Never use it to decide which Forge macro or app owns persisted content. - If a Lite
moduleKeyexecutes a bundle compiled withPRODUCT_TYPE=diagramly, diagnose a tunnel/Vite variant mismatch. The macro has not been converted and its saved content has not changed. - Running the variant-aware Diagramly deployment above upgrades the Diagramly development
installation; it does not convert existing Lite macros. Verify that the
active tunnel, the macro's
moduleKey, and the VitePRODUCT_TYPEmatch the variant being tested before investigating feature flags or UI visibility. - To test a Diagramly-only feature, use a Diagramly macro. Do not treat a Lite macro that happens to receive the Diagramly local bundle as a Diagramly macro.
Codex-managed monitoring
When the user asks Codex to start, own, monitor, or automatically diagnose the stack, do not run the AppleScript helper. Launch five long-running managed PTY sessions and retain every session ID:
# Diagramly checkout
DATABASE_URL='<local-url>' pnpm dev
# conf-app checkout; keep `dist` as the Pages asset directory so Wrangler does
# not scan the repository root and node_modules.
PORT=8789 HOST=127.0.0.1 pnpm wrangler:serve:raw --binding=DIAGRAMLY_BACKEND_API_BASE_URL=http://127.0.0.1:3000
ngrok http --authtoken '<token>' --url '<domain>' 8789
VITE_JOINT_DEBUG_REMOTE_BASE_URL='https://<domain>' FORGE_TUNNEL=1 VERSION=latest PRODUCT_TYPE=diagramly pnpm exec vite dev --port 8080 --host 127.0.0.1
JOINT_DEBUG_BACKEND_API_BASE_URL='https://<domain>' pnpm forge:tunnel
If a sandboxed launch fails with EPERM, file-log permission errors, or port-binding errors, rerun that service with the required elevated permission. Do not launch pnpm start:sit: it starts another Worker and collides with the separately managed Worker.
Require these readiness signals:
- Diagramly: Next.js
Readyon port3000, mock OpenAI server on9000, and deep healthdb: "up". - Worker:
Ready on http://localhost:8789. - ngrok: local API on
4040shows the configured public URL forwarding to8789. - Frontend: Vite
readyon127.0.0.1:8080. - Forge: tunnel reports its development environment and listens for requests.
User-managed Terminal windows
When the user explicitly wants separate macOS Terminal windows, run:
./.claude/skills/joint-debug/launch-debug-services.sh \
'<NGROK_AUTHTOKEN>' \
'<NGROK_DOMAIN>' \
'<DIAGRAMLY_PATH>'
The fourth argument is optional. When omitted, the helper lets Diagramly's pnpm dev load
DATABASE_URL from its default .env; the helper still verifies that it targets localhost. Pass
'<LOCAL_DATABASE_URL>' as the fourth argument only when an explicit local override is needed.
The helper requires macOS permission to send Apple Events to Terminal. If it reports error -1743, stop and tell the user to grant Automation permission or switch to Codex-managed PTYs. Never accept its success banner without checking that the expected ports are listening.
Monitor and repair
While the user tests:
- Poll all five PTY sessions after each action and retain new output.
- Correlate requests with ngrok metadata, Worker logs, Forge logs, and Diagramly logs. Avoid dumping authorization headers or request bodies containing secrets.
- Trace the user-visible error through runtime evidence before editing code.
- Apply the smallest evidence-backed fix, run focused tests, and confirm the affected service hot-reloads or restarts.
- Ask the user to retry only after the stack returns to ready state.
For an AI Repair acceptance test on a real Confluence draft:
- Reuse the user's existing logged-in browser tab; do not open another browser.
- Use Playwright because Forge Custom UI is a sandboxed cross-origin iframe.
- Insert the Diagramly development OpenAPI macro and enter deliberately invalid
YAML, for example
title Sample APIinstead oftitle: Sample API. - Require visible parser-error evidence, open AI Repair, wait for the repaired diff, apply it, and wait for the stale parser error to disappear.
- Require the editor to contain the repaired code and the preview to render.
- Corroborate the UI with ngrok metadata showing successful
/diagramly/fix-diagramand/diagramly/job-statusresponses. Print only timestamps, methods, paths, and status codes. - Save the macro to the page draft only when the user authorized insertion. Do not click Confluence's page-level Publish action unless separately asked.
Do not mark the check passed from unit tests alone. Preserve a screenshot, snapshot, or network intercept that proves the final UI state.
Known signatures:
Missing accountId in Forge context:/diagramlybypassed authentication. Restore it inAUTHENTICATED_PATHS; do not fall back to client-supplied identity.- Diagramly returns
401 Unauthorized: inspect Diagramly logs before changing API keys. API-key auth may be masking a Prisma connection failure. Confirm deep health and the localDATABASE_URL. - Prisma points at
diagramly-db-stg.postgres.database.azure.com: the local configuration is stale; use the dedicated local PostgreSQL database. - Wrangler
EMFILEorlisten EPERM: relaunch outside the sandbox; do not change application code. - Wrangler
/diagramly/job-statusfails withNetwork connection lostafter earlier polls returned200, while Diagramly later logs the job as completed: do not diagnose this as an AI/model failure. Read references/wrangler-network-connection-lost.md and follow its evidence, restart, and deployment-boundary guidance. - Forge lint errors followed by
Listening for requests: an old Forge CLI may reject newer manifest schema while the tunnel still works. Do not editmanifest.ymlwithout separate evidence. - Diagramly Node
>=24warning followed by Next.jsReady: record the warning but treat it as non-blocking for that run. - Mixpanel
before_registererrors together with Vite'sVITE_MIXPANEL_TOKEN is emptywarning mean local analytics is unconfigured; report dropped local events separately from AI Repair transport health.
Stop and clean up
- Send Ctrl+C to every managed service session and confirm exit.
- Stop
diagramly-postgresonly if this workflow created or started it. Never stop unrelated Docker/Supabase containers. - Vite, Worker, and Forge remote overrides disappear when their processes exit; no source or local config cleanup is needed.
- Do not change middleware authentication or AI Repair feature flags during cleanup.
- Inspect both
git diffandgit diff --cached; preserve all unrelated edits. - Confirm expected ports are no longer listening and run
git diff --check.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |