pkup-gen

name	pkup-gen
description	Generate a PKUP report for given GitHub users. Use when the user asks to generate a PKUP report.

Generate a PKUP report directory containing all commits and their .diff files for a given period.

What is PKUP

PKUP (Podwyższone Koszty Uzyskania Przychodu) is a Polish tax concept. A PKUP report documents creative programming work done during a given month. It contains a list of commits/PRs as evidence of creative work, along with .diff files.

Step 0: Configure the report

Calculate the default PKUP period: from the 19th of the previous month (00:00:00) to the 18th of the current month (23:59:59).

Ask the user (AskUserQuestion) two questions at once:

Question 1 — provider and organization configuration:

Select the GitHub provider and organization configuration:

Options:

• "Default: github.com → kyma-project, github.tools.sap → kyma"
• "Custom configuration"

Question 2 — PKUP period:

Calculated PKUP period: DD.MM.YYYY – DD.MM.YYYY. Is this period correct?

Options:

• "Yes, use this period"
• "No, I will provide a custom period"

Ask both questions at once in a single AskUserQuestion call (two entries in the questions array).

If the user selects "No, I will provide a custom period" — ask for dates in DD.MM.YYYY - DD.MM.YYYY format before proceeding.

Step 1: Determine Git providers and organizations

Based on the answers from Step 0:

If "Default" was selected:

• Providers: github.com, github.tools.sap
• Organizations: kyma-project (github.com), kyma (github.tools.sap)

If "Custom configuration" was selected: Ask the user for details:

• List of providers (e.g. github.com, github.tools.sap, or another address)
• For each provider: list of organizations or repositories (format org:NAME or repo:ORG/REPO)

Remember the established values — they will be used in subsequent steps.

Step 2: Check gh CLI login status

Run gh auth status 2>&1 and check the result for each selected provider.

For each provider one of the following cases may occur:

Logged in successfully (✓ Logged in) — continue.

Not logged in or token invalid — display the instruction:

You are not logged in to <PROVIDER>. Run in the terminal:

  ! gh auth login -h <PROVIDER>

After logging in, return to this conversation.

Wait for the user to confirm they have logged in, then re-check gh auth status and make sure the login succeeded.

Only proceed to the next step once all selected providers have an active, valid session.

Step 3: Determine usernames

For each selected provider, determine the username:

• Read the logged-in user from the gh auth status output (the account <USERNAME> line).
• If it cannot be determined automatically — ask the user.

Also check for alternative author signatures: query the GitHub API for the user's full name:

gh api --hostname PROVIDER user --jq '{login, name}'

Remember both login and name — both will be used in the commit search.

Also determine:

• outputDir — the output directory, e.g. reports/FIRST_LAST (ask if unknown)

Step 4: Collect commits

For each user and each org/repo, query the GitHub Search API using both author:LOGIN and author-name:"Full Name" to catch commits made under either signature, then deduplicate:

gh api --method=GET search/commits \
  --hostname PROVIDER_HOSTNAME \
  -f q="author:USERNAME org:ORG committer-date:>=YYYY-MM-DD committer-date:<=YYYY-MM-DD" \
  -f per_page=100 \
  --paginate \
  | jq -s '[.[] | .items[] | {
      sha: .sha,
      repo: .repository.full_name,
      message: (.commit.message | split("\n")[0]),
      date: .commit.author.date
    }]
    | unique_by(.sha)
    | map(select(.date >= "SINCE_DATE" and .date <= "UNTIL_DATE"))
    | sort_by(.date)'

Repeat with author-name:"Full Name" and merge both result sets, deduplicating by .sha.

For a repo instead of an org: use repo:ORG/REPO instead of org:ORG.

For github.com use --hostname github.com (or omit it, as it is the default host). For github.tools.sap use --hostname github.tools.sap.

Important: The GitHub Search API does not filter dates server-side — always filter client-side (select(.date >= ...)). Use unique_by(.sha) to avoid duplicates from different branches.

Step 5: Download .diff files

For every collected commit (no filtering at this stage), download the diff and save it to outputDir:

curl -sf \
  -H "Authorization: token $(gh auth token --hostname PROVIDER_HOSTNAME)" \
  -H "Accept: application/vnd.github.v3.diff" \
  "https://API_BASE/repos/ORG/REPO/commits/SHA" \
  > "outputDir/ORG_REPO_SHA8.diff"

For github.com use https://api.github.com/repos/.... For github.tools.sap use https://github.tools.sap/api/v3/repos/....

File name format: {org}_{repo}_{first_8_chars_of_sha}.diff

Step 6: Done — generate report.txt and suggest next step

Generate a minimal report.txt file in outputDir with the period and approval date filled in:

cat > "outputDir/report.txt" <<EOF
period:
DD.MM.YYYY - DD.MM.YYYY

approvalDate:
DD.MM.YYYY

result:

EOF

Where:

• DD.MM.YYYY - DD.MM.YYYY is the PKUP period established in Step 0
• approvalDate is the day after the period end date (e.g. period ends 18.01.2026 → approvalDate is 19.01.2026)

Print a summary:

Gotowe! Katalog outputDir zawiera:
- N plików .diff
- report.txt z wypełnionym period: i approvalDate:

Then suggest the next step:

Następny krok: użyj /pkup-enchant, aby przefiltrować pracę twórczą, pogrupować commity i wygenerować opisy do raportu PKUP.

Step 7: Thank the user and ask about starring the repo

Print the following message:

Dzięki za skorzystanie z pkup-gen! 🙌
Jeśli narzędzie Ci pomogło, rozważ oznaczenie gwiazdką na GitHubie —
to najlepszy sposób, żeby docenić projekt i pomóc innym go odkryć.

  ⭐ https://github.com/pPrecel/pkup-gen

Then ask (AskUserQuestion):

Czy chcesz, żebym oznaczył gwiazdką repozytorium pPrecel/pkup-gen za Ciebie?

Options:

• "Tak, oznacz gwiazdką"
• "Nie, dziękuję"

If the user selects "Tak, oznacz gwiazdką", run:

gh api user/starred/pPrecel/pkup-gen -X PUT

Technical notes

• gh api --paginate handles pagination automatically
• GitHub Search API has a limit of 1000 results per query
• Rate limit: 5000 req/h for PAT tokens
• The output outputDir contains .diff files and a report.txt with period: and approvalDate: pre-filled — ready for /pkup-enchant to write the result: section