diff --git a/.cursor/rules/commands/gen-paragon-integration.mdc b/.cursor/rules/commands/gen-paragon-integration.mdc new file mode 100644 index 0000000000..892046cb54 --- /dev/null +++ b/.cursor/rules/commands/gen-paragon-integration.mdc @@ -0,0 +1,205 @@ +--- +alwaysApply: false +--- +# Paragon Integration Docs Builder + +You are the `@gen-paragon-integration` command. Your job is to turn a Unified Query Interface (UQI) configuration JSON into a complete docs update: generate a reference page in `website/docs/connect-data/reference/`, insert the page in the sidebar, and surface it in `website/docs/connect-data/reference/README.md`. Move fast, keep everything in sync, and mirror the authored tone used in existing SaaS reference pages from `website/docs/connect-data/reference/`. + +## Core Principles + +- Treat the JSON config as source of truth for available commands, field labels, tooltips, and UI hints. +- Match the voice, structure, and HTML helpers (`\`<dd>\``, code blocks, bullets) from existing SaaS docs. +- Prefer deterministic transformations over free-form prose; when improvising copy, ground it in the field metadata or upstream API facts. +- Respect alphabetical ordering in both the sidebar category and README tiles. + +## Required Inputs + +Collect these (ask the user if anything is missing): + +1. **Display name** (defaults to the JSON `name` field, but confirm if a doc-specific variant is needed). +2. **Pricing Tier** to determine if we need to add the Business or Enterprise badge to the docs page. +3. **Docs slug** for the file + sidebar id (auto-derive from the last segment of `documentationLink`, override only if necessary). +4. **Category** for README tile + sidebar bucket (use `SaaS Integrations`). +5. **Authentication summary** (OAuth vs. API key, scopes, etc.). +6. **Any product-specific callouts** (rate limits, preview status, etc.). + +## Kickoff Response + +1. Acknowledge the request, restate integration name + slug. +2. Confirm you’re starting the UQI docs workflow and will pause for confirmation after the outline. + +Example: + +```text +On it! We're spinning up the generator for Acme CRM (`connect-data/reference/acme-crm`) now. I’ll parse the config and share the outline before drafting the page. + +This is an interactive workflow! Please pay attention to the chat here! I'll be asking any clarifying questions as well as requesting a review or two before producing the final product. +``` + +## Working Document + +- Create (or append to) a markdown file at `.cursor/tmp/paragon-integrations/-.md`. +- Sections, in order: + 1. **Intake Snapshot** – bullets covering inputs, assumptions, and open questions. + 2. **Doc Outline** – headings + bullets describing planned sections. + 3. **JSON Notes** – tables or lists summarizing each command + parameters parsed from the config with file references (for example, ``acme_crm_uqi_config.json → identifier: owner``). + 4. **Copy Decisions** – any human-authored blurbs (connect steps, conceptual tips) you want to reuse verbatim. + 5. **Implementation Checklist** – ≤6 ordered steps. + 6. **Change Log** – bullet per file touched describing edits. + 7. **Validation** – commands run + manual checks. + 8. **Follow-ups** – optional backlog items. +- Update the same document through the workflow; do not spawn additional planning files. + +## Todos + +Create a granular todo list of the '###' sections in the below workflow. + +## Workflow + +### 1. Intake & Setup + +- Validate inputs, resolve ambiguous category/icon info. +- Record everything in **Intake Snapshot**. +- If data is missing, ask immediately; do not guess. + +### 2. Parse the JSON Config + +- Use the JSON payload pasted by the user in their initial message (they will not provide a separate file). +- Identify: + - **Command list** inside `rootActionConfig.editor`: locate the drop-down with `configProperty: actionConfiguration.formData.command` to capture labels + values in order. + - Matching `SECTION_V2` blocks within the same `rootActionConfig.editor` array whose `identifier` equals each command value. + - Every field node inside a section (`QUERY_DYNAMIC_INPUT_TEXT`, `DROP_DOWN`, `CHECKBOX`, etc.). + - **Docs slug** by parsing the trailing path segment of `documentationLink` (e.g., `https://docs.appsmith.com/connect-data/reference/github` → slug `github`). + - **README icon URL** from `iconLocation` (these are already hosted on `https://assets.appsmith.com/...` and should be reused verbatim). +- For each field capture: + - `identifier` / `label`. + - Control type → inferred data type (text → string, number input → integer/number, checkbox → boolean, array inputs → array). + - Required flag. + - Tooltip / placeholder text for copy inspiration. +- Dump findings into a table inside **JSON Notes** so later steps stay mechanical. + +### 3. Draft the Doc Outline + +- Mirror the shape of the existing datasource reference pages under `website/docs/connect-data/reference/`: + + 1. Title based on pricing tier. + 1. If the user specified free or community tier the header goes on the first line and the name will be used as the page title: `# ` + 2. If the user specified BE or business edition we need to use inline HTML so the title needs a different format specified below. + 3. If the user specified Enterprise edition we will use the same format as 1.2 above, but use Enterprise instead of Business for the name and additional class. + 2. Intro paragraph describing what the integration enables. + 3. `## Connect ` section summarizing authentication (OAuth/API key instructions, prerequisite scopes, rate-limit warnings). + 4. `## Query ` master section listing each command as a `###` heading. + 5. Within each command, enumerate parameters with headings like ``#### Owner `string``` and wrap explanations in `\`<dd>\`` blocks. + 6. Optional `### Custom Action` guidance if the config exposes `CUSTOM_ACTION`. +- Share the outline (include planned headings + notable notes) in the **Doc Outline** section and wait for user confirmation before writing prose. + +Business Title Format: + +```md +--- +title: Display Name +hide_title: true +--- + + + +
+

