npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

draftty

v0.1.0

Published

Design CLIs in plain text before you build them. A YAML spec, a live terminal simulator, generated docs, and design checks.

Downloads

92

Readme

draftty

Design CLIs in plain text before you build them.

You write a YAML file describing what a CLI says: commands, help, output in each situation, and what --json returns. draftty turns it into:

  • try: a prompt and one screen. Type a command and see the designed output. The command's scenarios (default · empty · not-found) and --json switch the screen. Help, usage errors, "did you mean", and tab completion are generated.
  • docs: generated reference: every command with its arguments and options, the JSON and exit-code contract, and an example for each.
  • check: design checks for inconsistent verbs and flags, missing empty states, json gaps, and hints on stdout.

It works for a whole CLI or one part of one. It's built to be written by agents and reviewed by people, side by side.

Install

Needs Node.js 20 or later.

npm i -g draftty        # then: draftty <command>
npx draftty init        # or without installing

Quick start

In the project you're designing:

draftty init mycli      # design/mycli.yaml, design/AGENTS.md for your agent, .draftty/ in .gitignore
draftty dev             # browser: try, docs, check; reloads as you (or your agent) edit

Designs live in design/, one YAML file each. Every command finds them there (--spec overrides), and .draftty/ holds local state.

Working with an agent

draftty init writes design/AGENTS.md (and a CLAUDE.md that imports it), so any coding agent picks up this loop:

  1. draftty dev, once, in the background. It reloads on every save and prints what check finds.
  2. Edit the YAML.
  3. draftty check --fix: formats, updates handler types, and reports design issues. Exit 1 on errors.
  4. draftty run <command>: stdout, stderr and exit code exactly as designed.

draftty skill prints the agent skill: the workflow and the full spec reference.

Commands

| Command | What it does | |---|---| | init [name] | Start a design in ./design, with a brief for your agent | | dev [path] | Serve designs with a live terminal, docs, and checks | | build [path] --out <dir> | Write the designs as a static site you can host anywhere | | publish, pull | Share a draft through a draftty platform, and bring one back | | check [path] | Design checks, and drift between examples and handlers | | docs [path] | Print generated docs as Markdown | | types [path] | Generate TypeScript types for handlers from the spec | | run [design] <command...> | Run one command against a design | | use [design] | Make the design's binary (e.g. todo) run this design | | shell [design] | Open a shell where the design is a real binary, with fresh data | | reset [design] | Put a design's data back to its seed | | skill | Print the agent skill (SKILL.md) |

draftty <command> --help has the details.

The spec

name: vercel
title: observability
commands:
  drains:
    summary: Send logs to external services
    commands:
      ls:
        summary: List drains
        scenarios:
          default:
            run: vercel drains ls
            out: |
              {dim}id         name       status{/}
              drn_k2l9   datadog    {green}● healthy{/}
            json: [{ id: drn_k2l9, name: datadog, status: healthy }]
          empty:
            run: vercel drains ls
            err: "{dim}No drains yet. Add one with `vercel drains add <url>`.{/}"
            json: []

Output is written literally, because the wording is the design. Text output and --json sit side by side as two contracts for the same situation. {{arg}} placeholders fill in what the user typed. A variant extends: a design and only writes what differs. The full reference is in draftty skill.

Handlers and data

When a design has to work (filters that filter, add followed by ls), give it handlers: a TypeScript module that answers commands over plain JSON data.

name: todo
handlers: ./todo.ts                  # optional; commands without a handler use scenarios
data: ./fixtures.json                # { "todos": [ … ] }: the starting data
now: 2026-10-06T14:00:00Z            # a fixed clock, so runs are reproducible
commands:
  ls: { summary: List open todos, flags: { tag: { value: tag } } }
import { table } from "draftty/handler";
import { defineHandlers } from "./todo.types";   // generated by `draftty types`

export default defineHandlers({
  ls: ({ flags, data, out }) => {
    const rows = data.todos.filter((t) => !t.done && (!flags.tag || t.tags.includes(flags.tag)));
    out(table(rows, ["id", "title"]));
    return { json: rows };       // what --json prints
  },
});

Handlers are bundled into one browser module, which is what runs in draftty run and in the browser alike. So they can't use Node APIs, and they import only the design's own files and draftty/handler. The YAML still owns the surface: draftty parses and validates first, so the handler only sees valid input. With handlers, scenarios become examples, and check flags drift between them.

Share it

draftty build design/ --out site     # a static site: then `npx serve site`, or put it on any static host

License

MIT