feat: superdoc sdk

.github/workflows/ci-docs.yml

@@ -4,6 +4,11 @@ on:
   pull_request:
     paths:
       - 'apps/docs/**'
+      - 'packages/document-api/src/contract/**'
+      - 'packages/document-api/scripts/**'
+      - 'scripts/generate-all.mjs'
+      - 'package.json'
+      - 'pnpm-lock.yaml'
   workflow_dispatch:
 
 jobs:
@@ -27,6 +32,9 @@ jobs:
       - name: Install Dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Generate all artifacts
+        run: pnpm run generate:all
+
       - name: Validate Docs
         run: pnpm --filter @superdoc/docs validate
 

.github/workflows/ci-document-api.yml

@@ -32,5 +32,11 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Generate contract outputs
+        run: pnpm run docapi:sync
+
+      - name: Check overview.mdx freshness
+        run: git diff --exit-code apps/docs/document-api/overview.mdx
+
       - name: Check contract parity and generated outputs
         run: pnpm run docapi:check

.github/workflows/ci-sdk.yml

@@ -0,0 +1,52 @@
+name: CI SDK
+
+permissions:
+  contents: read
+
+on:
+  pull_request:
+    paths:
+      - 'packages/document-api/src/contract/**'
+      - 'packages/document-api/scripts/**'
+      - 'apps/cli/**'
+      - 'packages/sdk/**'
+      - 'scripts/generate-all.mjs'
+      - 'package.json'
+      - 'pnpm-lock.yaml'
+      - '.github/workflows/ci-sdk.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: ci-sdk-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+
+      - uses: oven-sh/setup-bun@v2
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Generate all artifacts
+        run: pnpm run generate:all
+
+      - name: Validate SDK
+        run: node packages/sdk/scripts/sdk-validate.mjs
+
+      - name: Build Node SDK
+        run: pnpm --prefix packages/sdk/langs/node run build

.github/workflows/release-sdk.yml

