feat(cli): excellent per-subcommand --help, thin SKILL.md, 0.3s default --seq delay (#68)
Three bundled improvements toward "pty is independently useful: a great --help
(the reference) + a thin SKILL.md (the judgment)".
--help (the reference):
- Every subcommand now ships focused `--help` (usage + every flag + >=1 example)
via a central COMMAND_HELP registry + a single interceptor. Previously most
subcommands errored or silently ran on `--help`. renameUsage/printEmitHelp now
read from the same source, so error-usage and --help can't drift.
- Top-level `usage()` already listed every subcommand; added the missing
`run --force` line.
- tests/help.test.ts asserts every subcommand has working `--help`, and that no
dispatch `case` is undocumented (drift guard).
--seq default delay (decision from Nathan):
- `pty send --seq` now inserts a 0.3s gap between items by default so a trailing
key:return doesn't race ahead of the program parsing the typed text.
`--with-delay 0` = straight stream (opt-out); `--with-delay N` honored.
- resolveSeqDelayMs() (pure, in client.ts) is the single decision point; the
library send() still treats delayMs literally, so programmatic callers are
unchanged.
- tests/seq-delay.test.ts: deterministic (a) default=300ms, (b) 0=0, (c) N=N,
plus a delta-timed end-to-end check that 0 = no spacing.
- `pty send --help` + top-level usage state the 0.3 default and the 0 opt-out.
SKILL.md (the judgment): thinned to the routing-hook + what/when/idiom/footguns/
delegate shape. Footguns captured: broken global `pty` on PATH silently breaks
the whole message bus (st shells to `pty send`); PTY_ROOT is the isolation
mechanism (PTY_SESSION_DIR is masked under an ambient PTY_ROOT); and the --seq
timing footgun with the WHY (byte-burst vs spaced input; Enter racing the
program's parse/render), now mostly handled by the 0.3s default.
docs: fix stale client API + development docs (onboarding audit) (#63)
Audited README + all repo docs against the code on main. Two files carried
factual errors; the rest (README, CHANGELOG, disk-layout, SKILL, testing)
verified accurate.
docs/client.md:
- gc() documented as `Promise<string[]>` returning removed names; it actually
returns a `GcResult` object. Corrected the signature, example, and added the
GcResult shape.
- getSessionDir() described only `PTY_SESSION_DIR`; it prefers the canonical
`PTY_ROOT` (legacy name still honored).
- isReservedTagKey() listed `supervisor.status`, which is no longer a reserved
key (the supervisor was replaced by cron gc). Removed it.
DEVELOPMENT.md:
- Said the project "ships TypeScript directly, no build step, run via tsx".
Actually: tsx is not a dependency, `npm run build` compiles src/ to dist/
(rewriteRelativeImportExtensions), the published package ships dist/, and
bin/pty runs dist/cli.js with Node. Rewrote the build section, the design-
decision note, the architecture line, and the bin/pty entry; dev-usage
examples now use `node --experimental-strip-types src/cli.ts`.
- `pty run <name> <command>` -> `pty run -- <command>` (actual syntax).
- Socket-override env `$PTY_SESSION_DIR` -> canonical `$PTY_ROOT`.
verify-docs (docs/testing.md executable examples) still passes: 13/13.