Validate and canonicalize generated toolkit routes by jottakka · Pull Request #1065 · ArcadeAI/docs

jottakka · 2026-07-16T14:18:05Z

Summary

validate every generated toolkit slug before it becomes a route
make integration cards, static parameters, and the sitemap share that contract
sort and deduplicate generated routes deterministically

Test plan

pnpm test

Note

Medium Risk
Touches integration routing, index link resolution, and sitemap/canonical SEO across many entry points; behavior is defensive and heavily tested but mis-slugging could hide or mis-link catalog entries.

Overview
Unifies how integration categories, slugs, and card URLs are derived so the catalog, static routes, sidebar, sitemap, and canonical metadata stay in sync.

Slug safety: getToolkitSlug now rejects unsafe path segments and returns null when no valid slug exists; route listing, index resolution, canonical paths, and llms.txt skip those entries instead of emitting bad URLs.

Shared contract: normalizeCategory and the category allow-list move to a client-safe toolkit-category module; catalog enrichment prefers toolkit JSON over design-system metadata for docsLink and category (matching route helpers).

Integrations index: resolveIndexToolkits exposes a final link (including lone bare-name → -api remaps when no sibling owns the page), drops unsluggable catalog rows, and cards use that link rather than recomputing on the client.

Data loading: Toolkit JSON and index.json are validated with Zod; malformed index rows are filtered without dropping the whole index.

SEO / discovery: The sitemap merges authored MDX URLs with listValidIntegrationLinks, dedupes by URL, and omits others integration paths that redirect; toolkit pages only set alternates.canonical when a canonical path exists.

Generator: Sidebar sync reuses shared slug/category helpers and safer JSON escaping for generated _meta.tsx files.

^{Reviewed by Cursor Bugbot for commit bac2dce. Bugbot is set up for automated code reviews on this repo. Configure here.}

vercel · 2026-07-16T14:18:11Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jul 21, 2026 5:13pm

Use one safe slug contract across route discovery, integration cards, and the sitemap so invalid or duplicate entries cannot publish broken links. Co-authored-by: Cursor <cursoragent@cursor.com>

Keep a malformed index entry from changing the source of the entire route set, and prevent redirecting fallback-category URLs from entering the sitemap. Co-authored-by: Cursor <cursoragent@cursor.com>

kamath · 2026-07-20T16:36:14Z

+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
 const isValidToolkitData = (parsed: unknown): parsed is ToolkitData =>
-  typeof parsed === "object" &&
-  parsed !== null &&
+  isRecord(parsed) &&
  "id" in parsed &&
  ("label" in parsed || "name" in parsed) &&
  "metadata" in parsed &&
-  typeof (parsed as Record<string, unknown>).metadata === "object" &&
-  (parsed as Record<string, unknown>).metadata !== null;
+  isRecord(parsed.metadata);
+
+const isToolkitIndexEntry = (value: unknown): value is ToolkitIndexEntry => {
+  if (!isRecord(value)) {
+    return false;
+  }
+
+  return (
+    typeof value.id === "string" &&
+    typeof value.label === "string" &&
+    typeof value.version === "string" &&
+    typeof value.category === "string" &&
+    (value.type === undefined || typeof value.type === "string") &&
+    typeof value.toolCount === "number" &&
+    Number.isInteger(value.toolCount) &&
+    value.toolCount >= 0 &&
+    typeof value.authType === "string"
+  );
+};
+
+const isToolkitIndexEnvelope = (
+  value: unknown
+): value is ToolkitIndexEnvelope =>
+  isRecord(value) &&
+  typeof value.generatedAt === "string" &&
+  typeof value.version === "string" &&
+  Array.isArray(value.toolkits);


cc @teallarson would these be better off as zod schemas?

100%

The generator already has a schema... we can't import that here because of module resolution BUT we can define one in app/_lib/toolkit-data.ts.

Something like:

// isToolkitIndexEntry becomes const ToolkitIndexEntrySchema = z.object({ id: z.string(), label: z.string(), version: z.string(), category: z.string(), type: z.string().optional(), toolCount: z.number().int().nonnegative(), authType: z.string(), }); ... // isToolkitIndexEnvelope becomes const ToolkitIndexEnvelopeSchema = z.object({ generatedAt: z.string(), version: z.string(), toolkits: z.array(z.unknown()), }); ... // isValidToolkitData becomes: const ToolkitDataSchema = z .object({ id: z.string(), label: z.string().optional(), name: z.string().optional(), metadata: z.object({}).passthrough(), }) .passthrough() .refine((v) => v.label !== undefined || v.name !== undefined); //etc.

