Skip to content

feat(bot-info): add site setup wizard#397

Open
tripodsan wants to merge 28 commits into
mainfrom
bot-info-setup-wizard
Open

feat(bot-info): add site setup wizard#397
tripodsan wants to merge 28 commits into
mainfrom
bot-info-setup-wizard

Conversation

@tripodsan

Copy link
Copy Markdown
Contributor

What

Turns the post-install bot-info widget into an interactive site setup wizard. After AEM Code Sync is added to a repo, the user lands here with org, site, user, optional url query params and a one-time token in the URL fragment. The widget now:

  1. Captures the #token into sessionStorage and scrubs it from the URL.
  2. Authenticates to the admin API with that token (Authorization: token …, no interactive-login fallback) and loads the org/site config.
  3. Presents a single scrollable form:
    • Organization users — shown only for new orgs (new_org=true); editable email + role rows; saving is blocked when the list is empty.
    • Site administrators — editable rows seeded from access.json.
    • Content source — URL + type (DA / SharePoint / Google Drive / AEM / BYOM), auto-detected from the URL.
  4. On submit, diffs and posts org users (add/remove/role-update), rebuilds access.json, and updates the site's content.source.
  5. Shows a confirmation ("What we did") rendered from the actual saved configuration, with a "Create your content" link to https://da.live/#/{org}/{site}.

Why

The previous widget was a static confirmation page that didn't match the real setup state and required users to bounce out to separate admin tools. This guides new sites through user and content-source setup in one step, right after install.

How it was tested

  • npm run lint — clean.
  • npm test — 552/552 pass, including new unit tests for the extracted pure logic in wizard.js (detectContentSourceKind, buildContentSource, diffOrgUsers).
  • Pure logic was extracted from DOM/fetch per TESTING.md; DOM building and API calls are exercised manually.

Reuses parseUsersFromAccessConfig/buildAccessConfig (user-admin), content-source detection (site-admin), and the shared helix-admin.js client.

Note: the widget is loaded by a CMS page via the widget block, and the full happy path needs a real new-org setup token from the bot redirect, so it can't be fully exercised on the preview without that flow. Raw widget markup: https://bot-info-setup-wizard--helix-tools-website--adobe.aem.page/widgets/bot-info/bot-info.html

Test plan

  • Lint passes (npm run lint)
  • Test suite passes (npm test, 552/552)
  • Unit tests added for new pure logic in wizard.js

🤖 Generated with Claude Code

Turn the post-install bot-info widget into an interactive setup wizard.
Using the one-time token stored from the URL fragment, it authenticates
to the admin API, loads the org/site config, and presents a single
scrollable form to validate users and the content source before saving.

- Org users section (new orgs only, gated on new_org=true): editable
  email + role rows, blocked from saving when empty.
- Site administrators section: editable rows seeded from access.json.
- Content source: URL + type (DA/SharePoint/Google Drive/AEM/BYOM),
  auto-detected from the URL.
- On submit, diffs and posts org users, rebuilds access.json, and updates
  the site content source, then shows a confirmation that reflects the
  actual saved configuration.

Pure logic (content-source detection/build, org-user diffing) is
extracted into wizard.js with unit tests.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync

aem-code-sync Bot commented Jun 25, 2026

Copy link
Copy Markdown

Hello, I'm the AEM Code Sync Bot and I will run some actions to deploy your branch and validate page speed.
In case there are problems, just click a checkbox below to rerun the respective action.

  • Re-run all PSI checks
  • Re-run failed PSI checks
  • Re-sync branch
Commits

@aem-code-sync

aem-code-sync Bot commented Jun 25, 2026

Copy link
Copy Markdown
Page Scores Audits Google
📱 /widgets/bot-info/bot-info.html PERFORMANCE A11Y SEO BEST PRACTICES SI FCP LCP TBT CLS PSI
🖥️ /widgets/bot-info/bot-info.html PERFORMANCE A11Y SEO BEST PRACTICES SI FCP LCP TBT CLS PSI

Comment thread widgets/bot-info/bot-info.html Outdated
Comment thread widgets/bot-info/bot-info.js Outdated
Comment thread widgets/bot-info/bot-info.js Outdated
Comment thread widgets/bot-info/bot-info.js Outdated
@claude

claude Bot commented Jun 25, 2026

Copy link
Copy Markdown
Contributor

Code Review

Summary

Well-structured PR converting a static confirmation page into an interactive setup wizard. Pure logic is cleanly extracted into wizard.js with solid test coverage (diffOrgUsers, detectContentSourceKind, buildContentSource); DOM and API work stays in bot-info.js. The three-phase load → wizard → success flow is clear, and the sequential-reduce pattern for API mutations is appropriate. The token-scrub-from-URL on load is a nice security touch.

Issues Found

SHOULD FIX:

  • Missing rel="noopener noreferrer" on target="_blank" links — without it, the opened page can access window.opener and navigate the parent frame. Two places fixed via inline suggestions:
    • Discord link in bot-info.html
    • Dynamically-created DA link in populateSummary (bot-info.js)
    • Note: the pre-existing <a target="_blank" class="bot-info-preview"> and <a target="_blank" class="bot-info-live"> links in bot-info.html are not part of this diff but should be fixed alongside.

