chore: interpolate example code in README.md for each package

This script will modify the given files (all CLI arguments passed to the
script are interpreted as filenames) to interpolate example code from files.

It looks for lines that look like this:

[This example code](../path/to/file.ts) shows how to do X.

And replaces those occurrences to look like this:

This example code shows how to do X.

```ts
// Contents of ../path/to/file.ts
```

This simple hack allows us to keep our code examples in separate files
(which are runnable and testable in CI), while still including them inline in
the documentation that gets published to npmjs.org for the packages.

.github/workflows/ci.yaml

@@ -34,6 +34,9 @@ jobs:
       - run: pnpm install --no-frozen-lockfile
       - run: pnpm run test
 
+      # Validate that the prepublish hook works.
+      - run: pnpm run prepublish
+
       # Finally, release (actual publishing only happens on the main branch).
       - run: pnpm run release
         env:

package.json

@@ -21,6 +21,7 @@
     "check": "pnpm turbo check",
     "lint": "pnpm turbo lint",
     "format": "pnpm turbo format",
+    "prepublish": "pnpm turbo prepublish",
     "release": "pnpm run -r --workspace-concurrency 1 release --"
   }
 }

packages/kurt-open-ai/README.md

@@ -8,4 +8,4 @@ This package implements an adapter for Kurt that works with [OpenAI's GPT models
 
 ## Examples
 
-Check the [example folder](https://github.com/FormulaMonks/kurt/tree/main/examples)
+[This example code](../../examples/basic/src/openai.ts) shows how to set up and use Kurt with OpenAI.

packages/kurt-open-ai/package.json

@@ -19,6 +19,7 @@
     "format": "pnpm biome format --write .",
     "lint": "pnpm biome lint --apply .",
     "check": "pnpm biome check .",
+    "prepublish": "../../scripts/interpolate-example-code.sh README.md",
     "release": "pnpm exec semantic-release"
   },
   "release": {

packages/kurt-vertex-ai/README.md

@@ -8,4 +8,4 @@ This package implements an adapter for Kurt that works with [Vertex AI's Gemini
 
 ## Examples
 
-Check the [example folder](https://github.com/FormulaMonks/kurt/tree/main/examples)
+[This example code](../../examples/basic/src/vertex.ts) shows how to set up and use Kurt with Vertex AI.

packages/kurt-vertex-ai/package.json

@@ -19,6 +19,7 @@
     "format": "pnpm biome format --write .",
     "lint": "pnpm biome lint --apply .",
     "check": "pnpm biome check .",
+    "prepublish": "../../scripts/interpolate-example-code.sh README.md",
     "release": "pnpm exec semantic-release"
   },
   "release": {

packages/kurt/package.json

@@ -19,6 +19,7 @@
     "format": "pnpm biome format --write .",
     "lint": "pnpm biome lint --apply .",
     "check": "pnpm biome check .",
+    "prepublish": "../../scripts/interpolate-example-code.sh README.md",
     "release": "pnpm exec semantic-release"
   },
   "release": {

scripts/interpolate-example-code.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+
+set -euo pipefail
+
+# This script will modify the given files (all CLI arguments passed to the
+# script are interpreted as filenames) to interpolate example code from files.
+#
+# It looks for lines that look like this:
+#
+# [This example code](../path/to/file.ts) shows how to do X.
+#
+# And replaces those occurrences to look like this:
+#
+# This example code shows how to do X.
+#
+# ```ts
+# // Contents of ../path/to/file.ts
+# ```
+#
+# This simple hack allows us to keep our code examples in separate files
+# (which are runnable and testable in CI), while still including them inline in
+# the documentation that gets published to npmjs.org for the packages.
+
+for file in "${@}"; do
+  echo "Interpolating example code in $file"
+
+  IFS=''
+  while read -r line; do
+    if echo "$line" | grep -E '\[This example code\]\([^)]+\).+$' > /dev/null; then
+      # If the line contains the pattern indicating a code example, fetch
+      # the code and print it as a markdown code block.
+      file_path=$(echo $line | cut -d '(' -f 2 | cut -d ')' -f 1)
+      file_code=$(cat $file_path)
+
+      # Print the line without the code link, followed by the code block.
+      printf "This example code"; echo "$line" | cut -d ')' -f 2-
+      echo # Empty line before the snippet
+      echo '```ts'
+      cat $file_path
+      echo '```'
+    else
+      # For all lines which don't match the pattern, print them as-is.
+      echo "$line"
+    fi
+  done < "$file" > "$file.tmp"
+  mv "$file.tmp" "$file"
+
+  git diff --color "$file" | cat
+done

turbo.json

@@ -15,6 +15,7 @@
     },
     "check": {},
     "format": {},
-    "lint": {}
+    "lint": {},
+    "prepublish": {}
   }
 }