cc: @jottakka !

Implemented the app-local Zod schemas as sketched (envelope + per-entry filter). See also the later note about how defensive this is — open to simplifying if you’d prefer slug-skip only.

fix: keep generated sidebar links aligned with toolkit routes Reuse the canonical toolkit slug and category validation when rendering sidebar metadata, including safely escaped labels and keys. Co-authored-by: Cursor <cursoragent@cursor.com>

Use app-local Zod schemas for toolkit data/index parsing, align the sitemap test with the others-category exclusion, and reuse the shared normalizeCategory helper in sidebar sync. Co-authored-by: Cursor <cursoragent@cursor.com>

jottakka · 2026-07-20T19:49:17Z

Addressed the Zod / sitemap / shared-normalizeCategory review feedback in the latest commits.

Remaining card↔route category contract gaps (raw toIntegrationLink category, catalog not backfilling JSON category/docsLink precedence) are intentionally in the independent follow-up: #1088

Re-requesting review for the Zod change on this PR.

teallarson

This PR is doing the right thing overall. Making sure toolkit page URLs are built the same way everywhere (cards, sitemap, sidebar, etc.).

The main feedback is: let's please clean up some duplicated logic and tests in here 🙏

teallarson · 2026-07-20T19:57:37Z

When a toolkit can’t produce a valid URL, this code throws an error in one place and catches it in another. That works, but it’s harder to follow than needed. Simpler approach: if we can’t build a URL, just skip that toolkit and move on — no throw/catch needed.

Also: Sidebar and canonical URLs now sanitize categories (so bad values like ../../outside get mapped to others), but integration card links don’t seem to do that yet. Should those use the same category cleanup so cards and pages always match?

Done — toIntegrationLink now returns null for bad slugs, and resolveIndexToolkits just skips those entries (no throw/catch).

Agreed — cards now use the same client-safe normalizeCategory helper as routes/sidebar (app/_lib/toolkit-category.ts), so unknown/empty categories map to others consistently.

teallarson · 2026-07-20T19:58:17Z

+  if (!slug) {
+    throw new Error(`Cannot build a canonical path for toolkit: ${toolkit.id}`);
+  }


similar to the comment above: invalid slugs throw errors that get caught elsewhere. Would be cleaner if “bad slug” just meant “don’t include this page” everywhere, consistently.

Done — getToolkitCanonicalPath now returns null instead of throwing; callers skip / omit canonical when there is no safe slug.

teallarson · 2026-07-20T20:00:25Z

This adds a fair amount of validation code. Is that solving a real problem we’ve hit (bad rows in index.json), or is it defensive?

If we haven’t seen bad data in practice, we might get most of the benefit from just skipping toolkits with invalid slugs.

Mostly defensive + consistency with the earlier request to use Zod here (generator already validates with Zod; we can’t import those schemas into app/_lib).

Practical benefit we kept: envelope validates, then filters bad index rows instead of dropping the whole catalog. Happy to slim this further to “skip invalid slugs only” if you’d rather — the slug skip path is now consistent everywhere either way.

Extract a client-safe toolkit-category helper so integration index links and catalog enrichment use the same category allow-list as static routes, instead of raw catalog categories that can miss pages or 404. Co-authored-by: Cursor <cursoragent@cursor.com>

Keep catalog enrichment aligned with route generation: toolkit JSON wins for docsLink, and category values are normalized before cards/filters use them. Co-authored-by: Cursor <cursoragent@cursor.com>

Return null instead of throw/catch for invalid integration/canonical URLs, reuse listValidIntegrationLinks in the sitemap (excluding others), fold in client-safe category normalization for cards, and trim overlapping sitemap and sidebar tests. Co-authored-by: Cursor <cursoragent@cursor.com>

jottakka · 2026-07-21T15:45:47Z

Addressed Teal’s latest review comments in the newest commits:

no throw/catch for bad URLs — return null and skip
cards use shared normalizeCategory (folded Normalize integration card categories to match routes #1088 into this PR)
sitemap reuses listValidIntegrationLinks (excludes others)
deduped sitemap + trimmed overlapping sidebar slug tests
left a note on the Zod thread about defensive vs slug-skip-only

#1088 can be closed as superseded.

cursor

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit baee0a0. Configure here.}

cursor · 2026-07-21T15:50:31Z

+      ...toolkit,
+      category,
+      ...(docsLink ? { docsLink } : {}),
+    };


Empty docsLink fails to override

Medium Severity

