Commit 292e59f
authored
fix(docs): stop publishing unsettable params, fix comment blanking (#7169)
* fix(docs): stop publishing unsettable params, fix comment blanking
generate-docs never read visibility, so every tool param appeared in the
public Input table -- including params marked visibility:'hidden', which are
shown to neither the user nor the LLM. Several are credential-shaped
(idToken, instanceUrl, apiToken, cloudId), so the docs told integrators they
could set values they cannot reach.
A hidden param is now dropped only when the block declares no subBlock for
it, matched on id or canonicalParamId -- a param can be hidden on the tool
because the block injects it while the block still renders it as a required
field the user types.
blankStringsAndComments kept the first and last character of every match.
That is right for a quoted string, where both are delimiters, but for a '//'
comment the last character is arbitrary source text, so a commented-out
'// options: [' left an unbalanced bracket that derailed the subBlock
scan. Parsing now throws rather than silently reporting that a block
exposes nothing, since that fallback was the destructive one.
Also corrects the LinkedIn w_member_social consent-screen description, which
read 'Access LinkedIn profile' for a scope that posts on the user's behalf.
* fix(docs): keep hidden params the block mapper supplies
The carve-out only recognized an identity match between a subBlock id and a
tool param, so a block that renames or assembles the value in
tools.config.params was invisible to it -- and the row was dropped even
though the user types it.
Cal.com's attendee (required) is assembled from attendeeName/attendeeEmail/
attendeeTimeZone; JSM's workspaceId comes from assetWorkspaceId; Textract
writes parameters.file from a field whose canonicalParamId is 'document',
which left the Mistral PDF Parser documenting zero inputs.
Collects params written by any accumulator identifier, not just 'result',
since the two real mappers use different names. Object keys are collected
without proving they are top-level, so a nested key can produce a false
keep -- one hard-to-set row is better than hiding a required input.
* fix(tools): reject values that cannot be a path segment
toGuardedString coerced with String(value), so an object reached the wire as
%5Bobject%20Object%5D and a boolean as 'true' -- a doomed request instead of
a clean error, on 44 live call sites. Accepts string, bigint, and finite
non-exponential numbers; everything else throws a named error.
Rejects a number whose decimal text is a rewrite rather than the caller's
value: 1e21 stringifies to '1e+21', and an integer past 2^53 has already
lost digits. A snowflake cannot be repaired here at all -- JSON.parse
destroys it before this runs -- so the doc now says it must arrive as a
string, and cites Box folderId (root = 0) instead.
Corrects the claim that the parser removes only an exact '.' or '..'; the
spec defines 11 removable spellings. The guards are sufficient because
encodeURIComponent escapes '%', not because the others cannot occur.
* test(oauth): pin the LinkedIn write-scope description
Nothing guarded the consent-screen text: utils.test.ts covered only the
Bitbucket and Reddit overrides, and the modal test stubs
getScopeDescription to identity, so a regression to a read-only label for a
posting scope would pass silently.
* fix(docs): stop a comment hijacking the id scan, unhang a Firecrawl reference
The depth-1 walk copied from the raw source at indices where the blanked
copy was at depth 1, so 'id:' inside a string value or a comment landed in
the scanned text and won the first match. With the keep-bias that now means
a phantom id can retain a param the block never exposes. Matching runs on
the blanked text and reads the literal back through a source-index map. No
block in the repo trips this today -- verified across all 305 -- so this is
a latent fix.
Removing the unsettable scrapeOptions row left five Firecrawl Search output
descriptions referencing a name that no longer appears on the page. They
now describe the response condition instead. Pointing them at 'formats' was
not an option: that subBlock is conditioned on scrape/parse/batch_scrape and
the search tool declares no such param, so it would have swapped one
dangling reference for another.
* refactor(tools): drop the unused guard API from this PR
safeUrlPath, safeOpaqueUrlSegment and SafeUrlPathOptions had zero call
sites -- 469 lines of unused API in a docs-generator change, including an
allowEmptySegments flag whose own TSDoc documents a host-takeover footgun
('//evil.com' under new URL(relative, base)). They belong with the ~693
traversal call sites that use them, where they can be reviewed against real
usage.
What stays is the part with 44 live consumers: safeUrlPathSegment now
accepts number and bigint. Staging already rejected every non-string, so
this only widens acceptance -- a differential over 87 real call-site values
shows 87 identical, 0 differing.
Also: encodeURIComponent throws an unnamed URIError on a lone surrogate,
which JSON.parse accepts, so a truncated emoji lost the param name the file
claims as its invariant. And the exponential rejection told tiny values like
1e-7 they were 'too large' when they round-trip exactly; the rejection is
right -- a path segment should not rewrite 0.0000001 into other text -- but
the stated ground was not.
* fix(docs): abort before writing on a parse failure, unhang three descriptions
The guard's own TSDoc said to fail rather than guess, because the fallback
strips every hidden param from a page. The caller did the opposite: it
caught, recorded, and continued with an empty id set, and the non-zero exit
came after every page was already written. A developer who reran, saw red,
and missed the scrollback could commit a stripped page. Parse failures are
now detected in a dry pass before anything is emitted.
The zero-id guard also only fired when the array held a literal '{', so a
subBlocks built by a helper call was silently empty, while a subBlocks whose
literals only spread ({ ...sb, required: true }) hard-failed the build. It
now fires on the destructive case alone -- reporting an unreadable array
while leaving legitimate opaque spreads, which 23 blocks rely on, untouched.
Three descriptions referenced things the reader can no longer see: Dataverse
mandated base64 after its base64 row was removed, Vanta's mimeType described
itself as useful only on that removed path, and five Drive actions told the
reader to fetch a next page with no input left to accept the token.
* chore(tinyfish): use a white block background
Matches the dominant convention (97 blocks use #FFFFFF). Regenerates the
docs page, the tool metadata, and the deployment catalog, which each carried
the previous value.
* fix(docs): correct Drive/Firecrawl/Vanta output and param descriptions
Google Drive nextPageToken: the discovery doc says the field is *absent*
at the end of the list, not empty. Say absent, and name the resource
(files/comments/permissions/revisions) per tool.
Firecrawl search outputs: restore the per-format gate the v2 OpenAPI
states ("HTML content if requested in formats"), and add that Search
exposes no input for those formats.
Vanta mimeType: the route resolves a content type from storage on every
path, so the param is never read. Say so instead of describing it as a
fallback.
Dataverse: describe the request as sending the bytes as the raw body.
* fix(docs): correct the Vanta mimeType and Firecrawl reachability wording
Vanta: the base64 branch (route.ts:100) reads params.mimeType as its only
content-type source, so "not currently applied" was wrong. Say it applies
there and is a fallback on the File branch.
Firecrawl: scrapeOptions is declared in the block's inputs map with no
subBlock, so it is reachable by a direct tool call. "Exposes no visible
input" rather than "exposes no input".
* fix(docs): never abort the generator on an unreadable subBlocks array
An unreadable `subBlocks` value used to throw, and with no spread base to
fall back on the failure was fatal: the pre-scan recorded it and
`generateAllBlockDocs` returned false, so `main` exited 1 and nothing was
written at all. Nine shipped blocks already use the non-literal form and
are saved only because they happen to spread a base — the first block
authored as `subBlocks: myFields` without one would brick `generate-docs`
and `docs:check` for the whole repository.
The author's reason for aborting was sound: an empty `userSettableParamIds`
is indistinguishable from "nothing is settable", which strips every hidden
param and publishes a wrong page. So the fix is not to treat the failure as
empty — it is to represent UNKNOWN distinctly. `extractBlockSuppliedParamIds`
now returns `{ ids, mapperIds, parseError }` with `ids: null` for UNKNOWN,
that `null` flows through `BlockConfig.userSettableParamIds`, `getToolInfo`
and `extractToolInfo`, and the filter site skips filtering entirely when it
sees it — restoring the pre-filter behaviour for that one block instead of
killing the run. `getToolInfo`'s default is `null` for the same reason: `[]`
as a default silently meant "strip everything".
The mapper scan now runs before the subBlocks scan, so a spread-inheriting
block keeps its mapper's renames when only the subBlocks scan fails. With
nothing left that can record a fatal, the dry pre-scan and its reporting
are removed.
Also fixes a silent blind spot in the mapper scan: both key regexes require
a literal `:`, so a mapper returning a shorthand property (`{ file }`) or
writing a computed key (`result['file'] = …`) dropped a real user input from
the docs with no warning. Shorthand names are read from the depth-1 comma
segments of brace-matched regions, which keeps call argument lists from
contributing names.
Verified byte-identical output: `scripts/generate-docs.ts` and
`tool-metadata:generate` reproduce all 302 generated files unchanged, the
credential-shaped hidden params stay stripped, and `check:audits` passes.
* fix(docs): name the input that gates Firecrawl search scrape output
The previous wording ended each description with "for which the Search
operation exposes no visible input", a relative clause that attaches
ambiguously and never tells the reader what controls the field. Name
scrapeOptions and note that it is hidden.
* fix(docs): say the Vanta mimeType is ignored for File-input uploads
Every return path of downloadServableFileFromStorage yields a non-empty
contentType (a literal, getMimeTypeFromExtension's GENERIC_MIME_TYPE
fallback, or resolveServableDocBytes' constants/getContentType), so
resolved.contentType always wins at route.ts:79-81 and params.mimeType is
unreachable on that branch. It is not a fallback; it is ignored.
* fix(docs): note the hidden inputs that gate Pulse html and figures output
extractFigure and returnHtml are visibility: 'hidden' with no subBlock, and
parser.ts:135-144 only forwards them when defined, so neither output can be
produced today. Say so on the output rows rather than deleting them, since
removing an output field would break saved block references.
chunks is left alone: chunking/chunkSize are user-only with real subBlocks.
* fix(docs): report a spread-only subBlocks array as unknown, not empty
extractUserSettableParamIds answered [] for a subBlocks array whose every
element spreads a fields array it cannot follow (NotionV2Block's
`[...NotionBlock.subBlocks, ...getTrigger(x).subBlocks]`). [] asserts the
block supplies nothing, so the hidden-param filter stripped every hidden
param from every tool the block owns - silently, with no parseError and so
no warning. That is the exact false-drop the null UNKNOWN state exists to
prevent.
Return null in that case and propagate it: extractBlockSuppliedParamIds no
longer folds it into [], and the block pass no longer collapses it with
`supplied.ids ?? []`. A config-level spread base still narrows the filter to
its readable fields plus the mapper's renames; with no base the filter is
switched off. An array with at least one inline id, a genuinely empty array,
and the existing throw/warn paths are unchanged - all 8 warned blocks warn
identically and every generated page is byte-identical.
Also pin the hidden-param filter on extractToolInfo's source-parsing path,
which had no coverage at all: deleting it outright left the suite green.
* fix(daytona): stop the lifecycle tools crashing on a non-string sandboxId
start/stop/delete echo sandboxId back as the output id when the API returns
no body, via params.sandboxId.trim() inside transformResponse - after the
request has already gone out. sandboxId is declared type: 'string' but
arrives unvalidated, and now that safeUrlPathSegment accepts a numeric id a
number builds a URL, sends the DELETE/START/STOP, and only then throws an
unnamed TypeError. Both the old and new behaviour fail, so this is not a
regression of a working workflow, but for delete_sandbox the side effect is
irreversible and the caller cannot tell what happened.
Fixed with a shared resolveSandboxId in utils.ts rather than a coercion at
each of the three sites: utils.ts already owns every sandbox-id helper, the
three tools already import from it, and the reasoning belongs in one place.
The encoded value cannot be reused - it is percent-encoded and would be
wrong as an output id. Behaviour for a string is unchanged.
* docs(url-path): drop the false claim that widening restores prior behaviour
The module TSDoc said the number/bigint widening fixed 'a regression for the
call sites whose pre-guard form was a bare ${params.id} template that
stringified a number fine'. It did not. Every pre-guard form in a422990
used .trim() (`/v13/deployments/${params.deploymentId.trim()}`,
`sandboxId?.trim()`), so a numeric id threw there too - no importer has ever
accepted one. The cited examples were also wrong: only Vercel and Daytona
import this module, and neither Box nor X does.
Replaced with the real motivation - params are declared type: 'string' but
nothing enforces it before the guard, and the old coercion-to-'' turned a
supplied numeric id into a misleading 'is required'. Two test comments made
the same claim ('still stringifies', 'replaced bare ${params.id} templates')
and are corrected; no assertion is weakened.
* fix(docs): correct output rows that cite inputs Sim does not send
mistral_parse: the PR removed the includeImageBase64 input row but left the
image_base64 output citing include_image_base64=true, so the page referenced
an input it no longer documents. includeImageBase64 is visibility: 'hidden'
with no subBlock, mapper or canonicalParamId, so it is annotated the same way
Pulse's html and figures were.
The sibling rows are a stronger defect: table_format, extract_header and
extract_footer appear nowhere in the repo - not as tool params, not in the
request body parser.ts builds - so tables/header/footer cited options Sim
never sends. Worded accordingly rather than as hidden inputs.
pulse structured_output cited 'if schema was provided', but there is no
schema or structuredOutput param in the tool, in pulseParseInputSchema, or in
the outgoing body, so the field is always null.
No output field is deleted - removing one changes the block's output schema
and could break saved workflow references.
* style: wrap long description literals to satisfy biome
Formatting only — regenerating both artifacts produces a byte-identical
tree, so no description text changed.
* fix(docs): cite the real Mistral options behind tables, header and footer
The previous wording was self-contradictory on tables: it described
placeholder-referenced table objects and then asserted the list is empty.
Mistral's OCR API does expose table_format, extract_header and
extract_footer. table_format defaults to inline markdown, so the separate
tables list stays empty; extract_header and extract_footer default to
false, so neither field is returned. Sim sets none of the three.
Name the option and its default in each description instead of asserting
an outcome the request body alone does not establish.1 parent 603f1c2 commit 292e59f
53 files changed
Lines changed: 1687 additions & 364 deletions
File tree
- apps
- docs/content/docs/en/integrations
- sim
- blocks/blocks
- lib
- oauth
- workspace-files
- tools
- daytona
- firecrawl
- generated
- google_drive
- microsoft_dataverse
- mistral
- pulse
- vanta
- packages/deployment-config/src
- scripts
Some content is hidden
Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
52 | 52 | | |
53 | 53 | | |
54 | 54 | | |
55 | | - | |
56 | 55 | | |
57 | 56 | | |
58 | 57 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
216 | 216 | | |
217 | 217 | | |
218 | 218 | | |
219 | | - | |
220 | 219 | | |
221 | 220 | | |
222 | 221 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
44 | 44 | | |
45 | 45 | | |
46 | 46 | | |
47 | | - | |
48 | 47 | | |
49 | 48 | | |
50 | 49 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
52 | 52 | | |
53 | 53 | | |
54 | 54 | | |
55 | | - | |
56 | 55 | | |
57 | 56 | | |
58 | 57 | | |
| |||
90 | 89 | | |
91 | 90 | | |
92 | 91 | | |
93 | | - | |
94 | 92 | | |
95 | 93 | | |
96 | 94 | | |
| |||
159 | 157 | | |
160 | 158 | | |
161 | 159 | | |
162 | | - | |
163 | 160 | | |
164 | 161 | | |
165 | 162 | | |
| |||
170 | 167 | | |
171 | 168 | | |
172 | 169 | | |
173 | | - | |
174 | | - | |
175 | | - | |
176 | | - | |
177 | | - | |
| 170 | + | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
178 | 175 | | |
179 | 176 | | |
180 | 177 | | |
| |||
195 | 192 | | |
196 | 193 | | |
197 | 194 | | |
198 | | - | |
199 | 195 | | |
200 | 196 | | |
201 | 197 | | |
| |||
287 | 283 | | |
288 | 284 | | |
289 | 285 | | |
290 | | - | |
291 | 286 | | |
292 | 287 | | |
293 | 288 | | |
| |||
313 | 308 | | |
314 | 309 | | |
315 | 310 | | |
316 | | - | |
317 | 311 | | |
318 | 312 | | |
319 | 313 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
120 | 120 | | |
121 | 121 | | |
122 | 122 | | |
123 | | - | |
124 | 123 | | |
125 | 124 | | |
126 | | - | |
127 | | - | |
128 | 125 | | |
129 | 126 | | |
130 | 127 | | |
| |||
Lines changed: 0 additions & 4 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
89 | 89 | | |
90 | 90 | | |
91 | 91 | | |
92 | | - | |
93 | 92 | | |
94 | 93 | | |
95 | 94 | | |
| |||
227 | 226 | | |
228 | 227 | | |
229 | 228 | | |
230 | | - | |
231 | 229 | | |
232 | 230 | | |
233 | 231 | | |
| |||
248 | 246 | | |
249 | 247 | | |
250 | 248 | | |
251 | | - | |
252 | | - | |
253 | 249 | | |
254 | 250 | | |
255 | 251 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
46 | 46 | | |
47 | 47 | | |
48 | 48 | | |
49 | | - | |
50 | 49 | | |
51 | 50 | | |
52 | 51 | | |
| |||
105 | 104 | | |
106 | 105 | | |
107 | 106 | | |
108 | | - | |
| 107 | + | |
109 | 108 | | |
110 | 109 | | |
111 | 110 | | |
| |||
485 | 484 | | |
486 | 485 | | |
487 | 486 | | |
488 | | - | |
489 | 487 | | |
490 | 488 | | |
491 | 489 | | |
| |||
518 | 516 | | |
519 | 517 | | |
520 | 518 | | |
521 | | - | |
| 519 | + | |
522 | 520 | | |
523 | 521 | | |
524 | 522 | | |
| |||
673 | 671 | | |
674 | 672 | | |
675 | 673 | | |
676 | | - | |
677 | 674 | | |
678 | 675 | | |
679 | 676 | | |
| |||
692 | 689 | | |
693 | 690 | | |
694 | 691 | | |
695 | | - | |
| 692 | + | |
696 | 693 | | |
697 | 694 | | |
698 | 695 | | |
| |||
723 | 720 | | |
724 | 721 | | |
725 | 722 | | |
726 | | - | |
727 | 723 | | |
728 | 724 | | |
729 | 725 | | |
| |||
741 | 737 | | |
742 | 738 | | |
743 | 739 | | |
744 | | - | |
| 740 | + | |
745 | 741 | | |
746 | 742 | | |
747 | 743 | | |
| |||
783 | 779 | | |
784 | 780 | | |
785 | 781 | | |
786 | | - | |
787 | 782 | | |
788 | 783 | | |
789 | 784 | | |
| |||
801 | 796 | | |
802 | 797 | | |
803 | 798 | | |
804 | | - | |
| 799 | + | |
805 | 800 | | |
806 | 801 | | |
807 | 802 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
75 | 75 | | |
76 | 76 | | |
77 | 77 | | |
78 | | - | |
79 | 78 | | |
80 | 79 | | |
81 | 80 | | |
| |||
102 | 101 | | |
103 | 102 | | |
104 | 103 | | |
105 | | - | |
106 | 104 | | |
107 | 105 | | |
108 | 106 | | |
| |||
129 | 127 | | |
130 | 128 | | |
131 | 129 | | |
132 | | - | |
133 | 130 | | |
134 | 131 | | |
135 | 132 | | |
| |||
0 commit comments