Repository navigation
Reconcile current API docs and Context preview contracts - #152
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars. ⚙️ Run configuration
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
7 issues found across 17 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="content/docs/source/api-reference/sites/overview.mdx">
<violation number="1" location="content/docs/source/api-reference/sites/overview.mdx:114">
P2: Custom agent: **Enforce Clear Code Style and Maintainability Practices**
This hand-authored MDX file is 137 lines after the addition, exceeding the rule's under-100-line cap. Split the deletion/cancellation material into a separate page or restructure the overview so each source file stays under 100 lines.</violation>
<violation number="2" location="content/docs/source/api-reference/sites/overview.mdx:114">
P3: This new section introduces `DELETE /api/sites/{id}` as a public REST operation, but the "Endpoints and tools" table at the top of this same page still has no DELETE row (it lists `GET /api/sites`, `POST /api/sites`, `GET /api/sites/{id}`, the four PATCH actions, `GET .../signups`, and `POST /api/sites/assets`). Readers and LLMs that discover operations through the table won't find deletion. Add a row such as `| \`DELETE /api/sites/{id}\` | \`delete_site\` | \`{ "deleted": true, "id": "..." }\` |` to keep the table in sync with the prose.</violation>
<violation number="3" location="content/docs/source/api-reference/sites/overview.mdx:116">
P3: The section says to send `revision` and `generationToken` with the DELETE but never states how they are transmitted (JSON body, query parameters, or headers), and no curl example is given. Every other parameterized request on this page is a JSON body sent to a PATCH (e.g. `{"action":"generate","revision":0}`), so a reader will guess; many HTTP clients also strip DELETE bodies, which makes transport worth stating explicitly. Confirm against the API source and specify the transport, ideally with one curl example.</violation>
</file>
<file name="scripts/refresh-contract-inventory.py">
<violation number="1" location="scripts/refresh-contract-inventory.py:105">
P2: Custom agent: **Enforce Clear Code Style and Maintainability Practices**
`main()` now adds unmatched-contract validation to a 134-line script, violating the under-100-line and single-responsibility requirements. Extract this validation into a separate cohesive module and keep `main()` focused on orchestration.</violation>
<violation number="2" location="scripts/refresh-contract-inventory.py:109">
P3: The gate depends on a prose marker, not just the structured field: it requires the literal substring `availability: pending`/`availability: retired` inside the operation description, so an otherwise correct `x-recoup-availability` value fails the refresh whenever the description formats the disclosure differently (e.g. `**Status:** pending`). It is also brittle on exact-path lookup: `['paths'][route]` uses the trailing-slash-stripped route from the docs key, while `social.json` stores `/api/spotify/artist/` with a trailing slash, so if that route ever became unmatched the script would raise an unhandled `KeyError` instead of the intended `SystemExit`. Consider gating on the structured field alone and normalizing the path lookup.</violation>
</file>
<file name="content/docs/source/api-reference/openapi/context.json">
<violation number="1" location="content/docs/source/api-reference/openapi/context.json:55">
P1: Custom agent: **Enforce Clear Code Style and Maintainability Practices**
This OpenAPI source file now spans 1,327 lines, violating the under-100-line maintainability rule; split the action schemas and single-source the MCP mapping instead of inlining both representations.</violation>
</file>
<file name="content/docs/source/api-reference/openapi/releases.json">
<violation number="1" location="content/docs/source/api-reference/openapi/releases.json:1049">
P2: Custom agent: **Enforce Clear Code Style and Maintainability Practices**
`releases.json` is a 6,733-line, multi-domain source file, and this change adds another 295 lines to it. Split the OpenAPI contracts into smaller single-domain files before extending this spec further.</violation>
</file>
Reply with feedback, questions, or to request a fix.
View guided diff | Turn on auto-fix | Re-trigger cubic
| @@ -32,7 +32,7 @@ | |||
| "post": { | |||
There was a problem hiding this comment.
P1: Custom agent: Enforce Clear Code Style and Maintainability Practices
This OpenAPI source file now spans 1,327 lines, violating the under-100-line maintainability rule; split the action schemas and single-source the MCP mapping instead of inlining both representations.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/source/api-reference/openapi/context.json, line 55:
<comment>This OpenAPI source file now spans 1,327 lines, violating the under-100-line maintainability rule; split the action schemas and single-source the MCP mapping instead of inlining both representations.</comment>
<file context>
@@ -49,38 +49,819 @@
+ "properties": {
+ "action": {
+ "type": "string",
+ "const": "list_release_cases"
+ },
+ "organization_id": {
</file context>
| dispositions = json.loads((out / 'operation-dispositions.json').read_text()) | ||
| operations = implementation_operations(api, docs, dispositions) | ||
| implemented = {item['method'] + ' ' + item['path'] for item in operations} | ||
| for key in sorted(set(docs) - implemented): |
There was a problem hiding this comment.
P2: Custom agent: Enforce Clear Code Style and Maintainability Practices
main() now adds unmatched-contract validation to a 134-line script, violating the under-100-line and single-responsibility requirements. Extract this validation into a separate cohesive module and keep main() focused on orchestration.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At scripts/refresh-contract-inventory.py, line 105:
<comment>`main()` now adds unmatched-contract validation to a 134-line script, violating the under-100-line and single-responsibility requirements. Extract this validation into a separate cohesive module and keep `main()` focused on orchestration.</comment>
<file context>
@@ -102,6 +102,12 @@ def main():
dispositions = json.loads((out / 'operation-dispositions.json').read_text())
operations = implementation_operations(api, docs, dispositions)
implemented = {item['method'] + ' ' + item['path'] for item in operations}
+ for key in sorted(set(docs) - implemented):
+ method, route = key.split(' ', 1)
+ operation = json.loads((root / docs[key]).read_text())['paths'][route][method.lower()]
</file context>
|
|
||
| Unpublish with `action: "unpublish"`, or `unpublish_site`. Agents should publish only when explicitly instructed. | ||
|
|
||
| ## Delete and cancel generation |
There was a problem hiding this comment.
P2: Custom agent: Enforce Clear Code Style and Maintainability Practices
This hand-authored MDX file is 137 lines after the addition, exceeding the rule's under-100-line cap. Split the deletion/cancellation material into a separate page or restructure the overview so each source file stays under 100 lines.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/source/api-reference/sites/overview.mdx, line 114:
<comment>This hand-authored MDX file is 137 lines after the addition, exceeding the rule's under-100-line cap. Split the deletion/cancellation material into a separate page or restructure the overview so each source file stays under 100 lines.</comment>
<file context>
@@ -111,6 +111,12 @@ The public page is `https://chat.recoupable.dev/s/{id}`.
Unpublish with `action: "unpublish"`, or `unpublish_site`. Agents should publish only when explicitly instructed.
+## Delete and cancel generation
+
+Delete only when explicitly instructed. Send `DELETE /api/sites/{id}` with the current `revision`. Include `generationToken` when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job.
</file context>
| @@ -17,7 +17,7 @@ | |||
| "/api/catalogs/{catalogId}/streams": { | |||
There was a problem hiding this comment.
P2: Custom agent: Enforce Clear Code Style and Maintainability Practices
releases.json is a 6,733-line, multi-domain source file, and this change adds another 295 lines to it. Split the OpenAPI contracts into smaller single-domain files before extending this spec further.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/source/api-reference/openapi/releases.json, line 1049:
<comment>`releases.json` is a 6,733-line, multi-domain source file, and this change adds another 295 lines to it. Split the OpenAPI contracts into smaller single-domain files before extending this spec further.</comment>
<file context>
@@ -1040,6 +1045,16 @@
}
}
+ },
+ "402": {
+ "description": "A single task fetched by id is blocked by its owner plan. Returns plan_limit with task_count or min_cadence and billingUrl. Ordinary listing does not apply this pre-run gate.",
+ "content": {
</file context>
|
|
||
| ## Delete and cancel generation | ||
|
|
||
| Delete only when explicitly instructed. Send `DELETE /api/sites/{id}` with the current `revision`. Include `generationToken` when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job. |
There was a problem hiding this comment.
P3: The section says to send revision and generationToken with the DELETE but never states how they are transmitted (JSON body, query parameters, or headers), and no curl example is given. Every other parameterized request on this page is a JSON body sent to a PATCH (e.g. {"action":"generate","revision":0}), so a reader will guess; many HTTP clients also strip DELETE bodies, which makes transport worth stating explicitly. Confirm against the API source and specify the transport, ideally with one curl example.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/source/api-reference/sites/overview.mdx, line 116:
<comment>The section says to send `revision` and `generationToken` with the DELETE but never states how they are transmitted (JSON body, query parameters, or headers), and no curl example is given. Every other parameterized request on this page is a JSON body sent to a PATCH (e.g. `{"action":"generate","revision":0}`), so a reader will guess; many HTTP clients also strip DELETE bodies, which makes transport worth stating explicitly. Confirm against the API source and specify the transport, ideally with one curl example.</comment>
<file context>
@@ -111,6 +111,12 @@ The public page is `https://chat.recoupable.dev/s/{id}`.
+## Delete and cancel generation
+
+Delete only when explicitly instructed. Send `DELETE /api/sites/{id}` with the current `revision`. Include `generationToken` when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job.
+
+Deletion checks workspace access and revision, then returns `{ "deleted": true, "id": "..." }`. A stale revision returns 409; reload before retrying. Unpublish with `action: "unpublish"` when the draft should remain available.
</file context>
|
|
||
| Unpublish with `action: "unpublish"`, or `unpublish_site`. Agents should publish only when explicitly instructed. | ||
|
|
||
| ## Delete and cancel generation |
There was a problem hiding this comment.
P3: This new section introduces DELETE /api/sites/{id} as a public REST operation, but the "Endpoints and tools" table at the top of this same page still has no DELETE row (it lists GET /api/sites, POST /api/sites, GET /api/sites/{id}, the four PATCH actions, GET .../signups, and POST /api/sites/assets). Readers and LLMs that discover operations through the table won't find deletion. Add a row such as | \DELETE /api/sites/{id}` | `delete_site` | `{ "deleted": true, "id": "..." }` |` to keep the table in sync with the prose.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/source/api-reference/sites/overview.mdx, line 114:
<comment>This new section introduces `DELETE /api/sites/{id}` as a public REST operation, but the "Endpoints and tools" table at the top of this same page still has no DELETE row (it lists `GET /api/sites`, `POST /api/sites`, `GET /api/sites/{id}`, the four PATCH actions, `GET .../signups`, and `POST /api/sites/assets`). Readers and LLMs that discover operations through the table won't find deletion. Add a row such as `| \`DELETE /api/sites/{id}\` | \`delete_site\` | \`{ "deleted": true, "id": "..." }\` |` to keep the table in sync with the prose.</comment>
<file context>
@@ -111,6 +111,12 @@ The public page is `https://chat.recoupable.dev/s/{id}`.
Unpublish with `action: "unpublish"`, or `unpublish_site`. Agents should publish only when explicitly instructed.
+## Delete and cancel generation
+
+Delete only when explicitly instructed. Send `DELETE /api/sites/{id}` with the current `revision`. Include `generationToken` when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job.
</file context>
| method, route = key.split(' ', 1) | ||
| operation = json.loads((root / docs[key]).read_text())['paths'][route][method.lower()] | ||
| availability = operation.get('x-recoup-availability') | ||
| if availability not in ('pending', 'retired') or ('availability: ' + availability) not in operation.get('description', '').lower(): |
There was a problem hiding this comment.
P3: The gate depends on a prose marker, not just the structured field: it requires the literal substring availability: pending/availability: retired inside the operation description, so an otherwise correct x-recoup-availability value fails the refresh whenever the description formats the disclosure differently (e.g. **Status:** pending). It is also brittle on exact-path lookup: ['paths'][route] uses the trailing-slash-stripped route from the docs key, while social.json stores /api/spotify/artist/ with a trailing slash, so if that route ever became unmatched the script would raise an unhandled KeyError instead of the intended SystemExit. Consider gating on the structured field alone and normalizing the path lookup.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At scripts/refresh-contract-inventory.py, line 109:
<comment>The gate depends on a prose marker, not just the structured field: it requires the literal substring `availability: pending`/`availability: retired` inside the operation description, so an otherwise correct `x-recoup-availability` value fails the refresh whenever the description formats the disclosure differently (e.g. `**Status:** pending`). It is also brittle on exact-path lookup: `['paths'][route]` uses the trailing-slash-stripped route from the docs key, while `social.json` stores `/api/spotify/artist/` with a trailing slash, so if that route ever became unmatched the script would raise an unhandled `KeyError` instead of the intended `SystemExit`. Consider gating on the structured field alone and normalizing the path lookup.</comment>
<file context>
@@ -102,6 +102,12 @@ def main():
+ method, route = key.split(' ', 1)
+ operation = json.loads((root / docs[key]).read_text())['paths'][route][method.lower()]
+ availability = operation.get('x-recoup-availability')
+ if availability not in ('pending', 'retired') or ('availability: ' + availability) not in operation.get('description', '').lower():
+ raise SystemExit('Unmatched documentation needs explicit pending/retired availability: ' + key)
registrations = static_mcp_registrations(api)
</file context>
There was a problem hiding this comment.
2 existing issues remain and 1 new issue found across 12 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="content/docs/contracts/context-contract.json">
<violation number="1" location="content/docs/contracts/context-contract.json:1">
P2: Custom agent: **Enforce Clear Code Style and Maintainability Practices**
`context-contract.json` is 1,039 lines, exceeding Rule 1's under-100-line limit. Keep the generated contract data outside the rule's file-size scope or change the contract-fixture design so the committed artifact does not violate the limit; the navigation-specific generated-output exception does not cover this file.</violation>
</file>
Requires human review: Auto-approval blocked because this review re-detected 2 unresolved issues already reported by Cubic.
View guided diff | Turn on auto-fix | Re-trigger cubic
| @@ -0,0 +1,1039 @@ | |||
| { | |||
There was a problem hiding this comment.
P2: Custom agent: Enforce Clear Code Style and Maintainability Practices
context-contract.json is 1,039 lines, exceeding Rule 1's under-100-line limit. Keep the generated contract data outside the rule's file-size scope or change the contract-fixture design so the committed artifact does not violate the limit; the navigation-specific generated-output exception does not cover this file.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/contracts/context-contract.json, line 1:
<comment>`context-contract.json` is 1,039 lines, exceeding Rule 1's under-100-line limit. Keep the generated contract data outside the rule's file-size scope or change the contract-fixture design so the committed artifact does not violate the limit; the navigation-specific generated-output exception does not cover this file.</comment>
<file context>
@@ -0,0 +1,1039 @@
+{
+ "evidence": "Provider-free request syntax and static contract claims only. URLs are placeholders; no provider, payment or customer workflow is exercised.",
+ "sourceHash": "de67b0fecf1759ffad99f0f32eedd2e9b33e22c7feebcebfd961e4d26d21262e",
</file context>
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="content/docs/contracts/operation-inventory.json">
<violation number="1" location="content/docs/contracts/operation-inventory.json:2">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**
This inventory still pins the reviewed API SHA, although the PR description requires the actual API merge commit before release. Regenerate the inventory against the merged API checkout so `apiSourceCommit` matches `git rev-parse HEAD`.</violation>
</file>
Reply with feedback, questions, or to request a fix.
View guided diff | Turn on auto-fix | Re-trigger cubic
| @@ -1,5 +1,5 @@ | |||
| { | |||
| "apiSourceCommit": "2a882dd460ef6757af6d7b1b93bbc1fd8d0c6e86", | |||
| "apiSourceCommit": "0a590490c0e005045e4cbf399fe552dc41e6b9a3", | |||
There was a problem hiding this comment.
P1: Custom agent: Flag AI Slop and Fabricated Changes
This inventory still pins the reviewed API SHA, although the PR description requires the actual API merge commit before release. Regenerate the inventory against the merged API checkout so apiSourceCommit matches git rev-parse HEAD.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/contracts/operation-inventory.json, line 2:
<comment>This inventory still pins the reviewed API SHA, although the PR description requires the actual API merge commit before release. Regenerate the inventory against the merged API checkout so `apiSourceCommit` matches `git rev-parse HEAD`.</comment>
<file context>
@@ -1,5 +1,5 @@
{
- "apiSourceCommit": "a4315940ef61df1620ca169a6ba5a17e2d1b92f0",
+ "apiSourceCommit": "0a590490c0e005045e4cbf399fe552dc41e6b9a3",
"evidence": "Static source only; tool discovery and OAuth host verification remain separate. Conditional registration and scope filters mean this is not a promised catalog count.",
"operations": [
</file context>
The maintained docs contained stale social prices/defaults, catalog limits, task inputs, chat resume statuses, callback authentication and artist pin routes. Correct those contracts, CLI examples and Sites deletion/cancellation instructions against the current source. Expand Context from five to 26 request schemas plus delegated MCP mappings, labeled as a source-verified preview with explicit pilot restrictions. Keep provider-bound catalog planning as a tracked gap.
Mark ten unmatched REST paths as pending reconciliation rather than presenting them as supported or retiring their retained outcomes. The reviewed source baseline is 406 implemented method/path pairs, ten unmatched documented pairs and 59 static MCP registrations; this is not a promised live feature/tool count.
Add shared contract fixtures checked against API validators and helpers. The MCP table is generated from the canonical mapping metadata. The inventory also rejects unmatched REST references unless their public description and metadata explicitly mark pending or retired availability. The inventory pins the coordinated API PR's reviewed source commit; refresh it to the actual API merge commit before releasing this change, then refresh the Docs copy to the actual Marketing merge commit.
Validation: 437 Marketing tests, docs generation/checks, shared fixture parity, contract-inventory and publication-sync tests pass. Local Turbopack fails because this environment blocks its helper port; the Webpack fallback fails parsing the existing Eve dependency. Pushed for remote preview validation under Sidney's existing approval; merge remains blocked until the remote production build passes at the final head. No hosting, DNS, redirect or paid-provider operation is changed.
API companion: recoupable/api#1032
CLI companion: recoupable/cli#26
Refs recoupable/mono#318, recoupable/mono#326, recoupable/mono#327, recoupable/mono#329, recoupable/mono#330, recoupable/mono#331, recoupable/mono#332, recoupable/mono#333, recoupable/mono#335, recoupable/mono#336, recoupable/mono#346, recoupable/mono#355, recoupable/mono#356, recoupable/mono#360, recoupable/mono#361.
Review notes: generated OpenAPI contracts and snapshots remain generated data; no arbitrary 100-line cap is applied. Artist profile song_count comes from an independent exact catalog count and can exceed the returned songs, so its existing description is preserved.