Tetch

Sidecar scaffold, external metadata extractor, and drift sync toolchain for Tomet (tetch).

Overview

tetch bridges arbitrary non-Tomet files (videos, images, scripts, source code, binaries) with companion Tomet (.tmt) sidecar documents.

While core tomet remains pure and deterministic, tetch acts as the reactive airlock to the operating system: it runs external commands (ffprobe, exiftool, git, user shell scripts) to extract facts and etches them into static, typed Tomet metadata.

Features

• Sidecar Scaffolding: Create companion .tmt files alongside any asset (foo.mp4 -> foo.mp4.tmt).
• Blueprint-driven Extraction: Define reusable templates with ${etch.target.sha256} and ${etch.cmd("...")} expressions.
• Drift Detection (check): Verify that recorded hashes and metadata still match the actual files on disk. Returns exit code 1 on drift for CI pipelines.
• Non-destructive Sync (sync): Update stale metadata while preserving human-written body text and notes.
• Sisho Integration: Fully compatible exit codes (0 ok, 1 changed, 2 error) and --format json output.

Usage

# Scaffold a basic sidecar
tetch init assets/movie.mp4

# Scaffold using a blueprint with external commands
tetch init scripts/deploy.sh --blueprint blueprints/script.blueprint.tmt

# Check all sidecars for drift
tetch check .

# Check with JSON output
tetch check . --format json

# Re-sync drifted sidecars with disk state
tetch sync .