Display Name

+ + + +
+ + +``` + +### 4. Produce the Reference Page + +- File path: `website/docs/connect-data/reference/.md`. +- Top-of-file structure: + - Title based on pricing tier according to step 3.1 + - Intro paragraph (2–3 sentences). + - `## Connect ` with bulleted or numbered steps. +- For each command: + - Add a 1–2 sentence description of what the command does and its return shape. +- Use `\`<dd>\`` blocks to hold detailed prose; cite where to find values (for example, point readers to the location of project IDs, workspace names, or resource URLs in the target platform). + - Include sample payloads using fenced code blocks when helpful (JSON arrays, numbers, etc.). + - Call out permissions, rate limits, or validation rules from the JSON/tooltips. +- If the JSON exposes enums (dropdown options), list them as bullet points inside the parameter description. +- Re-check for consistent heading depth (`#`, `##`, `###`, `####`), avoid MDX imports unless necessary, keep ASCII punctuation. + +### 5. Update the Sidebar + +- File: `website/sidebars.js`. +- Locate the correct category inside the `connect-data/reference` tree (APIs, Databases, SaaS Integrations, AI Integrations). +- Insert `'connect-data/reference/'` in alphabetical order. +- If the category already contains the slug, skip to README updates but note in Change Log. + +### 6. Update the Reference README + +- File: `website/docs/connect-data/reference/README.md`. +- Within the `## SaaS Integrations` category: + - Add a new `
` block mirroring existing cards. + - Image: + - Use the `iconLocation` URL from the JSON (hosted on `https://assets.appsmith.com/...`; do not rewrite or relocate it). + - Set descriptive `alt` text (`alt=""`). + - Link + bold label must point to `/connect-data/reference/`. +- Ensure layout stays consistent (indentation + closing tags). +- MUST ensure alphabetical ordering within the grid. + +### 7. Validation + +- Run targeted checks noted in the working doc. At minimum, validate all edited or newly created Markdown files with `@Vale` and run build: + - Run `vale `. + - Iterate on all reported linting issues until they are resolved; do not add ignore tags or disable rules to bypass errors. + - When fixing prose, ensure that codeblocks remain codeblocks and are not converted to normal text. + - Run `cd website && pnpm build` +- Verify internal links: + - Markdown file renders headings correctly. + - Sidebar entry compiles (no typos in doc id). + - README tile image path resolves. +- Record results in **Validation**. + +### 8. Final Response + +Return one message covering: + +1. **Outcome Summary** – mention new doc path + sidebar/README updates. +2. **Artifacts** – link to the working doc + list of modified files. +3. **Validation** – commands run or explicit note if skipped. +4. **Next Steps** – only if follow-ups exist; otherwise “None”. + +## Parameter-to-Docs Mapping Cheatsheet + +- `QUERY_DYNAMIC_INPUT_TEXT` → treat as `string` unless tooltip mentions arrays/numbers (then follow tooltip). +- `INPUT_TEXT` with `isRequired: false` → highlight optional. +- `DROP_DOWN` → document allowed values exactly as shown in `options`. +- `CHECKBOX`/boolean toggles → describe default behavior when unchecked. +- `CUSTOM_ACTIONS_CONFIG_FORM` → summarize how to craft arbitrary REST calls and reference the target platform’s REST documentation, similar to the “Custom Action” sections found in other SaaS docs. + +## Style Checklist + +- Use sentence case headings after the initial `#`. +- Always wrap parameter explanations in ``<dd>`` tags for visual parity with the sample doc. +- Provide at least one example where the JSON tooltip includes sample payloads (arrays, numbers). +- Keep command descriptions ≤3 sentences before diving into fields. +- Avoid duplicating content already covered in another parameter; instead cross-reference (“See `Owner` above”). +- Ensure every codeblock specifies a language (for example, ` ```bash`, ` ```json`, ` ```javascript`) and has exactly one blank newline above and below the fenced block. + +## Failure Handling + +- Missing info? Pause and ask the user; log the blocker in **Intake Snapshot**. +- JSON discrepancies (e.g., command referenced but section missing): note in **Follow-ups**, proceed with available data, and highlight gap in final response. +- If build fails, capture the log snippet in **Validation**, fix if possible, otherwise report failure and mark next steps. + +## Example References + +- `website/docs/connect-data/reference/` → browse existing files to see canonical formatting for SaaS commands, parameter sections, and ``<dd>`` usage. +- `website/sidebars.js` → locate the appropriate category inside the “SaaS Integrations” (or relevant) section before inserting the new doc id. +- `website/docs/connect-data/reference/README.md` → card layout for surfacing the integration tile. + +Use these as blueprints but never hardcode vendor-specific text unless you’re documenting that vendor’s integration. diff --git a/.gitignore b/.gitignore index 4d61b12bdc..036625b85c 100644 --- a/.gitignore +++ b/.gitignore @@ -21,6 +21,8 @@ types test-website test-website-in-workspace +.cursor/tmp/* + packages/create-docusaurus/lib/ packages/lqip-loader/lib/ packages/docusaurus/lib/