From d8d091d9e67149ab84bc16d4ac5c9a653e6d4487 Mon Sep 17 00:00:00 2001 From: Adam Friedmann Date: Tue, 10 Feb 2026 17:18:58 +0200 Subject: [PATCH 1/3] adding docs drafter workflow --- .github/workflows/claude-docs-drafter.yml | 144 ++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 .github/workflows/claude-docs-drafter.yml diff --git a/.github/workflows/claude-docs-drafter.yml b/.github/workflows/claude-docs-drafter.yml new file mode 100644 index 0000000..6e06eeb --- /dev/null +++ b/.github/workflows/claude-docs-drafter.yml @@ -0,0 +1,144 @@ +name: Claude Docs Drafter + +on: + pull_request: + types: [opened, synchronize] + paths: + - "src/modules/**" + - "src/client.types.ts" + - "src/types.ts" + +jobs: + claude-docs-draft: + if: | + github.actor != 'github-actions[bot]' && + github.actor != 'claude-code[bot]' && + github.actor != 'claude[bot]' && + github.actor != 'claude' + + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + issues: write + id-token: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Run Claude Docs Drafter + id: claude-docs-drafter + uses: anthropics/claude-code-action@beta + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + model: "claude-sonnet-4-20250514" + use_sticky_comment: true + + direct_prompt: | + You are a documentation drafter for the Base44 JavaScript SDK. + + ## Your task + + 1. Read the documentation skill file at `.claude/skills/sdk-docs-writing/SKILL.md`. Follow its rules exactly. + 2. Look at the changes in this PR (the diff of files under `src/modules/`, `src/client.types.ts`, and `src/types.ts`). + 3. Identify any **new or modified public APIs** (interfaces, types, methods, properties) that are missing JSDoc or have incomplete JSDoc according to the skill's rules. + 4. Check the existing `.types.ts` files in `src/modules/` and the generated docs in `docs/content/` to understand the established patterns and voice. Your suggestions must match these patterns. + + ## How to report + + Post a **single PR comment** with the following structure: + + ### 📝 Documentation Draft + + **Summary** + A brief overview of what new or changed public APIs were found in this PR and whether they need documentation. If everything is already documented, say so. + + **Draft JSDoc** + For each public API that is missing or has incomplete JSDoc, provide the complete suggested JSDoc block. Group suggestions by file. Use this format: + + --- + + #### `src/modules/example.types.ts` + + **`ExampleModule.myMethod`** — *New method, missing JSDoc entirely.* + + ```typescript + /** + * Does something useful. + * + * @param id - The unique identifier. Defaults to `undefined`. + * @returns Promise resolving to the result object. + * + * @example + * ```typescript + * // Basic usage + * const result = await base44.example.myMethod('abc'); + * ``` + * + * @example + * ```typescript + * // With error handling + * try { + * const result = await base44.example.myMethod('abc'); + * } catch (error) { + * console.error('Failed:', error); + * } + * ``` + */ + myMethod(id: string): Promise; + ``` + + --- + + Include the original method/property signature at the bottom of each code block so the developer can see exactly where the JSDoc should be placed. + + **Checklist** + End with this checklist for the developer and tech writer to verify: + - [ ] JSDoc completeness (description, `@param`, `@returns`, `@example`) + - [ ] `@internal` on implementation-only exports + - [ ] New types added to `types-to-expose.json` if needed + - [ ] Helper types added to `appended-articles.json` if needed + - [ ] Examples use `base44.` call path and are valid TypeScript + + ## Rules + - Do NOT commit any changes to the PR branch. Only comment. + - Do NOT modify any files. You are read-only. + - Be specific and actionable. Don't give vague advice. + - For each suggestion, briefly state why it's needed (new API, missing `@example`, incomplete `@param` tags, etc.). + - Match the tone and style of existing JSDoc in the codebase. + - If a public API already has complete, correct JSDoc, skip it — don't suggest changes for the sake of it. + + - name: Add docs-draft label + if: success() + uses: actions/github-script@v7 + with: + script: | + // Create the label if it doesn't exist yet + try { + await github.rest.issues.getLabel({ + owner: context.repo.owner, + repo: context.repo.repo, + name: 'docs-draft' + }); + } catch (e) { + if (e.status === 404) { + await github.rest.issues.createLabel({ + owner: context.repo.owner, + repo: context.repo.repo, + name: 'docs-draft', + color: '1D76DB', + description: 'PR has auto-drafted documentation suggestions' + }); + } + } + + // Add the label to the PR + await github.rest.issues.addLabels({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + labels: ['docs-draft'] + }); From 98b5ee2901fd24997b3e247627ee47f192b46c9c Mon Sep 17 00:00:00 2001 From: Adam Friedmann Date: Wed, 11 Feb 2026 11:09:08 +0200 Subject: [PATCH 2/3] fixes from review + conditional logic for labeling --- .github/workflows/claude-docs-drafter.yml | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/.github/workflows/claude-docs-drafter.yml b/.github/workflows/claude-docs-drafter.yml index 6e06eeb..eb957a9 100644 --- a/.github/workflows/claude-docs-drafter.yml +++ b/.github/workflows/claude-docs-drafter.yml @@ -27,17 +27,20 @@ jobs: - name: Checkout repository uses: actions/checkout@v4 with: - fetch-depth: 0 + fetch-depth: 2 - name: Run Claude Docs Drafter + timeout-minutes: 10 id: claude-docs-drafter - uses: anthropics/claude-code-action@beta + uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} - model: "claude-sonnet-4-20250514" use_sticky_comment: true + claude_args: | + --model claude-sonnet-4-20250514 + --json-schema '{"type":"object","properties":{"needs_docs":{"type":"boolean","description":"true if the PR has public APIs that need new or improved JSDoc"}},"required":["needs_docs"]}' - direct_prompt: | + prompt: | You are a documentation drafter for the Base44 JavaScript SDK. ## Your task @@ -103,6 +106,12 @@ jobs: - [ ] Helper types added to `appended-articles.json` if needed - [ ] Examples use `base44.` call path and are valid TypeScript + ## Structured output + + You MUST return a structured output with the field `needs_docs`. + - Set `needs_docs` to `true` if you found any public APIs that need new or improved JSDoc. + - Set `needs_docs` to `false` if every public API already has complete, correct JSDoc and you have no suggestions. + ## Rules - Do NOT commit any changes to the PR branch. Only comment. - Do NOT modify any files. You are read-only. @@ -112,7 +121,7 @@ jobs: - If a public API already has complete, correct JSDoc, skip it — don't suggest changes for the sake of it. - name: Add docs-draft label - if: success() + if: success() && fromJSON(steps.claude-docs-drafter.outputs.structured_output).needs_docs == true uses: actions/github-script@v7 with: script: | From 64bd7dce7538a646a18a10e91c42f333fb9099a3 Mon Sep 17 00:00:00 2001 From: adamfri Date: Sun, 15 Feb 2026 11:25:52 +0200 Subject: [PATCH 3/3] Update fetch-depth in CLAUDE Docs Drafter workflow Change fetch-depth to 0 for full history checkout. --- .github/workflows/claude-docs-drafter.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/claude-docs-drafter.yml b/.github/workflows/claude-docs-drafter.yml index eb957a9..419fb52 100644 --- a/.github/workflows/claude-docs-drafter.yml +++ b/.github/workflows/claude-docs-drafter.yml @@ -27,7 +27,7 @@ jobs: - name: Checkout repository uses: actions/checkout@v4 with: - fetch-depth: 2 + fetch-depth: 0 - name: Run Claude Docs Drafter timeout-minutes: 10