feat(docs): automate block reference generation and sync (#40)

* feat(docs): automate block reference generation and sync

- add multi-target block reference generator with --check mode
- generate and align docs/skill reference markdown including overview
- add CI check for generated references
- add workflow to sync generated references on main push

Co-authored-by: chatgpt-codex-connector[bot] <199175422+chatgpt-codex-connector[bot]@users.noreply.github.com>

* fix

* Update packages/skill/scripts/build-blocks.ts

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* fix

* Revert "Update packages/skill/scripts/build-blocks.ts"

This reverts commit 6331ebf.

---------

Co-authored-by: chatgpt-codex-connector[bot] <199175422+chatgpt-codex-connector[bot]@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

.github/workflows/ci.yml

@@ -23,3 +23,6 @@ jobs:
 
       - name: Typecheck
         run: bun typecheck
+
+      - name: Check generated references
+        run: bun run ref:check

.github/workflows/ref-sync.yml

@@ -0,0 +1,48 @@
+name: Sync Generated References
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - packages/hikkaku/src/blocks/**
+      - packages/skill/scripts/build-blocks.ts
+      - packages/skill/package.json
+      - package.json
+      - bun.lock
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  sync:
+    if: github.actor != 'github-actions[bot]'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Generate references
+        run: bun run ref:build
+
+      - name: Commit generated references
+        run: |
+          if git diff --quiet; then
+            echo "No generated changes"
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          git add docs/reference/blocks packages/skill/hikkaku/rules/blocks
+          git commit -m "chore: sync generated block references"
+          git push

AGENTS.md

@@ -37,3 +37,8 @@
     ```
 * You can use git command and gh command to commit, push and create PR.
 * Use "Squash and merge" to merge the PR on GitHub.
+
+* commands you have to use before commiting:
+  * `bun fmt`: apply formatting
+  * `bun typecheck`: run type checking
+  * `bun ref:build`: update the docs

docs/reference/blocks/control.md

@@ -3,6 +3,9 @@ title: Blocks - Control
 impact: HIGH
 ---
 
+<!-- AUTO-GENERATED FILE. Do not edit manually.
+Edit packages/hikkaku/src/blocks and packages/skill/scripts/build-blocks.ts instead. -->
+
 # Control Blocks
 
 ## repeat(times, handler)
@@ -166,16 +169,15 @@ import { ifElse } from 'hikkaku/blocks'
 ifElse(true, () => {}, () => {})
 ```
 
-## match(...branches)
+## match(branches)
 
 Builds chained if / else-if / else branching from condition-handler pairs.
 
-Input: `...branches`.
+Input: `branches`.
 
 Output: Scratch statement block definition that is appended to the current script stack.
 
-* `branches: Array<[condition: PrimitiveSource<boolean>, handler: () => void]>` - sequence of condition/handler pairs evaluated in order
-* Optional trailing `defaultHandler: () => void` - handler called when no branch condition matches
+* `branches: Input value used by this block`
 
 Example:
 ```ts

docs/reference/blocks/data.md

@@ -3,6 +3,9 @@ title: Blocks - Data
 impact: HIGH
 ---
 
+<!-- AUTO-GENERATED FILE. Do not edit manually.
+Edit packages/hikkaku/src/blocks and packages/skill/scripts/build-blocks.ts instead. -->
+
 # Variables & Lists
 
 ## getVariable(variable)

docs/reference/blocks/events.md

@@ -3,6 +3,9 @@ title: Blocks - Events
 impact: HIGH
 ---
 
+<!-- AUTO-GENERATED FILE. Do not edit manually.
+Edit packages/hikkaku/src/blocks and packages/skill/scripts/build-blocks.ts instead. -->
+
 # Events
 
 ## whenFlagClicked(stack)

docs/reference/blocks/looks.md

@@ -3,6 +3,9 @@ title: Blocks - Looks
 impact: HIGH
 ---
 
+<!-- AUTO-GENERATED FILE. Do not edit manually.
+Edit packages/hikkaku/src/blocks and packages/skill/scripts/build-blocks.ts instead. -->
+
 # Appearance
 
 ## say(message)

docs/reference/blocks/motion.md

@@ -3,6 +3,9 @@ title: Blocks - Motion
 impact: HIGH
 ---
 
+<!-- AUTO-GENERATED FILE. Do not edit manually.
+Edit packages/hikkaku/src/blocks and packages/skill/scripts/build-blocks.ts instead. -->
+
 # Motion
 
 ## moveSteps(steps)

docs/reference/blocks/operator.md

@@ -3,6 +3,9 @@ title: Blocks - Operators
 impact: HIGH
 ---
 
+<!-- AUTO-GENERATED FILE. Do not edit manually.
+Edit packages/hikkaku/src/blocks and packages/skill/scripts/build-blocks.ts instead. -->
+
 # Operators
 
 ## add(a, b)
@@ -20,7 +23,7 @@ Example:
 ```ts
 import { add } from 'hikkaku/blocks'
 
-add([[true, () => {}]] as any, undefined as any)
+add(1, 2)
 ```
 
 ## subtract(a, b)
@@ -38,7 +41,7 @@ Example:
 ```ts
 import { subtract } from 'hikkaku/blocks'
 
-subtract([[true, () => {}]] as any, undefined as any)
+subtract(5, 3)
 ```
 
 ## multiply(a, b)
@@ -56,7 +59,7 @@ Example:
 ```ts
 import { multiply } from 'hikkaku/blocks'
 
-multiply([[true, () => {}]] as any, undefined as any)
+multiply(3, 4)
 ```
 
 ## divide(a, b)
@@ -74,7 +77,7 @@ Example:
 ```ts
 import { divide } from 'hikkaku/blocks'
 
-divide([[true, () => {}]] as any, undefined as any)
+divide(10, 2)
 ```
 
 ## lt(a, b)
@@ -92,7 +95,7 @@ Example:
 ```ts
 import { lt } from 'hikkaku/blocks'
 
-lt([[true, () => {}]] as any, undefined as any)
+lt(1, 2)
 ```
 
 ## equals(a, b)
@@ -110,7 +113,7 @@ Example:
 ```ts
 import { equals } from 'hikkaku/blocks'
 
-equals([[true, () => {}]] as any, undefined as any)
+equals(5, 5)
 ```
 
 ## gt(a, b)
@@ -128,7 +131,7 @@ Example:
 ```ts
 import { gt } from 'hikkaku/blocks'
 
-gt([[true, () => {}]] as any, undefined as any)
+gt(10, 5)
 ```
 
 ## and(a, b)
@@ -146,7 +149,7 @@ Example:
 ```ts
 import { and } from 'hikkaku/blocks'
 
-and([[true, () => {}]] as any, undefined as any)
+and(true, false)
 ```
 
 ## or(a, b)
@@ -164,7 +167,7 @@ Example:
 ```ts
 import { or } from 'hikkaku/blocks'
 
-or([[true, () => {}]] as any, undefined as any)
+or(true, false)
 ```
 
 ## not(operand)
@@ -181,7 +184,7 @@ Example:
 ```ts
 import { not } from 'hikkaku/blocks'
 
-not(undefined as any)
+not(false)
 ```
 
 ## random(from, to)
@@ -217,7 +220,7 @@ Example:
 ```ts
 import { join } from 'hikkaku/blocks'
 
-join([[true, () => {}]] as any, undefined as any)
+join('Hello', 'World')
 ```
 
 ## letterOf(letter, text)
@@ -288,7 +291,7 @@ Example:
 ```ts
 import { mod } from 'hikkaku/blocks'
 
-mod([[true, () => {}]] as any, undefined as any)
+mod(10, 3)
 ```
 
 ## round(value)

docs/reference/blocks/overview.md

@@ -3,6 +3,9 @@ title: Blocks Overview
 impact: HIGH
 ---
 
+<!-- AUTO-GENERATED FILE. Do not edit manually.
+Edit packages/hikkaku/src/blocks and packages/skill/scripts/build-blocks.ts instead. -->
+
 # List of Available Blocks
 
 This document explains the function names, arguments, and behavior of exported helpers.
@@ -28,7 +31,7 @@ import { add, gotoXY } from 'hikkaku/blocks'
 - [Events](/reference/blocks/events)
 - [Looks](/reference/blocks/looks)
 - [Motion](/reference/blocks/motion)
-- [Operators](/reference/blocks/operator)
+- [Operator](/reference/blocks/operator)
 - [Procedures](/reference/blocks/procedures)
 - [Sensing](/reference/blocks/sensing)
 - [Sound](/reference/blocks/sound)