# dsk-cli

DSL Development Kit (DSK) – a CLI that helps you design, build, test, and ship Tree-sitter based Domain-Specific Languages (DSLs) with a convention-over-configuration workflow.

## Why this is helpful
- **Lower barrier to entry**: Generate a working Tree-sitter `grammar.js` from examples via an interactive flow.
- **No boilerplate**: One command builds both a C static library and a Node.js addon package.
- **Fast iteration**: Built-in watch mode (`dsk dev`) and testing (`dsk test`).
- **Editor-ready**: Generate Tree-sitter highlight queries and editor scaffolds (Neovim, Emacs, VS Code).
- **Consistent outputs**: Standardized project layout and generated artifacts under `generated/` and `dist/`.

## Prerequisites
- macOS or Linux
- [Bun](https://bun.sh) (to run `dsk`)
- [tree-sitter CLI](https://tree-sitter.github.io/tree-sitter/creating-parsers#installation) (`npm i -g tree-sitter-cli` or `brew install tree-sitter`)
- C toolchain: clang/gcc and `ar` (macOS: `xcode-select --install`, Ubuntu: `build-essential`)
- For the generated JS addon builds: Python 3 and make are typically required by node-gyp (the template depends on `node-gyp`)

## Install (for developing this CLI)
```bash
bun install
bunx tsc
bun link  # optional: exposes `dsk` on your PATH during development
```

## Quickstart (creating a DSL)
```bash
# 1) Scaffold a new DSL project interactively
dsk new my-lang --interactive

# 2) Move into the project directory
cd my-lang

# 3) Build (generates parser, C lib, and JS addon)
dsk build

# 4) Run tests (expects corpus in `corpus/` or queries)
dsk test -v

# 5) Iterate with watch mode
dsk dev --debounce 150

# 6) Generate editor highlighting scaffolds
dsk highlight

# 7) Package outputs for distribution
dsk package
```

## Command reference

### `dsk new <name> [--interactive]`
Creates a new DSL project. With `--interactive`, it asks for examples and infers common token patterns, then generates a starter `grammar.js` and project structure using templates.

### `dsk build` [--verbose] [--skip-c] [--skip-js]
Builds your DSL:
- Runs `tree-sitter generate`
- Builds a C static library and header under `generated/c/`
- Creates a Node.js addon package under `generated/js/` (compiles via node-gyp)

Outputs:
- `generated/c/include/<dsl>.h`
- `generated/c/lib/lib<dsl>.a`
- `generated/js/` (package.json, binding.gyp, compiled addon, copied `src/`)

### `dsk test` [-u|--update] [-f|--filter <regex>] [--cwd <dir>] [-v|--verbose] [patterns...]
Thin wrapper around `tree-sitter test` that streams output directly.
- `--update`: updates expected output snapshots
- `--filter <regex>`: only run tests whose description matches
- `--cwd <dir>`: run tests in a different directory
- `--verbose`: pass through verbose output

Examples:
```bash
dsk test
dsk test -v -f numbers
dsk test -u corpus/examples.txt
```

### `dsk dev` [--debounce <ms>] [--quiet] [-v|--verbose]
Watches `grammar.js` and on changes runs `dsk build` then `dsk test`.
- `--debounce <ms>`: delay rebuild after changes (default: 150)
- `--quiet`: suppress non-error logs
- `--verbose`: pass to `dsk build` (more detailed build logs)

### `dsk highlight`
Generates highlighting assets and editor scaffolds:
- `generated/editors/tree-sitter/highlights.scm`
- `generated/editors/neovim/setup-instructions.md`
- `generated/editors/emacs/<lang>-mode.el`
- `generated/editors/vscode/syntaxes/<lang>.tmLanguage.json`
- `generated/editors/vscode/language-configuration.json`

### `dsk package`
Packages build outputs into `dist/`:
- Archives `generated/c/` as `dist/c-artifacts.tar.gz`
- Packs the JS addon under `generated/js/` via `bun pack` (falls back to `npm pack`)

### `dsk self:package`
Builds and packages the `dsk` CLI itself into a tarball under `release/`.
```bash
dsk self:package
# → release/dsk-cli-<version>.tgz
```

## Project structure (generated DSL project)
- `grammar.js`: Tree-sitter grammar
- `src/`: generated parser sources after `tree-sitter generate`
- `corpus/`: test cases for `tree-sitter test`
- `generated/`: build outputs (C and JS targets)
- `generated/editors/`: highlight queries and editor scaffolds
- `dist/`: packaged artifacts

## Notes about the JS addon template
- Depends on `node-addon-api` and `node-gyp` (declared in template `package.json`)
- `binding.gyp` includes Node-API headers and defines `NAPI_VERSION=8`
- Builds via `npm install` or `bun install` in `generated/js/` (auto-detected)

## Troubleshooting
- `tree-sitter` not found: install with `npm i -g tree-sitter-cli` or `brew install tree-sitter`
- C compiler not found: macOS `xcode-select --install`; Linux install `build-essential`
- node-gyp build issues: ensure Python 3 and make are available; re-run `dsk build -v`

---

This project was created using `bun init` in bun v1.1.29. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.