spiderly 19.8.4 → 19.8.6

package/agent/skills/report-gap/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: report-gap
+description: Use the moment you're forced into a workaround because the clean Spiderly-native path didn't exist — you looked for a lifecycle hook, an override, an entity attribute, or a generator option and it was structurally missing, so you had to bypass or copy generated code, or reach into framework internals. Also use when the gap is in Spiderly's own skills, plugins, or docs — a skill that should have fired but didn't, or skill/doc content that was missing, stale, or wrong for the case you hit. Turns that gap into a pre-filled GitHub issue URL against filiptrivan/spiderly that the user copies and submits. Also invoke manually to report a Spiderly limitation. NOT for hacks in the consumer's own business logic, NOT for ordinary bugs in your own code.
+allowed-tools: Bash(node:*)
+---
+
+# Report a Spiderly gap
+
+When Spiderly forces you into a workaround — or its own guidance lets you down — that's signal the maintainer needs. This skill captures the gap as a **pre-filled GitHub issue URL** against `filiptrivan/spiderly`. It does **not** file anything — it prints a URL the user opens, reviews, and submits themselves.
+
+## When this fires (and when it doesn't)
+
+The trigger is sharp on purpose. Two shapes of gap qualify:
+
+**A framework-code gap** — *all* of these are true:
+
+- You wanted to do something the Spiderly way (a hook, an override, an entity attribute, a generator/CLI option).
+- You looked for that clean path and it was **structurally missing** — not just unfamiliar.
+- So you fell back to a hack: bypassing or **copying generated code to edit it**, reaching into framework internals, or duplicating logic Spiderly should own.
+
+**A gap in Spiderly's own skills, plugins, or docs** — the guidance layer itself failed you:
+
+- A Spiderly skill should have fired for your task but its description didn't match, so you worked blind until someone pointed you at it.
+- Skill or doc content you followed was **missing the case you hit, stale** against current Spiderly behavior, **or outright wrong** — and following it cost you a wrong turn.
+
+For these, use `--labels "agent-reported,documentation"` and name the skill/doc file in the body. The same sharpness applies: "the docs could say more about X" is not a gap; "the docs told me the wrong thing / the skill never fired" is.
+
+Do **NOT** use it for:
+
+- Workarounds in the **consumer's own business logic** — that's the consumer's problem, not a Spiderly gap.
+- Ordinary bugs in code you wrote, or a clean path you simply hadn't found yet (look harder first).
+- **Non-interactive sessions** (a subagent, CI, a scheduled run): there's no one to copy the URL. Just note the gap in your final output and move on — never block.
+
+## Flow
+
+1. Confirm it's a real Spiderly gap against the bar above.
+2. Fill the six-section body template (below), **sanitized**.
+3. Build the URL with the helper script.
+4. Print a short summary **and the URL** to the user. They copy it, open it, review the pre-filled form, and click Submit. Nothing is filed until they do.
+5. If there's a workaround code snippet, **show it in chat** and tell the user to paste it as the first comment after the issue opens — keep it **out of the URL** (see the length gotcha).
+
+## Be ruthlessly concise
+
+Brevity is the whole game here — it keeps the URL well under the 414 ceiling **and** means a single short comment instead of several. Concretely:
+
+- **One or two sentences per section.** No filler, no restating the title, no hedging. The maintainer reads fast.
+- **Trim any snippet to the 1–3 lines that actually show the gap** — not the whole class. A trimmed snippet usually fits in **one** comment; never spread it across multiple.
+- If everything is tight enough, you won't need a comment at all. Prefer that.
+
+## Body template
+
+Fill every section, one or two sentences each — prose only, no code snippet (that goes in a single comment if needed).
+
+```markdown
+### What I was trying to do
+<the clean goal, one or two sentences>
+
+### The clean Spiderly approach I expected
+<the hook / override / attribute / option you looked for>
+
+### Why it didn't work
+<what was structurally missing>
+
+### The workaround I used instead
+<the hack, described in prose — code snippet posted as a comment below>
+
+### Suggested fix
+<what Spiderly could add: a new hook, attribute, generator option, ...>
+
+### Context
+Spiderly version: <from the consumer's package.json / .csproj>. Project type: <e.g. .NET 9 + Angular 19>. (No proprietary code included.)
+```
+
+## Sanitize — this is a public repo
+
+The issue lands in a **public** repository, and you're running inside someone's (possibly private) codebase. Before building the URL, strip: secrets/keys, real entity/table/field names that reveal the business, customer data, internal URLs. Describe the *shape* of the problem, not the proprietary specifics. When in doubt, generalize.
+
+## Build the URL
+
+Title is a **plain summary with no `[agent-reported]` prefix** — the label carries provenance. Pipe the body on stdin:
+
+```bash
+node scripts/build-issue-url.mjs \
+  --title "No hook to override generated validator message" \
+  --labels "agent-reported,enhancement" <<'EOF'
+### What I was trying to do
+...
+### Context
+Spiderly version: 19.8.2. Project type: .NET 9 + Angular 19.
+EOF
+```
+
+It prints the encoded `https://github.com/filiptrivan/spiderly/issues/new?...` URL. Defaults: `--labels` is `agent-reported,enhancement`; the repo is hardcoded. The script does **not** open a browser — print the URL for the user to copy.
+
+> **Why a script instead of building the URL by hand:** encoding a multi-line body into a query string by hand (`%0A` for every newline, escaping `#`, `&`, spaces) is error-prone, and one wrong escape gives the user a broken form. `URLSearchParams` gets it right every time. If Node is somehow unavailable, encode by hand as a last resort — but Node ships with every Spiderly app.
+
+## Gotcha — URL length (414)
+
+GitHub returns **414 URI Too Long** around **8 KB**, and URL-encoding inflates the body ~3×. A code snippet in the body blows past this fast. So the snippet **never goes in the URL** — show it in chat and have the user paste it as a single comment. The script warns on stderr if the URL crosses ~7500 chars; if you see that warning, you wrote too much — **cut the prose down**, don't move it to comments.
+
+## The `agent-reported` label
+
+The pre-filled `&labels=agent-reported` only sticks if that label **exists** in the repo — GitHub silently drops unknown labels (you'd still get `enhancement`). **In `filiptrivan/spiderly` the label already exists — there is no setup left to do, so never prompt the maintainer to create it.** Only when targeting a fork that lacks it, create it once (authenticated `gh`):
+
+```bash
+gh label create agent-reported \
+  --repo <owner>/<fork> \
+  --color BFD4F2 \
+  --description "Gap surfaced by a coding agent forced into a Spiderly workaround"
+```

package/agent/skills/report-gap/scripts/build-issue-url.mjs

@@ -0,0 +1,82 @@
+// Build a pre-filled GitHub "new issue" URL for the Spiderly repo.
+//
+// Why a script: hand-encoding a multi-line issue body into a query string is
+// error-prone (every newline, space, #, & must be escaped). URLSearchParams
+// does it correctly every time. This script ONLY builds and prints the URL —
+// it never opens a browser and never files anything. The user copies the
+// printed URL, opens it, reviews the pre-filled form, and clicks Submit.
+//
+// Usage:
+//   echo "<markdown body>" | node build-issue-url.mjs --title "..." [--labels "a,b"]
+//   node build-issue-url.mjs --title "..." --body-file ./body.md
+//
+// Flags:
+//   --title       (required) plain issue title, NO "[agent-reported]" prefix
+//                 (the label carries provenance)
+//   --labels      (optional) comma-separated; default "agent-reported,enhancement"
+//   --body-file   (optional) read body from a file instead of stdin
+//
+// Fails loudly (non-zero exit) on a missing title or empty body.
+
+import { readFileSync } from "node:fs";
+
+const REPO = "filiptrivan/spiderly"; // hardcoded: this skill reports Spiderly gaps only
+const URL_SOFT_LIMIT = 7500; // GitHub returns 414 around ~8 KB; warn before we get there
+
+function arg(name) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i !== -1 ? process.argv[i + 1] : undefined;
+}
+
+function fail(message) {
+  console.error(`build-issue-url: ${message}`);
+  process.exit(1);
+}
+
+async function readStdin() {
+  if (process.stdin.isTTY) return ""; // nothing piped in
+  process.stdin.setEncoding("utf8");
+  let data = "";
+  for await (const chunk of process.stdin) data += chunk;
+  return data;
+}
+
+const title = arg("title");
+if (!title || !title.trim()) {
+  fail('missing --title. Pass a plain title, e.g. --title "No hook to override generated validator message"');
+}
+if (/^\s*\[agent-reported\]/i.test(title)) {
+  fail('drop the "[agent-reported]" prefix from --title — the label already carries provenance');
+}
+
+const labels = (arg("labels") ?? "agent-reported,enhancement").trim();
+
+const bodyFile = arg("body-file");
+let rawBody;
+if (bodyFile) {
+  try {
+    rawBody = readFileSync(bodyFile, "utf8");
+  } catch (err) {
+    fail(`could not read --body-file "${bodyFile}": ${err.message}`);
+  }
+} else {
+  rawBody = await readStdin();
+}
+const body = rawBody.trim();
+if (!body) {
+  fail("empty body. Pipe the markdown body on stdin, or pass --body-file <path>.");
+}
+
+const params = new URLSearchParams({ title: title.trim(), body });
+if (labels) params.set("labels", labels);
+
+const url = `https://github.com/${REPO}/issues/new?${params.toString()}`;
+
+if (url.length > URL_SOFT_LIMIT) {
+  console.error(
+    `build-issue-url: WARNING — URL is ${url.length} chars (soft limit ${URL_SOFT_LIMIT}). ` +
+      "GitHub returns 414 around 8 KB. Trim the body and post any code snippet as a comment instead."
+  );
+}
+
+console.log(url);

