The Shell-Pipe Foundry
Turn an ad-hoc A | B | C into a saved, typechecked, discoverable tool — before you run it in anger.
The ingredients 4 gifts
The idea
You have a shell pipe you keep re-typing: some tool, piped into another, piped into a third. It works, but it lives in your history and nobody else can find it or trust it. This kit turns that throwaway pipe into a first-class, checkable artifact. port is the small convention that makes it possible — every JSONL tool declares its own port-verb (source, transform, filter, fold, sink). Once the tools declare, map can fold a whole folder of them into a directory you can search, conductor can run the pipeline with a record of what happened, and declare can freeze your favorite pipe into a named, shareable score.
The parts + how they wire
Each small tool carries a port declaration (port) → map points at the folder and folds every tool's declared verb into one searchable index: what you have, and what can legally feed what → you assemble a pipeline and hand it to conductor, which typechecks the chain against those port-verbs before running a byte and then runs it under a record → declare takes the pipe you just proved and saves it as a named 'gift score' others can pull and run without reconstructing it from your shell history. The spine that ships is port -> map -> conductor: declare and typechecking are what make it safe to share, not just to run once.
The one piece you build
One real component: the wrapper that reads your existing tools' output and attaches a port declaration to each, then a thin config naming the pipeline you want conductor to run. If your tools already emit JSONL, this is a small adapter per tool plus a pipeline file; if they don't, the adapter is where the work is.
The technical breakdown
The port-verb is the whole trick and it is deliberately tiny: five verbs (source emits and accepts nothing upstream, sink accepts and emits nothing downstream, transform/filter/fold sit in the middle) and one rule — A can feed B iff A emits and B accepts. That rule is what conductor checks before it runs: a source piped into a source is refused at typecheck time, not discovered three tools deep when the second stage gets a record it can't parse. map reads the same declarations to build its index, so 'what can feed this' is a query, not tribal knowledge. declare's saved score records the exact tool versions and the pipeline shape, so a pulled score runs the pipe you proved, not a drifted copy. Roughly 80-150 lines depending on how many tools need adapters — the gifts supply the port convention, the fold, the runner, and the freezer; you supply the adapters and the pipeline definition.
The honest edge
The typecheck is port-level only. A clean check proves the tools are pipe-compatible — source to filter to fold — not that the records actually line up: conductor will happily run a chain where stage two emits fields stage three never reads, because both are 'transforms.' Port-compatibility catches the gross mistakes (a sink at the head, two sources chained) and nothing about record shape. That is the honest ceiling the port convention itself declares: it makes the plumbing legible and refuses the impossible, but it does not prove the water is clean.
These are ingredients, not instructions you have to follow. If you cook something from them — or something stranger — we want to see it.