CONSIDER:

  • sessionStorage key 'token' is too generic — other tools on the same origin (e.g. tools.aem.live) could accidentally read or overwrite it. A namespaced key like 'bot-info-setup-token' avoids the collision. Inline suggestions posted for both setItem and getItem.

  • "Create your content" link always points to da.live — the confirmation screen links to https://da.live/#/{org}/{site} even when the user chose SharePoint or Google Drive as their content source. Consider either omitting the link for non-DA sources or pointing to the right starting point (e.g. the SharePoint folder).

  • Default role for new user rows is 'admin' (wizard.js:944) — when a user clicks "Add user" and no role is preselected, createUserRow defaults to ['admin']. A more conservative default ('author') reduces the risk of accidental over-provisioning.

Verdict

REQUEST CHANGES — Fix the rel="noopener noreferrer" issues (two inline suggestions above) before merge. The CONSIDER items are optional but worth a quick look.

- add rel="noopener noreferrer" to all target="_blank" links
- namespace the setup token session key (bot-info-setup-token)
- default new org-user rows to the least-privileged author role
  (site-admin rows still default to admin)

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 07:01 Inactive
Use the DA editor URL only for DA sources; for SharePoint/Google
Drive/AEM/BYOM, link straight to the provided content source URL.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 07:04 Inactive
Revert new-row default back to admin (this is the initial setup) and
add an "admin roles" documentation link to both user sections.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 07:09 Inactive
…site

Rename the "Site administrators" section to "Site users" with matching
copy, and visually emphasize the org and site names throughout.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 07:31 Inactive
Each user row now shows a compact roles summary button that expands the
role pills on demand, reducing clutter for the 8 available roles.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 07:35 Inactive
Keep the role pills visible but only surface the primary admin role by
default; the remaining roles collapse behind an inline … link (auto
-expanded when one of them is already selected).

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 07:45 Inactive
Mirror the other admin tools by adding a console block that logs each
admin API request/response during load and save, plus info/success/error
status messages, so the setup flow is more transparent.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 07:52 Inactive
The site config response already contains the access sub-object, so drop
the redundant separate access.json read during load.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 07:55 Inactive
DA is now the default content source with a fixed, read-only URL
(content.da.live/{org}/{site}). A "use a different content source"
checkbox reveals the non-DA type selector and an editable URL.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 08:25 Inactive
Wrap the DA intro text and fixed URL in one container and hide it when
"use a different content source" is checked. The previous .bot-info-field
display rule also overrode the aria-hidden hide.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 08:55 Inactive
When config can't be loaded (e.g. an expired token / 401), the error
screen now offers a "Continue to your site" button that shows an adapted
confirmation: next-steps and DA defaults only, without the inaccurate
"what we did" summary.

Refactors the confirmation into a shared showConfirmation() used by both
the save and skip paths.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 11:45 Inactive
Soften the error copy, point to the continue button, and ask for a plain
screenshot instead of a console screenshot.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 11:53 Inactive
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 11:55 Inactive
Rename the AEM content source kind to "AEM Authoring" and add a suffix
field (default .html) that's shown for AEM Authoring and BYOM sources and
written to content.source.suffix.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 12:11 Inactive
- cap the suffix input width and apply the shared input styling
- clear the suffix when switching to BYOM; default to .html for AEM
- assert buildContentSource never sets a suffix for DA/SharePoint/Google

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 12:15 Inactive
Only BYOM exposes the editable suffix field; AEM Authoring keeps it
hidden while still writing its .html default to content.source.suffix.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 12:24 Inactive
Auto-select the content source type from the URL only for definite
provider matches (SharePoint/Google/AEM); never override the user's
selection with the BYOM fallback.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 12:27 Inactive
The user selects the content source type explicitly; remove the URL
change listener that auto-switched it.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 12:30 Inactive
Capture token_id (the admin api key id) from the fragment alongside the
token and store it. After the config saves successfully, delete that key
from the org config (new orgs) or site config, so the one-time setup key
can't be reused. Best-effort: a failed deletion is logged but doesn't
fail the setup.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 12:38 Inactive
Remove the setup token and key id from session storage once the config
is saved and the key is revoked.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard June 26, 2026 12:51 Inactive
Writing the whole site config after updating access.json overwrote the
just-added site users with the stale copy read on load. Update only the
content sub-config instead.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard July 9, 2026 12:05 Inactive
Write just { source } rather than merging the stale loaded content, so
the content update carries only the intended change.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard July 9, 2026 12:10 Inactive
Show a per-type example URL in the content source URL field, updating as
the content source type changes.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard July 9, 2026 13:24 Inactive
Rename "AEM Authoring" back to "AEM" and give it a fixed, non-editable
URL (https://api.aem.live/{org}/sites/{site}/source, type markup). The
URL field is read-only when AEM is selected; detection recognizes the
new api.aem.live format (and legacy adobeaemcloud).

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard July 9, 2026 15:21 Inactive
Drop suffix support from the AEM kind so buildContentSource never
attaches a suffix for AEM; only BYOM carries one now.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard July 10, 2026 12:23 Inactive
@aem-code-sync
aem-code-sync Bot temporarily deployed to bot-info-setup-wizard July 15, 2026 09:11 Inactive
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant