fix(docs): stop publishing unsettable params, fix comment blanking

Merged
WA
2mo ago
+1687-364

Summary

  • generate-docs never read visibility, so every tool param was published in the public Input table — including visibility: 'hidden' params, which are shown to neither the user nor the LLM. Several are credential-shaped (idToken, instanceUrl, apiToken, cloudId), so the docs advertised values integrators cannot set.
  • A hidden param is kept when the block exposes it — either a subBlock whose id/canonicalParamId matches, or a tools.config.params mapper that writes it. Cal.com's required attendee is assembled from three fields, JSM's workspaceId comes from assetWorkspaceId, and Textract writes parameters.file from a field whose canonicalParamId is document — none of which an identity match sees. The rule is biased toward keeping: measured across every block, it retains 25 mapper-only rows and all 25 are genuinely mapper-written.
  • blankStringsAndComments kept the first and last character of every match. Correct for a quoted string, where both are delimiters; wrong for a // comment, whose last character is arbitrary source. A commented-out // options: [ left an unbalanced bracket that derailed the subBlock scan, and the failure was silent — indistinguishable from "this block exposes nothing", the destructive fallback.
  • safeUrlPathSegment now accepts number and bigint.

On apps/sim/tools/url-path.ts

This file is already on staging with 44 importers (Vercel ×43, Daytona ×1) — an earlier draft of this description wrongly called it a new module with none, which is the sort of claim that would let a reviewer skip auditing it.

The change is strictly more permissive. Staging's toGuardedString was typeof value === 'string' ? value.trim() : '', so it already rejected every non-string; it just reported "is required" for a value the caller did supply. A numeric id from an LLM — Box's root folder is 0 — was one of those. A differential over 87 real call-site values (project/deployment/team/alias ids, hostnames incl. punycode, UUIDs, every URL-reserved char, unicode, all 12 dot-segment spellings) gives 87 identical, 0 differing.

An earlier revision of this branch added an unused safeUrlPath / safeOpaqueUrlSegment / SafeUrlPathOptions API and then removed it again, so that churn is not visible in the diff against staging — do not go looking for a deletion. Against the merge base this file is +156/−27. Those three names have zero references anywhere in the monorepo; the traversal call sites that need them will land separately.

Type of Change

  • Bug fix

Testing

check:audits 36/36 · docs:check · test:generators · type-check · turbo run lint:check — all exit 0. Full apps/sim/tools suite green.

Generator verified idempotent across consecutive runs; the pages with no tool-source change regenerate byte-identically.

Audited adversarially beyond the review bots, which found — and this PR now fixes — three reader-facing docs regressions (a Dataverse description mandating a removed parameter, a Vanta row whose only stated purpose was a removed sibling, five Google Drive actions documenting a pagination loop the reader cannot close), a lone-surrogate URIError that lost the param name, and a false "too large" message on values that round-trip exactly.

Net docs effect: ~268 unsettable rows removed, 19 wrongly-removed rows restored, no row removed that a block exposes to the user.

Checklist

  • Code follows project style guidelines
  • Self-reviewed my changes
  • Tests added/updated and passing
  • No new warnings introduced
  • I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)