package/agent/skills/spiderly-upgrade/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: spiderly-upgrade
+description: Upgrade a Spiderly consumer app's package version (NuGet + npm) to a newer Spiderly release. Use when the user asks to upgrade Spiderly, bump the Spiderly version, jump to a newer Spiderly release, or migrate to a newer Spiderly package version. Do NOT use for EF Core schema migrations (see ef-migrations skill).
+---
+
+# Spiderly Upgrade
+
+End-to-end version upgrade for apps consuming Spiderly via the NuGet packages (`Spiderly.Shared`, `Spiderly.Security`, `Spiderly.Infrastructure`, `Spiderly.SourceGenerators`) and the `spiderly` npm package. (`Spiderly.CLI` is a `dotnet tool`, not a project reference — out of scope.)
+
+Invocation forms:
+
+- `/spiderly-upgrade <version>` — explicit target (e.g. `21.2.0`)
+- `/spiderly-upgrade latest` — fetch latest stable from NuGet
+- `/spiderly-upgrade` — same as `latest`
+
+Spiderly has no backward-compatibility commitment — every release can break public API. This skill closes that gap by reading what changed on GitHub, scanning the user's app for what actually affects them, asking once, then applying everything with build-verification and self-healing retries.
+
+## Step 1 — Pre-flight
+
+Follow Spiderly's fail-loudly convention: every refused-to-start condition exits non-zero with an actionable message. Cache the parsed csproj and `package.json` contents from this step — Step 6 reuses them.
+
+1. **Locate the app.** Glob `**/*.csproj` and `**/package.json` from CWD (skip `node_modules`, `bin`, `obj`). Identify the Backend (csproj with `Spiderly.*` PackageReferences) and Frontend (package.json with `"spiderly"` dep). If neither is found, exit:
+
+   > Not a Spiderly app: no `Spiderly.*` PackageReference or `spiderly` npm dep found from this directory.
+
+2. **Reject local-dev consumers.** If any csproj has a `<ProjectReference Include="...\spiderly\...">` pointing at a sibling Spiderly checkout, exit:
+
+   > This skill is for NuGet/npm consumers. You're using local ProjectReferences to a sibling `spiderly/` directory — upgrade by `git pull` in that directory instead.
+
+3. **Require clean git state.** Run `git status --porcelain`. If non-empty, exit:
+
+   > Working tree must be clean before upgrading. Commit or stash your changes first — the upgrade will make many edits, and a clean tree is your `git restore .` safety net.
+
+4. **Detect current version.** Read all `Spiderly.*` `PackageReference` `Version=` values across every csproj, plus the `"spiderly"` value in `Frontend/package.json`. They should agree. If they drift, list the values and ask the user which to treat as "current".
+
+5. **Multi-solution monorepo.** If multiple Backend dirs (each with their own Spiderly refs) exist, ask the user which one to upgrade. One app per invocation.
+
+## Step 2 — Resolve target version
+
+- If arg is `latest` or omitted: WebFetch `https://api.nuget.org/v3-flatcontainer/spiderly.shared/index.json`, parse the `versions` array, pick the highest stable (no `-` suffix), confirm with the user.
+- Otherwise validate the arg as `X.Y.Z` (or `X.Y.Z-preview.N` if the user is explicitly opting into a preview — warn that preview release notes are usually thin).
+- Reject downgrades: if target < current, exit `Downgrades are not supported. To downgrade, edit Spiderly.* PackageReference Version= attributes and the "spiderly" npm dep manually, then run dotnet restore and npm install.`
+- Reject no-op: if target == current, exit `Already on {version}.`
+
+## Step 3 — Fetch what changed
+
+Fire these two WebFetch calls **in parallel** (same message, two tool calls):
+
+1. **Diff between tags.** `https://api.github.com/repos/filiptrivan/spiderly/compare/v{current}...v{target}` (three-dot syntax). Response has `files[]` with `filename` and `patch`. Filter client-side to the user-facing paths below — GitHub's compare endpoint has no path-filter parameter. If `truncated: true`, warn the user the diff was capped and proceed with what was returned.
+
+2. **All release notes in one call.** `https://api.github.com/repos/filiptrivan/spiderly/releases?per_page=100`. Returns every release. Filter in-memory to tags `v{X.Y.Z}` strictly above current and ≤ target. Concatenate `body` fields in ascending version order. (One call, not N — Spiderly's total release count fits in one page.)
+
+On 403 rate-limited: ask the user to export `GH_TOKEN` (no scopes needed) and retry.
+
+### User-facing file paths (filter the compare response client-side)
+
+**Include** — changes here affect consumers:
+
+- `Spiderly.Shared/**/*.cs` — public attributes, contracts, builders
+- `Spiderly.Security/**/*.cs` — auth interfaces, attributes
+- `Spiderly.Infrastructure/**/*.cs` — DI extensions, base services
+- `Spiderly.SourceGenerators/**/*.cs` — generator output shape changes (may break consumer overrides)
+- `Spiderly.Shared/Helpers/NetAndAngularFilesGenerator.cs` — init template; drift here implies existing apps may need mirroring edits (new service registration, new file in scaffold)
+- `Angular/projects/spiderly/src/lib/**/*.ts`
+- `Angular/projects/spiderly/src/public-api.ts`
+
+**Exclude** — `*.Tests/**`, `tests/**`, `Spiderly.CLI/**` (consumers don't reference CLI internals — flag CLI flag/command changes only via release notes), `Angular/node_modules/**`, `Angular/dist/**`, `.github/**`, `.claude-plugin/**`, `claude-plugins/**`, `*.csproj`, `package.json`, `*.md`.
+
+## Step 4 — Impact scan and plan
+
+Read the combined release notes + filtered diff in a single pass. Identify changes that likely affect a consumer:
+
+- New / renamed / removed public types, methods, attributes in `Spiderly.Shared`, `Spiderly.Security`, `Spiderly.Infrastructure`
+- Changes in source-generator output shape (consumers may have overrides that no longer compile)
+- Changes in the init template — signals what NEW apps look like; existing apps may need to mirror (e.g. a new `services.AddTransient<X>()`)
+- Changes in the Angular library's public surface (`public-api.ts` exports, component/service contracts)
+- CLI command/flag changes (if the user has CI scripts invoking `spiderly`)
+
+For each candidate change:
+
+1. Describe in one line what changed.
+2. Use Grep over the user's codebase to find real usages. Read context, don't just match symbol names blindly.
+3. If no real usages exist, drop the item from the plan.
+
+Plan format:
+
+```
+Spiderly upgrade: 19.5.0 → 21.2.0
+
+Code edits (N items affect you):
+  1. <change> — <N> usages in <files>
+  2. ...
+
+Manual steps after upgrade:
+  - <step the agent can't do for you>
+
+Version bumps: Spiderly.*  19.5.0 → 21.2.0  (4 csproj + Frontend/package.json[ + .claude/settings.json legacy-plugin removal])
+
+After approval: apply → bump → migrate guidance + config → restore + install (parallel) → build → agent-sync. Up to 2 build-fix retries on failure.
+```
+
+## Step 5 — Single approval gate
+
+Present the plan and ask the user explicitly. Don't proceed without a clear yes.
+
+## Step 6 — Apply
+
+In this order. A failure at any step is a hard stop until the recovery procedure in Step 7.
+
+1. **Code edits.** Apply each plan item via Edit. Read each target file first.
+2. **Version bumps.** Iterate the csproj list cached in Step 1: rewrite every `<PackageReference Include="Spiderly.X" Version="OLD" />` to the new version. Rewrite `"spiderly": "OLD"` in `Frontend/package.json`. Don't re-glob.
+3. **Migrate agent guidance off the legacy plugin.** Spiderly's AI-agent guidance now ships *inside* the `spiderly` npm package (projected by `spiderly agent-sync` in item 7 below), replacing the old `spiderly@spiderly` Claude Code plugin. If `.claude/settings.json` contains `extraKnownMarketplaces.spiderly` and/or `enabledPlugins."spiderly@spiderly"`, remove just those keys (leave any other settings intact; delete the file only if it becomes an empty `{}`). No settings file or no spiderly entries → skip.
+4. **Migrate `spiderly.json` → `.spiderly/config.json`.** Recent Spiderly moved the generator/api config out of a root `spiderly.json` into `.spiderly/config.json`. If the app has a `spiderly.json` registered via `<AdditionalFiles Include="spiderly.json" />`, `git mv` it to `.spiderly/config.json` and rewrite that csproj line to `<AdditionalFiles Include=".spiderly/config.json" />`. No `spiderly.json` → skip.
+5. **Restore packages in parallel.** Same message, two Bash calls: `dotnet restore` in Backend and `npm install` in Frontend. They share no locks. If either fails, surface the actual error and exit.
+6. **`dotnet build`** from the Backend dir. On failure, go to Step 7.
+7. **Sync agent guidance.** Run `spiderly agent-sync` from the app root. It reads the freshly-installed `Frontend/node_modules/spiderly/agent` bundle and reconciles `AGENTS.md` (doc index + `@AGENTS.md` in `CLAUDE.md`) and `.claude/skills/spiderly-*` (junctions, pruning any renamed/removed skill). Idempotent; non-fatal if it warns the bundle is missing (an older package predating the bundle).
+
+## Step 7 — Build-failure recovery (max 2 retries)
+
+Loop up to 2 times — stop on first green build:
+
+1. Scan output for the **first `SPIDERLY`-prefixed diagnostic** (these are the root cause; downstream `CS0246` errors about missing `*DTO` types are noise). Fall back to the first `CS` error only if no SPIDERLY diagnostic exists.
+2. Read the offending file. Apply the most likely fix using the error message + the diff context from Step 3.
+3. Re-run `dotnet build`.
+
+After 2 failed attempts, stop:
+
+```
+Upgrade halted after 2 build-fix attempts.
+
+Build error still present:
+  <paste the diagnostic>
+
+Attempted fixes:
+  1. <what>
+  2. <what>
+
+The in-progress upgrade is in your working tree.
+  - To roll back: git restore .
+  - To continue manually: fix the error, run `dotnet build`, then commit.
+```
+
+## Step 8 — Done
+
+Print summary:
+
+- Versions bumped (from → to)
+- Files edited (count + list)
+- Manual steps remaining (re-print verbatim from the plan)
+
+Do **not** auto-commit. The user reviews the diff and commits themselves.
+
+## Refresh AI-agent guidance
+
+After the new `spiderly` package is installed, project the version-matched guidance:
+
+```bash
+spiderly agent-sync
+```
+
+This is idempotent and reconciling: it rewrites the static `AGENTS.md` docs pointer, ensures `CLAUDE.md` imports it (`@AGENTS.md`), and adds/refreshes/prunes `.claude/skills/spiderly-*` junctions so renamed or removed skills self-heal. Re-running it is always safe.
+
+## Rules
+
+- **Never auto-revert.** Leave the in-progress state in the working tree so the user can see what was attempted; they roll back with `git restore .`
+- **Never silently drop a candidate breaking change.** If the diff shows one but you can't determine impact, include it in the plan as "verify manually".

package/agent/skills/verify-ui/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: verify-ui
+description: Log past Spiderly's email-code auth wall to visually verify the running Angular admin panel — screenshot a page, click through a flow, or dogfood a UI change without writing a test. Use when asked to "verify the admin UI", "check this page renders", "screenshot the admin panel", "does this screen look right", or to eyeball a change in the live app. For authoring Playwright test suites or debugging CI traces, use the e2e-testing skill instead.
+allowed-tools: Bash(node:*), Bash(npx:*), Bash(agent-browser:*), Bash(curl:*)
+---
+
+# Verify Spiderly Admin UI (past the auth wall)
+
+The Spiderly admin panel sits entirely behind a passwordless **email-code** login, which blocks any agent that just opens `localhost:4200`. This skill gets you a logged-in session headlessly so you can look at the real UI.
+
+**This is for ad-hoc visual verification, not test authoring.** If you're writing a Playwright suite or debugging a failing CI run, use the `e2e-testing` skill — it owns the canonical login helper and the PrimeNG selector quirks.
+
+## The core idea (driver-agnostic)
+
+In development, `SecurityService.SendLoginVerificationEmail` returns the verification code **in the response body** (when `ShouldShowVerificationCodeInNotification()` is true — i.e. `IWebHostEnvironment.IsDevelopment()` **and** SMTP is not fully configured, so `emailingService.IsConfigured()` is false). So no email inbox is needed. The flow is always:
+
+1. `POST /api/Security/SendLoginVerificationEmail` `{ email, browserId }` → read `verificationCode`.
+2. `POST /api/Security/Login` `{ verificationCode, email, browserId }` → get `accessToken` + `refreshToken`.
+3. In the browser, set three `localStorage` keys on the admin origin, then reload:
+   - `access_token`, `refresh_token`, `browser_id` (the last must equal the `browserId` used above).
+4. Wait for `sidebar-menu` to appear — that confirms you're authenticated and in.
+
+Step 1+2 are scripted for you: **`scripts/get-admin-token.mjs`** (pure Node, no dependencies, fails loudly).
+
+```bash
+node scripts/get-admin-token.mjs --email admin@example.com
+# → { "accessToken": "...", "refreshToken": "...", "browserId": "verify-ui" }
+```
+
+Flags: `--email` (required — must have the **Admin role**, see gotcha below), `--api` (default `http://localhost:5000`), `--browser-id` (default `verify-ui`).
+
+> **Don't trust the default ports — read them from the project.** The `:5000` (backend) and `:4200` (admin) values used throughout this skill are only the Spiderly scaffold defaults; any project can change them. The authoritative values live in **`Frontend/src/environments/environment.ts`**:
+> - `apiUrl` (e.g. `http://localhost:5000/api`) → pass its **origin** (strip the trailing `/api`) to `--api`.
+> - `frontendUrl` (e.g. `http://localhost:4200`) → the admin URL to open in the browser.
+>
+> The backend's actually-bound port is in **`Backend/<App>.WebAPI/Properties/launchSettings.json`** → `applicationUrl`. If a connection fails or the project looks non-standard, read those files first instead of assuming the defaults below.
+
+> **CORS origin must match.** The backend allows one origin (`appsettings.json` → `Spiderly.Shared:FrontendUrl`). Serving the admin on a different port blocks every API call and surfaces as a misleading **"Connection Lost"** toast + bounce to `/login` (looks like an auth failure).
+
+## Prerequisites — validate before doing anything
+
+The token script already fails loudly on the first two. Confirm all four up front so you don't burn a turn on a half-running stack:
+
+| Requirement | How to confirm | If it fails |
+|---|---|---|
+| Backend reachable | the script's first POST succeeds (port from `launchSettings.json` → `applicationUrl`) | start the backend (`dotnet run` in the WebAPI project) |
+| Dev-mode code exposure on | response contains `verificationCode` | run backend with `ASPNETCORE_ENVIRONMENT=Development` **and** SMTP unconfigured (`IsConfigured()` false) — a fully-configured SMTP setup does a real send even in Development |
+| Admin SPA running | `frontendUrl` (from `environment.ts`, default `:4200`) responds | start the admin (`npm start` in `Frontend/`) |
+| Account has Admin role | login lands on a populated sidebar, not an empty shell | use an Admin-roled email (see gotcha) |
+
+## Driver A — agent-browser (preferred when available)
+
+[agent-browser](https://www.skills.sh/vercel-labs/agent-browser/agent-browser) gives an agent live, interactive control — ideal for clicking through a flow and screenshotting. If it isn't installed, install once (or skip to Driver B):
+
+```bash
+npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser
+npm i -g agent-browser && agent-browser install   # CLI + Chrome binary
+```
+
+Then log in and verify (replace `<AT>` / `<RT>` with the script's output, and `verify-ui` if you changed `--browser-id`):
+
+```bash
+# 1. Open the admin origin first so localStorage writes land on the right origin
+agent-browser open http://localhost:4200
+
+# 2. Inject the session (use --stdin so quoting can't corrupt the values)
+agent-browser eval --stdin <<'EOF'
+localStorage.setItem('access_token', '<AT>');
+localStorage.setItem('refresh_token', '<RT>');
+localStorage.setItem('browser_id', 'verify-ui');
+EOF
+
+# 3. Navigate straight to the page under review — this load reads the just-set
+#    localStorage; the sidebar-menu wait confirms auth (it renders on every
+#    authenticated route, so no separate dashboard round-trip is needed).
+agent-browser open http://localhost:4200/administration/banner \
+  && agent-browser wait "sidebar-menu" \
+  && agent-browser wait --load networkidle \
+  && agent-browser screenshot --full
+```
+
+From here use the normal agent-browser loop (`snapshot -i` → `click`/`fill` → re-snapshot) to drive a flow. Close the session when done: `agent-browser close`.
+
+## Driver B — Playwright (guaranteed floor, zero extra install)
+
+Every Spiderly app ships Playwright for e2e, so this always works without installing anything new. Run it **from the `Frontend/` directory** so `playwright` resolves. It reuses the same token script.
+
+Save as `Frontend/verify-page.mjs` (gitignore it — it's a throwaway), then:
+
+```bash
+node verify-page.mjs --email admin@example.com \
+  --url http://localhost:4200/administration/banner \
+  --token-script <skill-dir>/scripts/get-admin-token.mjs --out ./_verify.png
+```
+
+It reuses the same token helper (`--token-script`, required — pass the absolute path to this skill's `scripts/get-admin-token.mjs`), so the localStorage key names and `sidebar-menu` wait stay defined in one place. Keep that injection block in sync with `e2e-testing`'s `authenticateBrowser` if either changes.
+
+```js
+import { chromium } from "playwright";
+import { execFileSync } from "node:child_process";
+
+function arg(name, fallback) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i !== -1 ? process.argv[i + 1] : fallback;
+}
+
+const email = arg("email");
+const url = arg("url", "http://localhost:4200");
+const api = arg("api", "http://localhost:5000");
+const out = arg("out", "./_verify.png");
+const tokenScript = arg("token-script");
+if (!email || !tokenScript) {
+  throw new Error("Pass --email <admin-roled account> and --token-script <path to get-admin-token.mjs>");
+}
+
+const { accessToken, refreshToken, browserId } = JSON.parse(
+  execFileSync("node", [tokenScript, "--email", email, "--api", api], { encoding: "utf8" })
+);
+
+const browser = await chromium.launch();
+try {
+  const page = await browser.newPage();
+  // Tokens must be set on the admin origin before the app reads them, so land there first.
+  await page.goto(new URL(url).origin);
+  await page.evaluate(
+    ([at, rt, bid]) => {
+      localStorage.setItem("access_token", at);
+      localStorage.setItem("refresh_token", rt);
+      localStorage.setItem("browser_id", bid);
+    },
+    [accessToken, refreshToken, browserId]
+  );
+  await page.goto(url);
+  await page.locator("sidebar-menu").waitFor({ state: "visible", timeout: 15000 });
+  await page.screenshot({ path: out, fullPage: true });
+  console.log(`Saved ${out}`);
+} finally {
+  await browser.close();
+}
+```
+
+## Gotcha — login can succeed but show an empty shell
+
+`SendLoginVerificationEmail` mints a session for any email when `OnlyAdminCanAddUsers` is `false` (the default) — a not-yet-existing user is **auto-provisioned with no role**, so the sidebar comes up empty and most pages are inaccessible. If you can log in but see nothing useful, the account lacks permissions. Use an email that already has the **Admin role** (role/permission assignment is seeded per-project, e.g. via a `PermissionSeeder`). Permissions hang off roles, not off the user directly.
+
+## Why a separate skill from e2e-testing
+
+Same login mechanism, different job: `e2e-testing` is for *authoring* Playwright suites and debugging CI traces; this is for *looking at* the running admin UI ad-hoc. Keeping them separate keeps each skill's trigger sharp. The login flow lives in both only as a thin reference — `e2e-testing` holds the canonical Playwright helper (`authenticateBrowser`); this skill holds the dependency-free token script and the agent-browser path.

package/agent/skills/verify-ui/scripts/get-admin-token.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// Obtain a Spiderly admin session token without an email inbox.
+//
+// In development, SecurityService.SendLoginVerificationEmail returns the
+// verification code directly in the response body (when
+// ShouldShowVerificationCodeInNotification() is true). This script uses that
+// to complete the passwordless login flow headlessly and print the tokens an
+// admin SPA expects in localStorage.
+//
+// The --api default (http://localhost:5000) is the Spiderly scaffold default only.
+// The authoritative backend URL for a project is the origin of `apiUrl` in
+// Frontend/src/environments/environment.ts (strip the trailing /api); the bound
+// port is in Backend/<App>.WebAPI/Properties/launchSettings.json -> applicationUrl.
+// Pass --api explicitly when a project overrides the default.
+//
+// Usage:
+//   node get-admin-token.mjs --email admin@example.com
+//   node get-admin-token.mjs --email admin@example.com --api http://localhost:5000 --browser-id verify-ui
+//
+// Output (stdout, JSON): { "accessToken": "...", "refreshToken": "...", "browserId": "..." }
+// Exit code 0 on success, 1 on any failure (fails loudly — no partial success).
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (!token.startsWith("--")) continue;
+
+    // Support both --flag=value and --flag value.
+    const eq = token.indexOf("=");
+    if (eq !== -1) {
+      args[token.slice(2, eq)] = token.slice(eq + 1);
+      continue;
+    }
+
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (next !== undefined && !next.startsWith("--")) {
+      args[key] = next;
+      i++;
+    } else {
+      args[key] = true;
+    }
+  }
+  return args;
+}
+
+function fail(message) {
+  console.error(`[get-admin-token] ${message}`);
+  process.exit(1);
+}
+
+const args = parseArgs(process.argv.slice(2));
+
+const email = args.email;
+const apiBaseUrl = (args.api || "http://localhost:5000").replace(/\/+$/, "");
+const browserId = args["browser-id"] || "verify-ui";
+
+if (!email || email === true) {
+  fail(
+    "Missing required --email. Pass an account that has the Admin role in the target DB.\n" +
+      "  Usage: node get-admin-token.mjs --email admin@example.com [--api http://localhost:5000] [--browser-id verify-ui]"
+  );
+}
+
+async function postJson(path, body) {
+  let response;
+  try {
+    response = await fetch(`${apiBaseUrl}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    fail(
+      `Could not reach the backend at ${apiBaseUrl}${path}. Is the backend running?\n  ${err.message}`
+    );
+  }
+
+  const text = await response.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : {};
+  } catch {
+    json = { raw: text };
+  }
+
+  if (!response.ok) {
+    fail(`POST ${path} failed (HTTP ${response.status}): ${text || "(empty body)"}`);
+  }
+
+  return json;
+}
+
+const sendCodeResult = await postJson("/api/Security/SendLoginVerificationEmail", {
+  email,
+  browserId,
+});
+
+const verificationCode = sendCodeResult.verificationCode;
+if (!verificationCode) {
+  fail(
+    "SendLoginVerificationEmail did not return a verificationCode.\n" +
+      "  This means dev-mode code exposure is OFF (ShouldShowVerificationCodeInNotification() returned false).\n" +
+      "  The gate is IsDevelopment() && !IsConfigured(): run the backend with ASPNETCORE_ENVIRONMENT=Development\n" +
+      "  AND with SMTP left unconfigured. A fully-configured SMTP setup (EmailSender.Email + EmailSenderPassword\n" +
+      "  + SmtpHost + SmtpPort) does a real email send instead, even in Development."
+  );
+}
+
+const loginResult = await postJson("/api/Security/Login", {
+  verificationCode,
+  email,
+  browserId,
+});
+
+if (!loginResult.accessToken || !loginResult.refreshToken) {
+  fail(
+    `Login did not return tokens. Response: ${JSON.stringify(loginResult)}\n` +
+      "  The email may not exist, or the code expired. Check the account and retry."
+  );
+}
+
+process.stdout.write(
+  JSON.stringify(
+    {
+      accessToken: loginResult.accessToken,
+      refreshToken: loginResult.refreshToken,
+      browserId,
+    },
+    null,
+    2
+  ) + "\n"
+);