// STRYKE-DEMO — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

stryke-demo is a meta-package that exercises every connector in the stryke-* family from a single repo. The 14 demos are runnable end-to-end: clone, s install, make up, make all. Each demo is a standalone .stk script (not embedded in test fixtures) so it doubles as living documentation for "how do I actually use this connector?" — and each is written to call every public verb of its connector, printing the function name alongside each line of output.

The harness is intentionally thin: no test framework, no assertions, no fancy reporting in the demo files. Each demo prints what it's doing as it goes. The orchestration lives in run_all.stk, which calls each connector's ::ping() to decide which demos can run in the current environment. A separate t/ directory holds cross-connector integration tests that do reconcile results between engines (Arrow↔DuckDB↔Parquet↔Polars).

~HARNESS DESIGN

Demos live in demos/ with NN_pkg.stk naming. Numbering is stable across releases so the README, docs, and run_all.stk can refer to demos by index. Adding a new connector is "drop a new file with the next index, add a row to the README table, update stryke.toml".

$SERVICE PROBE LOGIC

run_all.stk uses all 14 connector roots and classifies each demo into three buckets at startup:

Each runnable demo is dispatched via system("s", $path). Unreachable demos print ── NN name: SKIP (service not reachable); reachable ones print a ════ NN name ════ banner before their output. The in-process demos always run, so make all exercises a meaningful smoke set even on a bare machine.

&WHY GALLERY-NOT-TEST-SUITE

A test suite asserts. A gallery shows. The demos/*.stk files deliberately do no assertions — they print what they did and how, so the demo source reads as living documentation for each connector. The per-connector correctness tests live in each stryke-* package's own repo; this repo's job is to demonstrate the surface, not re-test it.

The CI workflow in this repo does not run the demos live — spinning up the full docker-compose stack on every GitHub Actions job is slow and brittle, and the cloud/reflection demos (gcp, grpc) can't run there at all. Instead CI pins the structure the demos depend on: the 14 git deps in stryke.toml, the contiguous 01..14 demo numbering, one Makefile target per demo, a valid docker compose config with the seven services, and the full doc/README/man-page gate set. Live runs happen on the maintainer's box via make all.

%DEMO ANATOMY

Every demos/NN_pkg.stk follows the same shape so the files stay scannable:

1. #!/usr/bin/env stryke shebang + a header comment with the run command and any required env vars.
2. A single use Pkg directive (the first non-comment line — pinned by tests/repo-contract.sh).
3. One # ── Pkg::verb ── banner per public function, then a p "Pkg::verb ..." line that calls it and prints the result — so the output is a literal transcript of the connector's API.
4. Cleanup at the end (drop temp files, temp tables, created topics / objects / k8s resources / containers).

The connection target comes from the environment (MYSQL_URI, POSTGRES_URI, REDIS_URL, MONGODB_URI, KAFKA_BROKERS, AWS_ENDPOINT_URL & friends, KUBECONFIG, DOCKER_HOST); the make target sets a localhost default that matches docker-compose.yml. A few demos read opt-in flags (STRYKE_DEMO_LAMBDA, STRYKE_DEMO_DOCKER_BUILD, STRYKE_DEMO_DOCKER_PUSH, STRYKE_DEMO_SPARK_SCRIPT) to enable slower or destructive branches; unset, those are skipped.

/EXTENDING

Adding a connector to the family means a set of coordinated edits in stryke-demo, several of which are pinned by tests/repo-contract.sh and the CI layout job:

1. Add the dep to stryke.toml under [deps] (key must match the demo filename suffix and point at MenkeTechnologies/stryke-<name>).
2. Drop demos/15_newpkg.stk — first line a use directive — that exercises the connector's public verbs.
3. Add a make newpkg target (and list it under .PHONY).
4. Add a run_demo "15 newpkg", Newpkg::ping(), "demos/15_newpkg.stk" line in run_all.stk (it dispatches each demo explicitly, not by directory scan).
5. If it needs a live service, add it to docker-compose.yml.
6. Update the count claims in this report and the demo table in index.html.

The numbering must stay contiguous (01..NN, no gaps or duplicates) and the [deps] keys must be a 1:1 match with the demo filenames — both are enforced by tests/repo-contract.sh.

#PROJECT METADATA