@@ -0,0 +1,124 @@
+name: 📦 Release SDK
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (e.g. 1.0.0-alpha.7). Leave empty to release the current version."
+        required: false
+        type: string
+      dry-run:
+        description: "Dry run — build and validate without publishing"
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+  id-token: write # PyPI trusted publishing (OIDC)
+
+concurrency:
+  group: release-sdk
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-24.04
+    environment: ${{ inputs.dry-run && '' || 'pypi' }}
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+          registry-url: "https://registry.npmjs.org"
+
+      - uses: oven-sh/setup-bun@v2
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Install Python build tools
+        run: pip install build
+
+      # ---------------------------------------------------------------
+      # Show current version (visible in the Actions run summary)
+      # ---------------------------------------------------------------
+      - name: Show current version
+        run: |
+          CURRENT=$(node -p "require('./packages/sdk/package.json').version")
+          echo "### SDK Release" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| | Version |" >> $GITHUB_STEP_SUMMARY
+          echo "|---|---|" >> $GITHUB_STEP_SUMMARY
+          echo "| **Current (in repo)** | \`${CURRENT}\` |" >> $GITHUB_STEP_SUMMARY
+          if [ -n "${{ inputs.version }}" ]; then
+            echo "| **Releasing** | \`${{ inputs.version }}\` |" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "| **Releasing** | \`${CURRENT}\` (unchanged) |" >> $GITHUB_STEP_SUMMARY
+          fi
+          echo "| **Dry run** | \`${{ inputs.dry-run }}\` |" >> $GITHUB_STEP_SUMMARY
+
+      # ---------------------------------------------------------------
+      # Set version (if provided)
+      # ---------------------------------------------------------------
+      - name: Set version
+        if: inputs.version != ''
+        run: node packages/sdk/scripts/sync-sdk-version.mjs --set "${{ inputs.version }}"
+
+      # ---------------------------------------------------------------
+      # Generate + validate
+      # ---------------------------------------------------------------
+      - name: Generate all artifacts
+        run: pnpm run generate:all
+
+      - name: Validate SDK
+        run: node packages/sdk/scripts/sdk-validate.mjs
+
+      # ---------------------------------------------------------------
+      # Node SDK
+      # ---------------------------------------------------------------
+      - name: Build Node SDK
+        run: pnpm --prefix packages/sdk/langs/node run build
+
+      - name: Publish Node SDK
+        if: ${{ !inputs.dry-run }}
+        run: pnpm --prefix packages/sdk/langs/node publish --access public --tag latest --no-git-checks
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish Node SDK (dry run)
+        if: ${{ inputs.dry-run }}
+        run: pnpm --prefix packages/sdk/langs/node publish --access public --tag latest --no-git-checks --dry-run
+
+      # ---------------------------------------------------------------
+      # Python SDK
+      # ---------------------------------------------------------------
+      - name: Prepare Python SDK tools
+        run: |
+          rm -rf packages/sdk/langs/python/superdoc/tools
+          cp -r packages/sdk/tools packages/sdk/langs/python/superdoc/tools
+          rm -f packages/sdk/langs/python/superdoc/tools/__init__.py
+
+      - name: Build Python SDK
+        run: python -m build
+        working-directory: packages/sdk/langs/python
+
+      - name: Publish Python SDK to PyPI
+        if: ${{ !inputs.dry-run }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: packages/sdk/langs/python/dist/
+
+      - name: Publish Python SDK (dry run)
+        if: ${{ inputs.dry-run }}
+        run: |
+          echo "Would publish the following Python packages:"
+          ls -la packages/sdk/langs/python/dist/

.gitignore

@@ -78,3 +78,16 @@ devtools/visual-testing/pnpm-lock.yaml
 
 .bun-cache/
 
+# Python
+__pycache__/
+*.pyc
+*.pyo
+
+# Generated artifacts — run `pnpm run generate:all` to produce
+packages/document-api/generated/
+apps/cli/generated/
+packages/sdk/langs/node/src/generated/
+packages/sdk/langs/python/superdoc/generated/
+packages/sdk/tools/*.json
+# Note: apps/docs/document-api/reference/ stays committed because Mintlify
+# deploys directly from git with no pre-build hook support.

CLAUDE.md

@@ -109,3 +109,21 @@ Many packages use `.js` files with JSDoc `@typedef` for type definitions (e.g.,
 - `pnpm build` - Build all packages
 - `pnpm test` - Run tests
 - `pnpm dev` - Start dev server (from examples/)
+- `pnpm run generate:all` - Generate all derived artifacts (schemas, SDK clients, tool catalogs, reference docs)
+
+## Generated Artifacts
+
+These directories are produced by `pnpm run generate:all`:
+
+| Directory | In git? | What it contains |
+|-----------|---------|-----------------|
+| `packages/document-api/generated/` | No (gitignored) | Agent tool schemas, JSON schemas, manifest |
+| `apps/cli/generated/` | No (gitignored) | SDK contract JSON exported from CLI metadata |
+| `packages/sdk/langs/node/src/generated/` | No (gitignored) | Node SDK generated client code |
+| `packages/sdk/langs/python/superdoc/generated/` | No (gitignored) | Python SDK generated client code |
+| `packages/sdk/tools/*.json` | No (gitignored) | Tool catalogs for all providers (catalog.json, tools.openai.json, etc.) |
+| `apps/docs/document-api/reference/` | Yes (Mintlify deploys from git) | Reference doc pages generated from contract |
+
+After a fresh clone, run `pnpm run generate:all` before working on SDK, CLI, or doc-api code.
+
+Note: `packages/sdk/tools/__init__.py` is a manual file (Python package marker) and stays committed.

apps/cli/package.json

@@ -44,13 +44,6 @@
     "typescript": "catalog:"
   },
   "module": "src/index.ts",
-  "optionalDependencies": {
-    "@superdoc-dev/cli-darwin-arm64": "workspace:*",
-    "@superdoc-dev/cli-darwin-x64": "workspace:*",
-    "@superdoc-dev/cli-linux-x64": "workspace:*",
-    "@superdoc-dev/cli-linux-arm64": "workspace:*",
-    "@superdoc-dev/cli-windows-x64": "workspace:*"
-  },
   "publishConfig": {
     "access": "public"
   }