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.
lean-core: delete pty state + pty wrap; --help + completions rewrite (#58)
Two lean-core deletes and an accuracy pass on the help / completion
surface. Nathan authorized, cos briefed, usage-check across pty,
eval-sandbox/st-evals, convoy, pty-claude-launcher, cos, pty-relay,
and pty-layout came back clean — no external consumers.
BREAKING (no back-compat shim):
- `pty state` (subcommand + programmatic API + events + metadata field)
gone. CLI subcommands `get`/`set`/`delete`/`keys` removed. Public
API exports `getState`, `getStateKey`, `setState`, `deleteState`,
`listStateKeys` dropped from `@myobie/pty/client`. Event types
`state.set` and `state.delete` removed from `EventRecord`.
`SessionMetadata.state?` field removed — Storage format change;
existing metadata files with a populated `state` object silently
drop the field on the next daemon-side rewrite.
- `pty wrap` / `pty unwrap` / `pty wrap --list` removed. `PTY_BIN_PATH`
env var no longer consumed. `~/.local/pty/bin/` no longer created;
existing shims can be `rm -rf`'d by hand.
Redundant with smalltalk's folder-and-bus persistence (for state) and
orthogonal to the session primitive contract (for wrap).
Accuracy pass:
- `usage()` rewritten. Commands grouped logically (Create / Attach &
interact / Observe / Modify / Lifecycle / Multi / Global); every
flag every current subcommand accepts listed; `<ref>` semantics and
the four env vars (PTY_ROOT / PTY_SESSION_DIR / PTY_ROOT_LEGACY_SILENT
/ PTY_SESSION) documented.
- `completions/pty.{fish,bash,zsh}` rewritten against the same surface.
Every current subcommand + every accepted flag covered; `state`,
`wrap`, `unwrap` removed. All three shells consistent.
Tests: tests/state.test.ts deleted (485 LOC). tests/atomic-writes.test.ts
and tests/events.test.ts shed their state-specific cases.
Suite: 1202 passed, 21 skipped, 0 failed (down from 1231 in main; -29
across the deleted state.test.ts + removed state.* format assertions +
one atomic-writes setState concurrency test).
Delta: +467 / -1223 across 14 files (13 modified, 1 deleted).