@levu/snap

Snap

Snap is a contract-first TypeScript framework for terminal workflows.

It runs one action contract in 2 modes:

• TUI-first (default for interactive terminals)
• Auto CLI (non-interactive when required args are already provided)

It also enforces deterministic, text-only help so both humans and AI agents can discover commands reliably.

For module/tool authors, Snap also exposes optional DX helper groups:

• SnapArgs (typed argv readers/parsers)
• SnapHelp (arg-schema driven help + commandline contracts)
• SnapRuntime (standardized action result helpers)
• SnapTui (typed flow/component definitions, including custom components)

What this framework does

• Enforces action triad at registration: tui + commandline + help
• Uses one runtime engine for TUI and CLI paths
• Uses Clack-powered prompt adapters for interactive TUI (select, text, confirm, multiselect)
• Text prompts support clipboard paste and multiline input for pasting multiple lines
• Supports workflow transitions: next, back, jump, exit
• In TUI mode, pressing Esc backs to the previous workflow step by default; pressing Esc on the root step exits.
• Supports resume checkpoints for interrupted flows
• Produces stable help output hierarchy:
  • snap -h
  • snap -h <module>
  • snap -h <module> <action>

Repository

git clone [e-mail]:khanglvm/snap.git
cd snap

Quick start

npm install
npm run typecheck
npm run build
npm test

Usage

npm run dev -- -h
npm run dev -- content slugify --text="Hello World"
npm run dev -- system node-info

For module authors

Documentation

• Getting Started - Quick start guide
• Module Authoring Guide - Core concepts
• Help Contract Spec - Help format specification

DX Helper References

• SnapArgs - Type-safe argument reading
• SnapHelp - Schema-driven help generation
• SnapRuntime - Standardized action results
• SnapTui - Typed TUI flow definitions
• SnapTerminal - Terminal output helpers

Additional Resources

• Integration Examples - Common patterns
• Component Reference - All components and gaps

Examples

See examples/ for working code examples:

• basic-module.ts - Minimal module structure
• advanced-flow.ts - Multi-step workflows
• dx-helpers.ts - All DX helpers in action
• custom-prompt.ts - Custom prompts with validation