Skip to content

Add Cyclops CS Backend API reference documentation #2001

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
r33drichards wants to merge 2 commits into
base: main
Choose a base branch
from
+2,920 −1
Open

Add Cyclops CS Backend API reference documentation #2001

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fe40e6d
docs(cyclops-cs): generate backend HTTP API reference from vendored O…
claude Jun 23, 2026
ebfb473
docs(cyclops-cs): address review — path-param required + sync robustness
claude Jun 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/workflows/ci-check-docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,13 @@ on:
- "libs/typescript/agent/src/**"
# Cua-Bot
- "libs/cuabot/src/**"
# Cyclops CS Backend (vendored OpenAPI spec from trycua/cloud)
- "scripts/docs-generators/specs/cyclops-cs.swagger.json"
# Documentation files themselves
- "docs/content/docs/cua-driver/reference/**"
- "docs/content/docs/cua/reference/**"
- "docs/content/docs/cuabot/reference/**"
- "docs/content/docs/reference/cyclops-cs/**"
# Generator scripts
- "scripts/docs-generators/**"

Expand Down Expand Up @@ -89,6 +92,10 @@ jobs:
if echo "$CHANGED_FILES" | grep -q "^libs/cuabot/src/"; then
GENERATORS="$GENERATORS cuabot"
fi
# Cyclops CS: vendored spec, generator, or its output page changed
if echo "$CHANGED_FILES" | grep -q "^scripts/docs-generators/specs/cyclops-cs\.swagger\.json\|^scripts/docs-generators/cyclops-cs\.ts\|^docs/content/docs/reference/cyclops-cs/"; then
GENERATORS="$GENERATORS cyclops-cs"
fi

# Individual generator script changes — only trigger their own generator
if echo "$CHANGED_FILES" | grep -q "^scripts/docs-generators/cua-driver\.ts"; then
Expand Down
70 changes: 70 additions & 0 deletions .github/workflows/sync-cyclops-cs-spec.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
name: "Sync: Cyclops CS spec"

# Refreshes the vendored Cyclops CS backend OpenAPI spec from its source of
# truth in trycua/cloud and regenerates the reference MDX. Opens a PR when the
# vendored copy or generated page drifts.
#
# Triggers:
# - repository_dispatch: trycua/cloud pings this when swagger.json changes
# (see trycua/cloud .github/workflows/notify-cyclops-cs-spec-change.yml)
# - schedule: daily self-heal in case a ping is missed
# - workflow_dispatch: manual run
#
# Required secret:
# CLOUD_REPO_TOKEN — a PAT or GitHub App token with read access to the
# private trycua/cloud repo contents. The built-in GITHUB_TOKEN cannot read
# another private repo, so this must be provisioned in repo/org settings.

on:
repository_dispatch:
types: [cyclops-cs-spec-changed]
schedule:
- cron: "0 7 * * *"
workflow_dispatch:

permissions:
contents: write
pull-requests: write

jobs:
sync:
name: Sync vendored spec and regenerate docs
runs-on: ubuntu-latest
steps:
- name: Checkout cua
uses: actions/checkout@v4

- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: "20"

- name: Install pnpm
uses: pnpm/action-setup@v4

- name: Install Node dependencies
run: pnpm install
working-directory: docs

- name: Sync spec and regenerate
env:
CYCLOPS_CS_SPEC_SOURCE: "https://api.github.com/repos/trycua/cloud/contents/cyclops-cs/backend/docs/swagger.json?ref=main"
GITHUB_TOKEN: ${{ secrets.CLOUD_REPO_TOKEN }}
run: npx tsx scripts/docs-generators/sync-cyclops-cs-spec.ts

- name: Open PR on drift
uses: peter-evans/create-pull-request@v6
Comment on lines +35 to +56

@coderabbitai coderabbitai Bot Jun 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Pin all GitHub Actions to commit SHAs and disable checkout credential persistence.

This workflow currently uses mutable action tags (Lines 35, 38, 43, 56) and default checkout credential persistence (Line 35), which weakens CI supply-chain security.

🧰 Tools
🪛 zizmor (1.26.1)

[error] 35-35: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

[error] 38-38: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

[error] 43-43: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

[error] 56-56: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/sync-cyclops-cs-spec.yml around lines 35 - 56, Pin all
GitHub Actions to specific commit SHAs instead of mutable version tags to
strengthen supply-chain security. Replace the version tags (`@v4`, `@v6`) in the
uses clauses for actions/checkout, actions/setup-node, pnpm/action-setup, and
peter-evans/create-pull-request with their corresponding commit SHA hashes.
Additionally, add persist-credentials: false to the actions/checkout action to
disable default credential persistence, which reduces the risk of credential
leakage in the workflow.

Source: Linters/SAST tools

with:
branch: docs/cyclops-cs-spec-sync
title: "docs(cyclops-cs): sync backend API reference from trycua/cloud"
commit-message: "docs(cyclops-cs): sync backend API reference from trycua/cloud"
body: |
Automated sync of the Cyclops CS backend OpenAPI spec from
`trycua/cloud` (`cyclops-cs/backend/docs/swagger.json`) and the
regenerated reference page.

Generated by `.github/workflows/sync-cyclops-cs-spec.yml`. Do not
edit the vendored spec or `http-api.mdx` by hand.
add-paths: |
scripts/docs-generators/specs/cyclops-cs.swagger.json
docs/content/docs/reference/cyclops-cs/http-api.mdx
Loading
Loading