cli-ts

Files (2)

• SKILL.md
• engineering.md · references/

SKILL.md (first lines)

# TypeScript CLI Engineering

Build TypeScript command-line interfaces as stable public APIs. Optimize for predictable automation, packed-artifact correctness, safe releases, and maintainable external-service boundaries.

## Scope

This skill handles TypeScript CLI architecture, command contracts, package builds, npm distribution, CI/CD, documentation, and agent-facing output. Release, publish, tag, merge, and external writes stay separate authorization boundaries.

## Workflow

1. Inspect `package.json`, lockfile, TypeScript config, executable entry, command registration, tests, workflows, docs, and repository instructions.
2. Preserve the current package manager, module format, parser, test runner, and release model unless a measured requirement justifies change.
3. Classify the CLI:
   - Use Node `util.parseArgs` for one or two flat commands.
   - Use Commander for nested operational command trees.
   - Use oclif only when plugins, installers, autoupdate, or large lazy-loaded trees are real requirements.
4. Freeze the public contract before editing: binary names, command paths, flags, defaults, config precedence, stdout, stderr, exit behavior, and version policy.
5. Keep the executable and command handlers thin. For one external service, put SDK access in a direct client or domain module. Add `providers/` only when multiple providers or interchangeable backends are real requirements.
6. Validate external input at boundaries. Treat SDK types as implementation help, not runtime validation.
7. Build once, inspect the packed artifact, install that tarball in a temporary prefix, and run every binary's `--help`, `--version`, success, and failure paths.
8. Run format check, typecheck, focused tests, full tests, package smoke, docs build, and `git diff --check`.
9. Before release, re-check current official Node, npm, GitHub Actions, parser, bundler, and registry requirements. Never copy stale action versions or OIDC requirements from memory.

Read [references/engineering.md](references/engineering.md) for architecture, output contracts, testing, CI, release, docs, and primary sources.

## Agent-friendly contract

For automation-first commands:

- Write exactly one documented JSON value to stdout on success.
- Keep stderr empty on success.
- Write exactly one redacted JSON error to stderr on failure and exit nonzero.
- Keep `--help` and `--version` human-readable on stdout with exit 0.
- Give every error a stable `code`, safe `message`, boolean `retryable`, and non-empty ordered `next_steps`.
- Make `retryable` true only when repeating the same operation is safe. Reconcile ambiguous writes before retrying.
- Never print secrets, raw request headers, stack traces, full configuration, or provider payloads that may contain credentials.
- Prefer `process.exitCode` over forced `process.exit()` so output is not truncated.

Do not force a universal success wrapper onto an existing CLI. Preserve compatible provider response shapes and document each command schema.

## Design rules

- Treat commands, flags, aliases, defaults, output schemas, error codes, exit behavior, environment variables, and config paths as versioned API.
- Keep one command registration root and one central output/error boundary.
- Keep SDK calls out of command registration. Use a direct client or domain module for one service; use provider modules only for real multi-provider or replaceable-backend designs.
- Pin external SDKs exactly when their generated types and endpoints define observable CLI behavior.
- Add no plugin system, factory, dual-module build, importable library API, or custom updater until required.
- Prefer generated help as the exact flag reference. Keep README short and put durable details in `docs/`.
- Never manually edit generated changelogs or release artifacts.

## Release safety

- Use least-privilege workflow permissions and pin third-party actions by full commit SHA.
- Prefer npm trusted publishing with OpenID Connect (OIDC) on supported hosted runners over long-lived publish tokens.
- Preserve the trusted publisher's exact repository, workflow filename, environment, and allowed-action binding.
- Keep one release authority. When Release Please is adopted, it owns versions, changelogs, tags, and GitHub Releases.
- Gate publishing on the release action's output and keep it in the same workflow run when using `GITHUB_TOKEN`; action-created tags do not start another workflow.
- Use a GitHub App token when release PR CI or auto-merge must run unattended. Otherwise document the approval-required CI state and verify the repository setting that permits Actions to create pull requests.
- Verify tag and package versions match, publish the same tested tarball, and read the version back from npm.
- Treat release, publish, tag, merge, and external writes as separate authorization boundaries.

## Completion evidence

Report changed public contracts, exact verification commands and results, packed artifact proof, and any release action still awaiting authorization. Do not declare success from source tests alone.

From vanducng/skills, MIT.

More from vanducng/skills