3 Commits

Include renames

Author	SHA1	Message	Date
Waleed	ae2147645c	fix(cli): resolve findings from a full command-surface audit (#6788) ... * fix(cli): resolve findings from a full command-surface audit Exercised all 147 commands against a live deployment. Fixes the defects that surfaced, plus the docs and generator drift they exposed. Transport - Stop following redirects. A bare domain that 301s to www silently converted POST to GET and dropped the body, so reads worked while every write failed with a misleading validation error and login returned 405. Both the client and the device flow now explain the redirect and name the endpoint to configure, rather than carrying credentials off-origin. - Report a non-JSON response as one instead of printing the HTML page. - Name the personal-API-key remedy on a workspace-key refusal, reading the machine-readable code the API actually sends. - Drop union-branch noise from validation errors that contradicted itself. - Show paging progress on stderr for multi-page fetches. Output - Clamp record values for table only. text is the format built for pipes, and it was truncating signed URLs and tool source mid-value. - Infer timestamp, duration, bytes and boolean formatting for API-owned keys so undeclared commands stop printing raw ISO and float ms. Skips user-defined table cells and leaves json/yaml on the raw payload. - Render a declared-but-absent field as an em dash; billing credits were vanishing silently. Paths, naming and validation - Percent-encode folder paths per segment and decode them for display, so a folder reads and types as the name shown in the app. - Reject a malformed endpoint where it is set and where it resolves, instead of crashing with a URL parse trace. - Request the detail level logs list's own columns need; its workflow column could never populate. - Rename three commands that described themselves wrongly and align two flags with their siblings. Old spellings still work: hidden, warned on stderr, and kept out of help and docs. - Verify whoami against the API, separating a bad key from an unreachable endpoint, and report the workspace by name. - Correct the --yes help text, which advertised skipping a prompt that does not exist. Docs - Teach the docs generator that a flag required by the runtime is required, and that hidden commands are not documented. * fix(cli): clear the paging progress line when a page fails Progress is written without a trailing newline so it can be overwritten in place, and both paging loops cleaned it up only on success. A page that threw part-way through left `fetched 1200…` on the line the error was then printed onto, so the two ran together. * fix(cli): name a working API root when an endpoint redirects The suggested endpoint was the redirect target's origin, which drops a path prefix. A self-hosted deployment reached at https://host/sim was told to set https://www.host — not an API root, so following the advice replaced one broken endpoint with another. Derive it by stripping the request's own path from the target instead, so a prefix survives, and say nothing about --set-endpoint when the target resolves to the endpoint already configured: a trailing-slash or path normalization redirect keeps the origin, and naming the value the caller already has explains nothing. The login poll shared both faults and now shares the helper.	2026-08-17 15:55:04 -07:00
Waleed	025ea4d2bd	fix(docs): serve JSON-LD in the HTML, fix sidebar spacing, and tighten the CLI guides (#6763) ... * docs(cli): use -g for the install, and cut the prose that was not pulling weight `--global` is valid but `-g` is what every comparable CLI documents, and the long form only came from the package README. Also drops the yarn tab: it read `yarn global add sim`, which works on Yarn 1 only — Yarn 2 removed global installs, so that command fails for anyone on a modern Yarn. Adds `npx sim` for running without installing. The guides had accumulated design rationale that belongs in code comments rather than user docs — why the filter grammar is JSON, why the config section naming is asymmetric, why an unexpected error keeps its stack trace. Surveying how gh, Vercel, Turborepo, Deno, Bun and Supabase write theirs, none carry that kind of justification, and callouts are reserved for content whose absence produces a wrong result rather than for general asides. So: 1016 lines to 763, and 12 callouts to 3. The three that remain are the pairing-code check, that `sim logout` does not revoke the key, and the `--limit 100` default on `batch-delete`/`batch-update`, which silently truncates a larger match. Troubleshooting drops the entries whose error message already contained its own fix and keeps the seven whose cause is not obvious. * fix(docs): render JSON-LD as native script tags so it reaches the HTML All four structured-data blocks — WebSite, TechArticle, BreadcrumbList, SoftwareApplication — were rendered with `next/script`, which never emitted a script tag. Measured on a production build, `/api-reference/getting-started` contained zero `<script type="application/ld+json">` elements; the payload existed only in the `__next_s` client-injection queue and the RSC flight data, so anything reading the served HTML saw no structured data at all. React was also logging "Encountered a script tag while rendering React component" on every page. `next/script` is for loading and executing JavaScript. JSON-LD is data, and Next's own guidance is a native `<script>` in the component. `serializeJsonLd` already escapes the `<` character to its unicode form, which is the sanitization that guidance calls for, so only the element changes. Same build, after: three valid tags per page with `WebSite` in `<head>`, and the injection queue gone entirely. * fix(docs): scope the flush-separator rule to a container's first separator `[data-separator]:not([data-separator] ~ [data-separator])` was meant to keep the first sidebar group flush against the top padding, but `~` only reaches siblings, so it also matched the first separator inside every expanded folder. Under Self-Hosting, "Install" lost its top margin and crowded the "Architecture" link above it — 25px of gap where "Configure" and "Operate" below it had 40px. `:first-child` expresses the intent directly. Only the four sidebar roots open with a separator; every nested folder starts with a page, so the intended case still goes flush and nothing else changes. * fix(docs): move the flush-separator rule onto the separator component Keeps the styling with the component that owns it, per the repo standard, and lets the global rule be deleted outright rather than corrected — `global.css` now only loses a rule in this PR. Tailwind's `first:` variant compiles to the same `:first-child` selector, so behavior is unchanged: the build emits `.first\:mt-0:first-child{margin-top:0}` and the prerendered HTML carries the class on the separator.	2026-08-15 20:39:34 -07:00
Waleed	fed891f69d	docs(cli): add a CLI docs section generated from the command tree (#6762) ... * docs(cli): add a CLI section, generated from the command tree The `sim` CLI shipped with no coverage in the docs site. Adds a fourth top-level tab for it, and moves Academy last. The command reference is generated. `sim` exposes 147 leaf commands across 33 groups, most of them derived at runtime from the v2 route contracts, so a hand-written reference would be wrong the week after it was written. The generator walks the command tree `buildProgram()` hands to commander — the same tree the terminal parses — rather than re-deriving it from the contract, which would be a second implementation free to describe commands nobody can invoke. `check:cli-docs` is a zero-arg `check:*` script, so the existing audit runner picks it up and stale pages fail CI. Generating against the real tree surfaced a collision it had been hiding: `bulkUpdateKnowledgeDocuments` and `updateKnowledgeDocument` both derived to `sim knowledge documents update`. Commander resolves a duplicate to the first match, so the bulk form shadowed the single-document one and its flags were unreachable while still appearing in `--help`. The bulk form is now `batch-update`, matching how `tables rows batch-delete`/`batch-update` already handle the same REST overload, and the generator fails on any duplicate path so the next one cannot land silently. Five hand-written guides cover install, auth, configuration, output formats, and scripting. Also corrects two commands in the package README that do not exist as documented (`tables columns <tableId>`, and `--sort score:desc`, which is JSON). * docs(cli): document every flag from the contracts, add troubleshooting and a single-page reference The command reference was structurally complete but said almost nothing: 223 of 377 flags rendered as "Set sort by" because the CLI only ever read flag help from its own contract overrides, and fell back to restating the flag name. The prose already existed. The v2 route contracts carry 931 `.describe()` calls and the OpenAPI specs publish all of them — 327 parameters and 282 body properties, 100% coverage — but the generated operation table dropped every one, carrying only a per-operation summary. It now carries the field descriptions, the path-parameter descriptions, and positional help, so `--help` and the docs explain a flag the same way the API reference does. Placeholder descriptions are now zero, and 147/147 commands, 377/377 flags and 130/130 arguments are documented. `check:cli-docs` fails on a request field with no `.describe()` rather than letting it render as documentation that says nothing. Also in this pass: - Commands are root-level sidebar entries under a Commands heading rather than a folder, and headings are the command's description, so the table of contents distinguishes entries at the first word instead of repeating "sim knowledge documents …" fourteen times. A guard fails the build if two descriptions on a page collide, since they would share an anchor. - A single-page `Complete reference` carrying all 147 commands, for in-page search and for agents fetching `/cli/reference.mdx`. It keys on exact command paths because descriptions are only unique within a group. - A troubleshooting page, with every message copied from the source. - Table columns are sized by a local component; the flag column was starved while descriptions kept most of the row empty. - The prerelease install channels are dropped from the docs and the package README, which is what npm renders. * fix(docs): match the CLI tab by path segment, and escape backslashes before pipes `pathname.includes('/cli')` also matches `/integrations/clickup` and `/integrations/clickhouse`, so both existing integration pages lit the CLI tab and unlit Documentation. Matching is now per path segment. Anchoring to the start would not work either — a non-default locale prefixes the path, as in `/ja/cli` — so the segment is matched wherever it sits. Table cells now double a backslash before escaping pipes. A value ending in one turned `a\` + `|` into `a\\|`, which the table parser reads as an escaped backslash followed by an unescaped pipe, splitting the cell early. Nothing in the command surface contains a backslash today, so this was latent rather than visible. The reference page's global options table is two-column and was being wrapped in `CommandTable`, which sizes the second column for the `Required` cell of the three-column tables and crushed the description into 5.5rem. It now matches the overview page, which leaves that table unsized.	2026-08-15 19:25:34 -07:00