@chrismo/superkit 1.0.0

package/docs/tutorials/bash_to_sup.md

@@ -0,0 +1,123 @@
+---
+title: "Getting Bash Text into SuperDB"
+name: bash-to-sup
+description: "Getting raw text safely from Bash into SuperDB without manual escaping."
+layout: default
+nav_order: 1
+parent: Tutorials
+superdb_version: "0.3.0"
+last_updated: "2026-02-17"
+---
+
+# Getting Bash Text into SuperDB
+
+The companion to [sup_to_bash](sup_to_bash.md), this covers the reverse: safely
+getting raw text from Bash into SuperDB.
+
+## The Problem
+
+When building `.sup` records from Bash, you need to escape text before embedding
+it in SUP strings. A common approach is manual escaping with sed:
+
+```bash
+# Manual escaping — fragile and error-prone
+escape_for_sup() {
+  echo "$1" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | sed "s/'/\'/g"
+}
+
+text='She said "hello" and it'\''s a back\slash'
+record="{body:\"$(escape_for_sup "$text")\"}"
+echo "$record" >> data.sup
+```
+
+This works but is brittle — each special character needs its own sed pass, and
+it's easy to miss edge cases or get the escaping order wrong.
+
+## Let Super Handle It
+
+Instead of escaping text yourself, pipe it through `super` and let the
+serializer do the work. The `-i line` flag reads each line of stdin as a string
+value.
+
+### Single-Line Text
+
+```bash
+text='She said "hello" and it'\''s a back\slash'
+echo "$text" | super -s -i line -c "values this" -
+# => "She said \"hello\" and it's a back\\slash"
+```
+
+Super's SUP output automatically escapes backslashes and double quotes. No sed
+needed.
+
+### Multiline Text to a Single String
+
+With `-i line`, each input line becomes a separate string value. To collapse
+multiline text into a single string with embedded `\n`:
+
+```bash
+printf 'line one\nline two\nline three' |
+  super -s -i line -c 'aggregate s:=collect(this) | values join(s, "\n")' -
+# => "line one\nline two\nline three"
+```
+
+The pattern: `collect()` gathers all lines into an array, then `join()` merges
+them with literal newline characters.
+
+### Building Records with Raw Text
+
+Combine `-i line` with record construction to safely embed text into `.sup`
+records:
+
+```bash
+# Single-line field
+msg='User said "goodbye" & left'
+body=$(echo "$msg" | super -f line -i line -c "values this" -)
+echo "{type:'message',body:'$body'}" | super -s -c "values this" -
+
+# Or build the whole record in one shot
+echo "$msg" | super -s -i line -c "values {type:'message', body: this}" -
+```
+
+The second form is cleaner — super constructs the full record, so the text never
+passes through Bash string interpolation at all.
+
+### Multiline Record Fields
+
+```bash
+notes="first line
+second line
+third line"
+
+echo "$notes" |
+  super -s -i line -c '
+    aggregate s:=collect(this)
+    | values {type: "note", body: join(s, "\n")}
+  ' -
+# => {type:"note",body:"first line\nsecond line\nthird line"}
+```
+
+## Appending to .sup Files
+
+A common pattern in scripts that maintain `.sup` files:
+
+```bash
+append_record() {
+  local file="$1"
+  local msg="$2"
+  echo "$msg" |
+    super -s -i line -c "values {ts: now(), body: this}" - >> "$file"
+}
+
+append_record "log.sup" 'User clicked "submit" at /path?q=1&r=2'
+```
+
+## Why This Is Better
+
+| Approach | Handles `"` | Handles `\` | Handles `'` | Handles newlines | Handles unicode |
+|---|---|---|---|---|---|
+| Manual sed chains | One sed per char | Easy to mis-order | Another sed | Yet another sed | Hope for the best |
+| `super -i line` | Yes | Yes | Yes | With collect/join | Yes |
+
+One pipeline replaces an entire family of escape functions. Super knows its own
+serialization format — let it do the work.

package/docs/tutorials/chess-tiebreaks.md