Explicit empty docsLink values from toolkit JSON are not correctly applied in getToolkitsWithDocsLinks. The docsLink ? { docsLink } : {} spread condition treats empty strings as falsy, allowing existing design-system docsLinks to persist. This can cause card slugs to diverge from generated routes, which correctly interpret an empty docsLink as a fallback to the ID slug.

^{Reviewed by Cursor Bugbot for commit baee0a0. Configure here.}

normalizeCategory can return docs-only "others", which is not in the design-system ToolkitCategory union — widen the docs toolkit type and filter helper so the Next build typecheck passes. Co-authored-by: Cursor <cursoragent@cursor.com>

Only drop a bare name when another catalog toolkit owns the -api URL; otherwise remap the card onto that page and store the resolved link on the index entry so the client does not recompute a dead bare href. Co-authored-by: Cursor <cursoragent@cursor.com>

This was referenced Jul 16, 2026

Keep generated sidebar links aligned with toolkit routes #1066

Merged

Publish canonical toolkit URLs in llms.txt #1067

Closed

vercel Bot deployed to Preview July 16, 2026 14:20 View deployment

jottakka mentioned this pull request Jul 16, 2026

Harden toolkit docs generation and indexing #1060

Closed

cursor Bot reviewed Jul 16, 2026

View reviewed changes

Comment thread app/_lib/toolkit-data.ts Outdated

Comment thread app/sitemap.ts Outdated

jottakka marked this pull request as draft July 16, 2026 18:22

fix: validate and canonicalize generated toolkit routes

35ecefc

Use one safe slug contract across route discovery, integration cards, and the sitemap so invalid or duplicate entries cannot publish broken links. Co-authored-by: Cursor <cursoragent@cursor.com>

jottakka force-pushed the split/validate-toolkit-doc-routes branch from 8fb9dfe to 35ecefc Compare July 16, 2026 20:18

vercel Bot deployed to Preview July 16, 2026 20:21 View deployment

fix: preserve valid toolkit routes on malformed input

98bf485

Keep a malformed index entry from changing the source of the entire route set, and prevent redirecting fallback-category URLs from entering the sitemap. Co-authored-by: Cursor <cursoragent@cursor.com>

vercel Bot deployed to Preview July 18, 2026 12:49 View deployment

jottakka self-assigned this Jul 18, 2026

jottakka marked this pull request as ready for review July 18, 2026 21:37

cursor Bot reviewed Jul 18, 2026

View reviewed changes

Comment thread tests/sitemap.test.ts Outdated

kamath reviewed Jul 20, 2026

View reviewed changes

vercel Bot deployed to Preview July 20, 2026 16:42 View deployment

cursor Bot reviewed Jul 20, 2026

View reviewed changes

Comment thread toolkit-docs-generator/scripts/sync-toolkit-sidebar.ts Outdated

Address review feedback on toolkit route validation.

60b763c

Use app-local Zod schemas for toolkit data/index parsing, align the sitemap test with the others-category exclusion, and reuse the shared normalizeCategory helper in sidebar sync. Co-authored-by: Cursor <cursoragent@cursor.com>

vercel Bot deployed to Preview July 20, 2026 19:36 View deployment

cursor Bot reviewed Jul 20, 2026

View reviewed changes

Comment thread app/sitemap.ts

jottakka mentioned this pull request Jul 20, 2026

Normalize integration card categories to match routes #1088

Closed

2 tasks

jottakka requested review from kamath and teallarson July 20, 2026 19:43

teallarson requested changes Jul 20, 2026

View reviewed changes

jottakka and others added 3 commits July 21, 2026 12:41

Prefer JSON docsLink and store normalized categories.

58c188d

Keep catalog enrichment aligned with route generation: toolkit JSON wins for docsLink, and category values are normalized before cards/filters use them. Co-authored-by: Cursor <cursoragent@cursor.com>

vercel Bot had a problem deploying to Preview July 21, 2026 15:46 Failure

jottakka requested a review from teallarson July 21, 2026 15:46

cursor Bot reviewed Jul 21, 2026

View reviewed changes

vercel Bot deployed to Preview July 21, 2026 17:00 View deployment

vercel Bot deployed to Preview July 21, 2026 17:13 View deployment

jottakka marked this pull request as draft July 21, 2026 18:40

Uh oh!

Conversation

jottakka commented Jul 16, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

vercel Bot commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jottakka commented Jul 20, 2026

Uh oh!

teallarson left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jottakka commented Jul 21, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot Jul 21, 2026

Choose a reason for hiding this comment

Empty docsLink fails to override

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jottakka commented Jul 16, 2026 •

edited by cursor Bot

Loading

vercel Bot commented Jul 16, 2026 •

edited

Loading

teallarson left a comment •

edited

Loading