shell: add defaults param, fix 3 rendering bugs, add bedtools example

shell.create now accepts `defaults={name: value}` — per-input fallback
values applied when the caller omits an input. Works independently of
`T | None`: required + no default raises, optional + no default suppresses
the flag, either + default uses the default.

Three rendering bugs surfaced while building a bedtools intersect wrapper:

1. Positional-arg indices >= 10 were emitted as bare `$10`, which bash
   parses as `$1` followed by literal "0". Any task with 10+ scalar/bool
   inputs had its 10..N values silently corrupted. Fixed by always braced
   `${10}`.

2. Optional File / Dir flags emitted unconditionally — the renderer
   hardcoded `-flag /var/inputs/name` regardless of whether the caller
   supplied the file, so omitting an optional file flag pointed the tool
   at a missing path. Now guarded with
   `if [ -e <path> ]; then ...; else <flag>=""; fi`.

3. Inputs whose names differed only in case (e.g. `c` vs `C`, common in
   bio CLIs like bedtools / samtools) collided on the same `_VAL_*` /
   `_FLAG_*` bash variable and silently overwrote each other. create()
   now rejects this at declaration time with an error naming both
   offending inputs.

Adds 28 unit tests across the four-cell defaults matrix, optional
File/Dir flag emission, case-collision detection, and the positional-arg
brace regression.

New examples:
- examples/shell/12_bedtools_intersect_example.py — three intersect
  queries in parallel against a small BED fixture.
- examples/shell/modules/bedtools_intersect.py — typed wrapper around
  bedtools intersect; reference for bio-CLI shell-extra modules.

Signed-off-by: Kyle Hazen <kyle@union.ai>

Author: k1sauce

examples/shell/12_bedtools_intersect_example.py

@@ -0,0 +1,100 @@
+"""bedtools intersect — three common overlap queries against a peaks file.
+
+This example consumes ``modules/bedtools_intersect.py`` (a typed shell wrapper
+around the ``bedtools intersect`` CLI) and exercises three of its most-used
+flag combinations on a small BED fixture:
+
+- ``wa=True`` — write each A feature that has *any* overlap in B.
+- ``v=True``  — write each A feature that has *no* overlap in B (set diff).
+- ``c=True``  — write each A feature with a trailing count of B overlaps.
+
+Fixture (4 "genes" in A, 3 "peaks" in B, all on chr1):
+
+    A (genes)               B (peaks)
+    chr1 100-200 gene1      chr1 150-180 peak1   <- overlaps gene1
+    chr1 300-400 gene2      chr1 350-450 peak2   <- overlaps gene2
+    chr1 500-600 gene3      chr1 900-950 peak3
+    chr1 700-800 gene4
+
+Expected:
+- wa  -> gene1, gene2
+- v   -> gene3, gene4
+- c   -> gene1\\t1, gene2\\t1, gene3\\t0, gene4\\t0
+
+Run locally::
+
+    uv run python 12_bedtools_intersect_example.py
+"""
+
+import asyncio
+import tempfile
+
+import flyte
+from flyte.io import File
+
+from modules.bedtools_intersect import bedtools_intersect
+
+
+env = flyte.TaskEnvironment(
+    name="bedtools_intersect_example",
+    depends_on=[bedtools_intersect.env],
+)
+
+
+@env.task
+async def intersect_demo(genes: File, peaks: File) -> tuple[File, File, File]:
+    overlapping, non_overlapping, counts = await asyncio.gather(
+        bedtools_intersect(a=genes, b=[peaks], wa=True),
+        bedtools_intersect(a=genes, b=[peaks], v=True),
+        bedtools_intersect(a=genes, b=[peaks], count_overlaps=True),
+    )
+    return overlapping, non_overlapping, counts
+
+
+GENES_BED = (
+    "chr1\t100\t200\tgene1\t0\t+\n"
+    "chr1\t300\t400\tgene2\t0\t+\n"
+    "chr1\t500\t600\tgene3\t0\t+\n"
+    "chr1\t700\t800\tgene4\t0\t+\n"
+)
+
+PEAKS_BED = (
+    "chr1\t150\t180\tpeak1\t0\t+\n"
+    "chr1\t350\t450\tpeak2\t0\t+\n"
+    "chr1\t900\t950\tpeak3\t0\t+\n"
+)
+
+
+
+
+# Fixtures
+# mkdir -p /tmp/bedtools-fixtures && \
+# printf 'chr1\t100\t200\tgene1\t0\t+\nchr1\t300\t400\tgene2\t0\t+\nchr1\t500\t600\tgene3\t0\t+\nchr1\t700\t800\tgene4\t0\t+\n' > /tmp/bedtools-fixtures/genes.bed && \
+# printf 'chr1\t150\t180\tpeak1\t0\t+\nchr1\t350\t450\tpeak2\t0\t+\nchr1\t900\t950\tpeak3\t0\t+\n' > /tmp/bedtools-fixtures/peaks.bed && \
+# ls -la /tmp/bedtools-fixtures/
+
+if __name__ == "__main__":
+
+    flyte.init()
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".bed", delete=False) as f:
+        f.write(GENES_BED)
+        genes_path = f.name
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".bed", delete=False) as f:
+        f.write(PEAKS_BED)
+        peaks_path = f.name
+
+    run = flyte.with_runcontext().run(
+        intersect_demo,
+        File.from_local_sync(genes_path),
+        File.from_local_sync(peaks_path),
+    )
+
+    print(run)
+
+    out = run.outputs()
+    overlapping_path = out.o0.download_sync("./overlapping.bed")
+    non_overlapping_path = out.o1.download_sync("./non_overlapping.bed")
+    counts_path = out.o2.download_sync("./counts.bed")
+    print(f"Wrote: {overlapping_path}, {non_overlapping_path}, {counts_path}")