@@ -0,0 +1,233 @@
+---
+title: "Chess Tiebreaks"
+name: chess-tiebreaks
+description: "End-to-end tutorial parsing PGN chess data to find tie-break games."
+layout: default
+nav_order: 2
+parent: Tutorials
+superdb_version: "0.3.0"
+last_updated: "2026-02-15"
+---
+
+# Chess Tiebreaks
+
+SuperDB isn't limited to JSON — it can ingest and transform plain text just as
+easily. This tutorial demonstrates parsing raw text input using `grok` patterns,
+reshaping records, and aggregating results to answer a real question.
+
+PGN (Portable Game Notation) is a plain text format for recording chess games.
+Each game has metadata in bracketed lines like `[White "LastName, FirstName"]`
+followed by the moves. Here we'll parse a tournament's PGN file to find players
+who faced each other more than once (indicating tie-break games).
+
+The data comes from the Tata Steel Masters 2024 broadcast on Lichess, the
+[tie-break games can be seen
+here](https://lichess.org/broadcast/tata-steel-masters-2024/tiebreaks/L43YRQWv#boards).
+
+## The Complete Solution
+
+```mdtest-command
+curl -sS https://lichess.org/api/broadcast/ycy5D2r8.pgn |
+super -i line -s -c "
+  --
+  -- parse the pgn file
+  --
+  where this != ''
+  | grok('.*White \"%{WORD:last_name_white}|.*Black \"%{WORD:last_name_black}', this)
+  | where not is_error(this)
+
+  --
+  -- pair up each player in each game
+  --
+  | count
+  | put game_id:=((count - 1) / 2)::int64
+  | values {...that, game_id}
+  | aggregate
+      last_name_white:=max(last_name_white),
+      last_name_black:=max(last_name_black)
+    by game_id
+  | drop game_id
+
+  --
+  -- re-organize the data by player and opponent regardless of piece color
+  --
+  | [
+      {player: last_name_white, opponent: last_name_black},
+      {player: last_name_black, opponent: last_name_white}
+    ]
+  | unnest this
+
+  --
+  -- count each match-up of player and opponent and find any with counts > 1
+  --
+  -- this should be players who participated in tie-breaks, as the regular
+  -- tournament was only a single round-robin
+  --
+  | count(this) by player, opponent
+  | where count > 1
+  | sort player, opponent
+" -
+```
+
+```mdtest-output
+{player:"Abdusattorov",opponent:"Wei",count:3}
+{player:"Giri",opponent:"Gukesh",count:4}
+{player:"Gukesh",opponent:"Giri",count:4}
+{player:"Gukesh",opponent:"Wei",count:3}
+{player:"Wei",opponent:"Abdusattorov",count:3}
+{player:"Wei",opponent:"Gukesh",count:3}
+```
+
+## Walkthrough
+
+### Line Input and Filtering
+
+`-i line` tells super to treat each line as a separate string record. We filter
+out empty lines with `where this != ''`.
+
+### Grok Parsing
+
+The grok pattern `'.*White \"%{WORD:last_name_white}|.*Black \"%{WORD:last_name_black}'`
+uses alternation (`|`) to match either a White or Black player line. The
+`%{WORD:...}` capture extracts just the last name (the first word after the
+opening quote).
+
+Lines that don't match (like move notation or other metadata) produce errors,
+which we filter with `where not is_error(this)`.
+
+### Pairing Records
+
+PGN files list White and Black players on consecutive lines for each game. We
+need to combine them into single records.
+
+The `count` operator adds a sequential `count` field to each record (1, 2, 3, ...).
+Integer division `(count - 1) / 2` maps pairs of rows to the same game_id:
+rows 1,2 get game_id 0; rows 3,4 get game_id 1, etc. The `count` operator wraps
+the input in a `that` field, so `{...that, game_id}` spreads the original fields
+back out alongside the game_id.
+
+Then `aggregate ... by game_id` with `max()` picks up the non-null value from
+each field within each pair.
+
+### Reshaping with Arrays and Unnest
+
+Each game record has `{last_name_white, last_name_black}`. To count matchups
+regardless of color, we create an array with both perspectives:
+
+```
+| [{player: last_name_white, opponent: last_name_black},
+   {player: last_name_black, opponent: last_name_white}]
+| unnest this
+```
+
+This doubles our records — each game now appears twice, once from each player's
+perspective.
+
+### Final Aggregation
+
+`count(this) by player, opponent` counts how many times each matchup occurred.
+`where count > 1` filters to only matchups that happened more than once -
+these are the tie-break games.
+
+## Nested `unnest ... into` Example
+
+Here's a minimal dataset to demonstrate this next technique, based on similar
+data we were just working with. Four players in a single round-robin (6 games),
+plus one tie-breaker between Gukesh and Wei:
+
+```mdtest-input pairings.sup
+{pairing:"Giri Gukesh"}
+{pairing:"Giri Wei"}
+{pairing:"Giri Abdusattorov"}
+{pairing:"Gukesh Wei"}
+{pairing:"Gukesh Abdusattorov"}
+{pairing:"Wei Abdusattorov"}
+{pairing:"Gukesh Wei"}
+```
+
+```mdtest-command
+super -s -c "
+  split(pairing, ' ')
+  | unnest {pairing:this, player:this} into (
+      unnest {player: this.player, opponent: pairing} into (
+        where player != opponent
+        | cut player, opponent
+      )
+    )
+" pairings.sup
+```
+
+```mdtest-output
+{player:"Giri",opponent:"Gukesh"}
+{player:"Gukesh",opponent:"Giri"}
+{player:"Giri",opponent:"Wei"}
+{player:"Wei",opponent:"Giri"}
+{player:"Giri",opponent:"Abdusattorov"}
+{player:"Abdusattorov",opponent:"Giri"}
+{player:"Gukesh",opponent:"Wei"}
+{player:"Wei",opponent:"Gukesh"}
+{player:"Gukesh",opponent:"Abdusattorov"}
+{player:"Abdusattorov",opponent:"Gukesh"}
+{player:"Wei",opponent:"Abdusattorov"}
+{player:"Abdusattorov",opponent:"Wei"}
+{player:"Gukesh",opponent:"Wei"}
+{player:"Wei",opponent:"Gukesh"}
+```
+
+### How Nested Unnest Works
+
+The `unnest ... into` syntax is powerful but takes some unpacking:
+
+1. **`split(pairing, ' ')`** turns `"Giri Gukesh"` into `["Giri", "Gukesh"]`
+
+2. **First unnest**: `unnest {pairing:this, player:this} into (...)`
+   - Keeps the full array as `pairing`
+   - Unnests each element as `player`
+   - For `["Giri", "Gukesh"]` this produces two records:
+     - `{pairing: ["Giri", "Gukesh"], player: "Giri"}`
+     - `{pairing: ["Giri", "Gukesh"], player: "Gukesh"}`
+
+3. **Second unnest**: `unnest {player: this.player, opponent: pairing} into (...)`
+   - Preserves `player` from the outer record
+   - Unnests `pairing` array elements as `opponent`
+   - For `{pairing: ["Giri", "Gukesh"], player: "Giri"}` this produces:
+     - `{player: "Giri", opponent: "Giri"}`
+     - `{player: "Giri", opponent: "Gukesh"}`
+
+4. **`where player != opponent`** filters out self-matches
+
+The result: each pairing expands into both player/opponent perspectives.
+
+### Finding Tie-Breaks
+
+Now we can append the same count query to find players who faced each other
+more than once:
+
+```mdtest-command
+super -s -c "
+  split(pairing, ' ')
+  | unnest {all_pairings:this, player:this} into (
+      unnest {player: this.player, opponent: all_pairings} into (
+        where player != opponent
+        | cut player, opponent
+      )
+    )
+  | count(this) by player, opponent
+  | where count > 1
+  | sort player, opponent
+" pairings.sup
+```
+
+```mdtest-output
+{player:"Gukesh",opponent:"Wei",count:2}
+{player:"Wei",opponent:"Gukesh",count:2}
+```
+
+## as of versions
+
+```mdtest-command
+super --version
+```
+```mdtest-output
+Version: v0.2.0
+```