Generate integration docs and task bodies

Task 13364 · Done · Coder · created · updated

## Original requirement (verbatim, epic 13348) Deep research all third party integrations in Lovable (Connect) and implement all of them. Ensure the highest level of code reuse, abstract out any generic code across all integrations. Users need an easy way to connect. Documentation must be as detailed as in Lovable or better. If something needs to be done on the partner website (e.g. register an app) and it can only be done by human create a follow up task per third party with exact step by step of what user needs to do). Mark it as user only task to set up but the runner will validate it was done correctly. You can refactor anything to make working with creds more robust. ## Settled inputs Full PRD and architecture: the epic's `prd` and `architecture` artifacts (Task 13348 BA, Task 13349 Architect). Section numbers below (§3.2 item 6, AC2.3, …) refer to them. They are settled: realize them, do not reopen them. Operator decisions O1–O6 and D1–D8 bind. ## This child's scope C3, architecture §3.4. Build against the §3.1 schema pinned in the architecture (can start in parallel with C1; read TOML directly, never import the API app). - `tools/integration_docs.py` following the `tools/prompt_library.py` pattern (committed output, generated-header line, never hand-edited). - `--write`: `apps/docs/content/using-jaah/integrations/` (`_category_.json`, `index.md` table by category, `<category>/_category_.json`, `<category>/<slug>.md`) and `docs/integrations/apps/<slug>.md` per `jaah_app = true` vendor + `docs/integrations/apps/README.md`. - Reader-page headings fixed by the generator (the twelve in §3.4); frontmatter `type: how-to`, `routes: ["/credentials/new"]`, `last_verified` from the spec file's git date. Operator page headings: Redirect URIs (dev + prod derived from the single-homed connect-callback path and environment hostnames), Scopes, Knob, Registration steps, Review or verification status. - `--check` in the `tools/check.sh` quick tier: output fresh, every spec has a page with all headings, every `jaah_app` vendor has an operator page, and it FAILS on empty `agent_uses`, a key field without `help`, or fewer than 2 troubleshooting entries (risk 5). - `tools/docs_coverage.py` `GENERATED_DIRS` gains `using-jaah/integrations`. - One router row edit in `CLAUDE.md` (integrations row) pointing to `docs/integrations/apps/README.md` and the spec home. - `--task-body <slug>` prints the human registration task body of §7: title "[setup] Register the Jaah <Vendor> OAuth app", numbered steps, developer-console URL, app name "Jaah", dev and prod redirect URIs, scopes and why, where to paste ("Settings > Integrations > OAuth apps > <Vendor>", create the `oauth_app` secret, pick it in the knob; never values), and a "Runner validation" section (on dev, Connect <Vendor> with the Jaah app ends on "Connected" and Test passes). - Tests use fixture specs in the test tree; ship with at least one real example spec only if C1's loader is merged, else fixture only. Credentials & reach: - Unit tests, `./dc check quick`, `tools/check_context.py` — verified (no credential) Out of scope (PRD §6, verbatim, plus what NOT to touch): - No app-user connectors (per-end-user OAuth, connector gateway for published apps). - No "Managed by Jaah" vendor keys or credit billing; no change to `apps/api/app/billing/`. - No per-vendor API client libraries or MCP tool wrappers built by Jaah (except where the vendor's own hosted MCP server is the connector). - No Lovable action-approval UI (allow once/always). - No change to runner auth to model providers (`account_auth.py`, `Account` table) or to login/sign-in OAuth (`routes/login_oauth.py`). - No change to NodeVault crypto semantics (`credential_crypto.py` encryption tiers) beyond what a refactor needs to keep behaviour identical. - Do not break existing rows: every existing credential type and every existing row keeps working; migrations additive (two-release overlap rule). - Supabase/project-backend and git-sync are not new work; Figma plugin/.fig upload out. - Never write a credential value into a task, doc, log or PR. - Do NOT file Tasks (no licence): the human-only OAuth registration tasks are filed outside this child. Done means: - AC6.1 One reader page per vendor in `apps/docs`, at least Lovable's depth (what it enables for agents, prerequisites, step-by-step connect for OAuth and key paths with where-to-find-it steps, scopes requested and why, test, scope org/project/personal, MCP project linking for MCP vendors, manage/rotate/disconnect, limitations, troubleshooting, FAQ). — `--check` asserts each catalog vendor has a page with these headings and fails on a thin fixture (empty `agent_uses`, missing `help`, <2 troubleshooting); reader-docs route-coverage check green. The reviewer reads the page rendered from a full fixture and confirms it is readable prose, not a template with blanks. - AC6.2 One operator page per Jaah-owned OAuth app in `docs/integrations/` (redirect URI per environment, scopes, knob names, review/verification status), routed from the hub per context-architecture. — `tools/check_context.py` reachability green; a page exists per `jaah_app` fixture vendor. - AC7.1 generator half: `--task-body <slug>` for a fixture OAuth vendor prints every element listed in scope (numbered steps, console URL, app name, both redirect URIs, scopes with reasons, paste location, Runner validation) and no secret value — unit test. - `--check` runs in the quick tier — `./dc check quick` output shows the step. - AC1.5 `./dc check quick` green and `tools/check_context.py` green on this PR — the gate output cited in the PR body.

Outcome

Built tools/integration_docs.py: reader pages (build output), committed operator app pages, --task-body setup bodies; --check runs in the quick gate (green). PR #7876 merged at 163ebeca; Jaah Deploy succeeded. Assumed the reader pages are uncommitted build output, because the GENERATED_DIRS contract forbids committing them. Visual check done: the fixture page renders cleanly at 1280 and 390 px. Memory: none applied.

Pull request

Artifacts

Activity

  • Draft
  • Ready
  • Runner started
  • Runner ended (done)