examples/shell/modules/bedtools_intersect.py

@@ -0,0 +1,69 @@
+from flyte.extras import shell
+from flyte.io import File
+
+IMAGE = "quay.io/biocontainers/bedtools:2.31.1--hf5e1c6e_0"
+
+# Inputs use descriptive Python names where the bedtools CLI has case-only
+# collisions (`-c`/`-C`, `-s`/`-S`, `-f`/`-F`). The shell renderer builds
+# bash variable names by uppercasing the Python name, so two inputs whose
+# names differ only in case would collide on the same `_FLAG_*` slot.
+# `flag_aliases` maps each descriptive Python name to the actual CLI flag.
+bedtools_intersect = shell.create(
+    name="bedtools_intersect",
+    image=IMAGE,
+    inputs={
+        "a": File,
+        "b": list[File],
+        "wa": bool | None,
+        "wb": bool | None,
+        "loj": bool | None,
+        "wo": bool | None,
+        "wao": bool | None,
+        "u": bool | None,
+        "count_overlaps": bool | None,
+        "count_per_file": bool | None,
+        "v": bool | None,
+        "same_strand": bool | None,
+        "opposite_strand": bool | None,
+        "frac_a": float | None,
+        "frac_b": float | None,
+        "r": bool | None,
+        "e": bool | None,
+        "ubam": bool | None,
+        "bed": bool | None,
+        "sorted": bool | None,
+        "nonamecheck": bool | None,
+        "g": File | None,
+        "names": str | None,
+        "filenames": bool | None,
+        "sortout": bool | None,
+        "split": bool | None,
+        "header": bool | None,
+        "nobuf": bool | None,
+        "iobuf": str | None,
+    },
+    outputs={"out": File},
+    flag_aliases={
+        "b": "-b",
+        "count_overlaps": "-c",
+        "count_per_file": "-C",
+        "same_strand": "-s",
+        "opposite_strand": "-S",
+        "frac_a": "-f",
+        "frac_b": "-F",
+    },
+    script=r"""
+        bedtools intersect \
+            -a {inputs.a} \
+            {flags.b} \
+            {flags.wa} {flags.wb} {flags.loj} {flags.wo} {flags.wao} \
+            {flags.u} {flags.count_overlaps} {flags.count_per_file} {flags.v} \
+            {flags.same_strand} {flags.opposite_strand} \
+            {flags.frac_a} {flags.frac_b} {flags.r} {flags.e} \
+            {flags.ubam} {flags.bed} \
+            {flags.sorted} {flags.nonamecheck} {flags.g} \
+            {flags.names} {flags.filenames} {flags.sortout} \
+            {flags.split} {flags.header} {flags.nobuf} {flags.iobuf} \
+            > {outputs.out}
+    """,
+)

src/flyte/extras/shell/_render.py

@@ -5,7 +5,7 @@
 import shlex
 from typing import Any, Tuple
 
-from ._types import FlagSpec, Stderr, Stdout, _classify_input
+from ._types import FlagSpec, Stderr, Stdout, _classify_input, _is_optional
 
 _PLACEHOLDER_RE = re.compile(r"\{(inputs|flags|outputs)\.([a-zA-Z_][a-zA-Z0-9_]*)\}")
 _DICT_SEP = "\x1e"
@@ -20,6 +20,7 @@ def _render_command(
     output_data_dir: pathlib.Path,
 ) -> Tuple[str, list[str]]:
     kinds = {name: _classify_input(name, tp) for name, tp in inputs.items()}
+    optionals = {name: _is_optional(tp)[0] for name, tp in inputs.items()}
 
     preamble_lines: list[str] = []
     positional_templates: list[str] = []
@@ -34,7 +35,11 @@ def alloc_slot(name: str) -> str:
         idx = len(positional_templates) + 1
         positional_templates.append(f"{{{{.inputs.{name}}}}}")
         var = f"_VAL_{name.upper()}"
-        preamble_lines.append(f'{var}="${idx}"')
+        # Brace the positional index: bash parses `$10` as `$1` + `"0"`,
+        # so any task with 10+ scalar/bool inputs would silently bind
+        # later variables to the wrong values. `${10}` is the only form
+        # that works for indices ≥ 10.
+        preamble_lines.append(f'{var}="${{{idx}}}"')
         slot_var_for[name] = var
         return var
 
@@ -90,6 +95,7 @@ def render_flag_ref(name: str) -> str:
                     alloc_slot,
                     ensure_dict_decoded,
                     input_data_dir,
+                    is_optional=optionals[name],
                 )
             )
         if kind in ("list_file", "dict_str"):
@@ -139,6 +145,7 @@ def _emit_flag_setter(
     alloc_slot,
     ensure_dict_decoded,
     input_data_dir: pathlib.Path,
+    is_optional: bool = False,
 ) -> str:
     flag = spec.flag
     sep = spec.separator
@@ -155,6 +162,12 @@ def _emit_flag_setter(
         )
     if kind in ("file", "dir"):
         path = input_data_dir / name
+        if is_optional:
+            return (
+                f'if [ -e {shlex.quote(str(path))} ]; then '
+                f'{flag_var}={shlex.quote(flag + sep + str(path))}; '
+                f'else {flag_var}=""; fi'
+            )
         return f"{flag_var}={shlex.quote(flag + sep + str(path))}"
     if kind == "list_file":
         dirpath = input_data_dir / name