stop-wasting-tokens 1.0.0 → 1.5.2

package/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to stop-wasting-tokens
+
+Thanks for considering a contribution. The project is in early alpha and the surface is changing quickly, so please open an issue before starting non-trivial work.
+
+## Code of Conduct
+
+All participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Beta tester
+
+The v0.1.0-alpha closed beta is live. If you want to help shape v1.0:
+
+- Read the [beta tester guide](https://docs.stopwastingtokens.dev/recipes/beta-feedback) — it covers install, what to test, and how to report what you find.
+- File [friction reports](.github/ISSUE_TEMPLATE/friction.md) — even subtle "this should be smoother" feedback is signal.
+- Join the closed-beta Discord (invite via DM during the beta window).
+- Optionally enable anonymous telemetry: `swt config set telemetry.enabled true`.
+
+Top-10 friction items will be addressed before v1.0 release.
+
+## Reporting issues
+
+- **Bug:** use the bug template under `.github/ISSUE_TEMPLATE/`. Include reproduction steps, expected vs actual behaviour, your Node version, OS, and Codex CLI version.
+- **Feature request:** use the feature template. Describe the use case before the proposed solution.
+- **Question:** use the question template, or join the discussion forum (link TBD once the docs site is live).
+
+## Pull requests
+
+1. Fork the repo, create a branch from `main` (e.g. `feat/something`, `fix/something`).
+2. Make your changes. Keep PRs focused — one logical change per PR.
+3. Run the project's checks locally before pushing:
+   ```
+   pnpm install
+   pnpm typecheck
+   pnpm lint
+   pnpm test
+   ```
+   These commands are wired up starting in Phase 2 (Foundation).
+4. Add a Changeset entry: `pnpm changeset` and follow the prompts.
+5. Open the PR using the [pull request template](.github/PULL_REQUEST_TEMPLATE.md).
+6. CI must pass before review. Maintainers will request changes via review comments.
+
+## Commit conventions
+
+This project follows [Conventional Commits](https://www.conventionalcommits.org/). Examples:
+
+- `feat(cli): add swt status command`
+- `fix(codex-driver): handle empty hooks.json`
+- `docs(readme): clarify install instructions`
+- `chore(deps): bump tsup to 8.x`
+
+The commit type drives Changesets release notes, so please use the right type.
+
+## Originality and licensing of contributions
+
+By submitting a contribution you confirm that:
+
+1. The work is your own, or you have the right to submit it under the project's license.
+2. You agree that your contribution is licensed under the same MIT license as the rest of the project (see [LICENSE](LICENSE)).
+3. You have not copied source code from any third-party project that is not compatibly licensed.
+
+If a contribution is inspired by published documentation, blog posts, or open-source projects, please cite the source in the PR description.
+
+## Development environment
+
+- **Node:** 20.18+ or 22.x.
+- **Package manager:** pnpm (workspaces are used from Phase 2 onward).
+- **Editor:** any. We ship `.vscode/settings.json` recommendations once Phase 2 lands.
+- **OS:** Linux, macOS, and Windows are all supported. Please report platform-specific issues against the bug template.
+
+## Releasing
+
+Maintainer-only. Releases are cut via the Changesets release workflow. See `docs/releasing.md` (added in Phase 9) for the full procedure.
+
+## Getting help
+
+- Open a question issue for project-related questions.
+- For ad-hoc design discussion, the discussion forum is the best venue (link TBD).
+- For private maintainer contact, see [SECURITY.md](SECURITY.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tiago Serôdio (@yidakee) and SWT contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,15 +1,349 @@
-# Stop Wasting Tokens
+# stop-wasting-tokens
 
-Token-efficient AI-assisted development for everyone.
+[![npm](https://img.shields.io/npm/v/stop-wasting-tokens.svg)](https://www.npmjs.com/package/stop-wasting-tokens)
+[![CI](https://github.com/swt-labs/stop-wasting-tokens/actions/workflows/ci.yml/badge.svg)](https://github.com/swt-labs/stop-wasting-tokens/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> A spec-driven harness for the OpenAI Codex CLI, built around a single obsession: **stop wasting tokens**.
+
+`swt` is a Node/TypeScript CLI you install once. It wraps every Codex session in a six-agent software development lifecycle, persistent planning artefacts, and goal-backward verification — so the model never re-discovers what you already specified, never improvises past a documented plan, and never burns turns on work the spec doesn't ask for.
+
+If you've ever watched Codex re-read your codebase three times in one session, hallucinate an architecture you already rejected, or chase a fix in circles because the goal drifted mid-stream — that's the waste this tool is engineered to eliminate.
+
+---
+
+## Table of contents
+
+- [What "saving tokens" actually means](#what-saving-tokens-actually-means)
+- [How SWT works](#how-swt-works)
+- [Prerequisites](#prerequisites)
+- [Install](#install)
+- [Verify the install](#verify-the-install)
+- [Quick start: a real session](#quick-start-a-real-session)
+- [The methodology](#the-methodology)
+- [Configuration](#configuration)
+- [Command reference](#command-reference)
+- [Troubleshooting](#troubleshooting)
+- [Status](#status)
+- [Contributing, security, license](#contributing-security-license)
+
+---
+
+## What "saving tokens" actually means
+
+Token waste in AI coding has five concrete sources. SWT is designed to attack each one:
+
+| Waste source                              | Without SWT                                                             | With SWT                                                                                                               |
+| ----------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Re-reading project context every turn     | Codex re-greps, re-globs, re-reads files it saw 5 minutes ago           | Stable cache-prefix prompts; durable `.swt-planning/` artefacts persist between turns                                  |
+| Re-discovering architecture & decisions   | Each session starts cold, re-derives constraints, re-debates trade-offs | `PROJECT.md`, `REQUIREMENTS.md`, `STATE.md` are read once and stay cached for the whole milestone                      |
+| Improvised approaches that get rejected   | Model proposes, you correct, model re-proposes — three turns gone       | Plans are written by Architect/Lead **before** Dev gets the keys; rejected approaches are recorded in `ASSUMPTIONS.md` |
+| Goal drift mid-execution                  | "While I was at it, I also refactored…" — the dreaded scope explosion   | Goal-backward QA verifies output against the **specified** plan, not against improvised goals                          |
+| Re-running QA from scratch on small fixes | Full validation matrix every time                                       | Three QA tiers (`quick` / `standard` / `deep`) plus a `fix` lane that targets only the failed acceptance criterion     |
+
+Every design decision in SWT — split prompts, pinned model profiles per agent, the phase artefact pipeline, the verification tiers, even the file-locking system — is downstream of "minimize tokens spent per shipped acceptance criterion."
+
+---
+
+## How SWT works
+
+In one sentence: **you write a spec, SWT turns it into a plan, six specialist agents execute the plan, and a verification stage compares output to the spec before anything ships.**
+
+```
+   You write              SWT turns it into        Six agents execute        Output is verified
+   ─────────              ─────────────────        ──────────────────        ─────────────────
+   PROJECT.md             ROADMAP.md (phases)      Scout    → research        QA tier
+   REQUIREMENTS.md        PHASE/PLAN.md (tasks)    Architect → design         Goal-backward
+                                                   Lead     → coordinate      Acceptance criteria
+                                                   Dev      → implement       UAT scenarios
+                                                   QA       → verify
+                                                   Debugger → resolve
+```
+
+Each agent has a fixed model profile and reasoning effort tuned for its role (Scout uses `gpt-5.5/low`, Architect uses `gpt-5.5/high`, Dev uses `gpt-5.3-codex/medium`, etc). You don't think about model selection — the methodology does.
+
+---
+
+## Prerequisites
+
+| Tool                                         | Version      | Why                                              |
+| -------------------------------------------- | ------------ | ------------------------------------------------ |
+| **Node.js**                                  | `>= 20.18`   | Runtime for the `swt` CLI itself                 |
+| **OpenAI Codex CLI**                         | `>= 0.124.0` | The backend SWT orchestrates against             |
+| **Git**                                      | any recent   | Phase commits, milestone tags, the pre-push hook |
+| One of: **npm 10+**, **pnpm 9+**, **bun 1+** | —            | Pick whichever you already use                   |
+
+Optional but recommended:
+
+- **`jq`** — used by some helper scripts; `brew install jq` on macOS, `apt install jq` on Linux.
+- **A terminal with 256-color + Unicode support** — `swt watch` renders an Ink TUI dashboard.
+
+To check Codex is installed and reachable:
+
+```bash
+codex --version
+```
+
+If the Codex CLI isn't installed, follow the OpenAI install guide first — SWT is a methodology layer; it doesn't ship its own model runtime.
+
+---
+
+## Install
+
+Install once, globally:
+
+```bash
+# npm
+npm install -g stop-wasting-tokens
+
+# pnpm
+pnpm add -g stop-wasting-tokens
+
+# bun
+bun add -g stop-wasting-tokens
+```
+
+That's it. The package ships an ESM-only bundle with a single `swt` binary. No build step, no peer-dependency negotiation, no native modules.
+
+### What the package contains
+
+The published tarball is ~1.3 MB compressed and includes:
+
+- `dist/cli.mjs` — the bundled CLI (single file, ~2.1 MB)
+- `dist/cli.d.ts` — TypeScript declarations for programmatic consumers
+- `README.md`, `LICENSE`, `CONTRIBUTING.md`, `SECURITY.md`
+
+Everything reachable from the CLI entry point is bundled in. There are no transitive runtime dependencies installed alongside.
+
+---
+
+## Verify the install
+
+After install, run:
+
+```bash
+swt --version          # should print: swt 1.5.1 (or whatever you installed)
+swt --help             # should list ~30 commands
+swt doctor             # checks: Node version, Codex CLI, jq, git
+```
+
+`swt doctor` is the one-shot environmental check. If anything's missing or out-of-version it tells you exactly what to fix.
+
+---
+
+## Quick start: a real session
+
+This is what a typical first hour with SWT looks like.
+
+### 1. Bootstrap a project (`swt init`)
+
+In an empty directory or an existing repo:
+
+```bash
+swt init
+```
+
+Interactively walks you through:
+
+- Confirming or auto-detecting the tech stack (Node? Python? Rust? Mixed?)
+- Naming the project
+- Capturing 3–5 high-level requirements
+- Choosing your defaults: `effort` (`thorough` / `balanced` / `fast` / `turbo`), `autonomy` (`cautious` / `standard` / `confident` / `pure-vibe`), `verification_tier` (`quick` / `standard` / `deep`)
+
+Result: a populated `.swt-planning/` directory with `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, and a `config.json` capturing your defaults.
+
+### 2. Map an existing codebase (`swt map`, brownfield only)
+
+If you ran `swt init` in an existing repo, follow up with:
+
+```bash
+swt map
+```
+
+This generates `.swt-planning/codebase/` with `STACK.md`, `ARCHITECTURE.md`, `PATTERNS.md`, `CONCERNS.md` — a dense, cache-friendly snapshot of what's already there. Subsequent agent calls read this once and reference it for the whole milestone instead of re-grepping.
+
+### 3. Plan and execute the next phase (`swt vibe`)
+
+```bash
+swt vibe
+```
+
+`vibe` is the orchestrator. It detects what state you're in (no plan? planned but not built? built but not verified? verified but not archived?) and routes you to the right next step. In the common "fresh project" case:
+
+- Spawns **Scout** for ambient research
+- Spawns **Architect** for design decisions
+- Asks you to confirm scope before any code is written
+- Spawns **Lead** to break the phase into atomic tasks
+- Spawns **Dev** to execute each task with one commit per task
+- Spawns **QA** to verify against the goal-backward acceptance criteria
+- Asks you to confirm UAT before declaring the phase complete
+
+You can short-circuit to a specific stage with `swt plan`, `swt execute`, `swt qa`, or `swt vibe --plan=03`.
+
+### 4. Inspect progress at any time
+
+```bash
+swt status               # current phase, milestone, % complete
+swt detect-phase --json  # machine-readable state (used by the statusline / IDE plugins)
+swt watch                # interactive TUI dashboard scoped to the active milestone
+```
+
+### 5. Archive a completed milestone
+
+When all phases in a milestone pass UAT:
+
+```bash
+swt archive
+```
+
+Archives `.swt-planning/phases/*` into `.swt-planning/milestones/<NN>-<slug>/`, runs the 7-point pre-archive audit, generates `RELEASE-NOTES.md`, and tags the commit if `auto_push` is configured.
+
+### 6. Other common entry points
+
+```bash
+swt research "How does feature X interact with Y?"     # Scout-only pass; saves to RESEARCH.md
+swt fix "auth flow rejects valid tokens"               # quick-fix lane for a single failing UAT scenario
+swt debug "the test in foo.spec.ts fails intermittently"  # hypothesis-driven debugging
+swt todo add "investigate caching bug"                 # add a backlog item to STATE.md
+swt update                                             # check npm for a newer version
+```
 
 ---
 
-AI development tools are powerful. They're also expensive, context-hungry, and easy to misuse. Stop Wasting Tokens is built around one principle: every token should move your project forward.
+## The methodology
+
+### The six agents
+
+| Agent         | Model profile   | Reasoning effort | Job                                                    |
+| ------------- | --------------- | ---------------- | ------------------------------------------------------ |
+| **Scout**     | `gpt-5.5`       | `low`            | Ambient research, codebase queries, doc fetches        |
+| **Architect** | `gpt-5.5`       | `high`           | Design decisions, trade-off analysis, scope shaping    |
+| **Lead**      | `gpt-5.3-codex` | `medium`         | Plans phases into atomic tasks; one commit per task    |
+| **Dev**       | `gpt-5.3-codex` | `medium`         | Executes tasks; writes code, tests, docs               |
+| **QA**        | `gpt-5.3-codex` | `medium`         | Goal-backward verification against acceptance criteria |
+| **Debugger**  | `gpt-5.3-codex` | `high`           | Hypothesis-driven root-cause analysis when QA fails    |
+
+You can override profiles per-project in `.swt-planning/config.json`, but the defaults are tuned to balance cost, latency, and quality for typical workloads.
 
-This project is open source and community driven. Whether you're shipping your first project or your fiftieth, you belong here.
+### The phase lifecycle
 
-More coming. Watch this space.
+Every phase goes through five states:
+
+```
+needs_discussion  →  needs_plan_and_execute  →  needs_execute  →  needs_verification  →  archived
+     (optional)              ↑                       ↑                  ↓
+                             └──── if user           └──── if QA        └──── if UAT issues
+                                  rejects scope            fails              found by user
+```
+
+`swt vibe` reads `STATE.md` + on-disk artefacts, computes the current state, and routes to the right command. Manual flags (`--plan`, `--execute`, `--verify`, `--archive`) bypass auto-routing when you want to be explicit.
+
+### The artefact pipeline
+
+```
+.swt-planning/
+├── PROJECT.md              ← what we're building (you write this)
+├── REQUIREMENTS.md         ← validated + active + out-of-scope (you write this)
+├── ROADMAP.md              ← milestones → phases (Architect generates, you approve)
+├── STATE.md                ← current phase, milestone, todos (machine-managed)
+├── config.json             ← effort, autonomy, model profiles (you tune)
+├── codebase/               ← brownfield map (swt map output)
+│   ├── STACK.md
+│   ├── ARCHITECTURE.md
+│   ├── PATTERNS.md
+│   └── CONCERNS.md
+├── phases/
+│   └── 01-{slug}/
+│       ├── ASSUMPTIONS.md  ← discussion outputs
+│       ├── PLAN.md         ← Lead's task breakdown
+│       ├── RESEARCH.md     ← Scout's findings
+│       ├── VERIFICATION.md ← QA's contract verification
+│       └── UAT.md          ← user acceptance scenarios
+└── milestones/             ← archived phases, frozen
+    └── 01-{slug}/
+```
+
+Artefacts are read at the **start** of each agent call as part of the cache-stable prefix. Token cost: paid once per file, amortised across every turn in the milestone.
 
 ---
 
-MIT License ·
+## Configuration
+
+Live config lives in `.swt-planning/config.json` and is editable directly or via `swt config set <key> <value>`.
+
+The knobs that matter most:
+
+| Key                      | Values                                              | Default    | Effect                                                                                                                                        |
+| ------------------------ | --------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `effort`                 | `thorough` / `balanced` / `fast` / `turbo`          | `balanced` | Planning depth and verification thoroughness; also a turn-budget scalar (1.5× → 0.6×) applied to every agent                                  |
+| `autonomy`               | `cautious` / `standard` / `confident` / `pure-vibe` | `standard` | How aggressively `swt vibe` advances without prompts. `cautious` stops every stage; `pure-vibe` auto-loops everything until a hard error      |
+| `verification_tier`      | `quick` / `standard` / `deep`                       | `standard` | What QA runs. `quick` = smoke + lint + types; `standard` = +unit tests + must-have evidence; `deep` = +integration + cross-phase traceability |
+| `model_profile`          | `quality` / `balanced` / `cost`                     | `quality`  | Coarse cost/quality switch applied across all six agents                                                                                      |
+| `backend`                | `codex` / `claude-code` / `ollama`                  | `codex`    | Which CLI runtime SWT orchestrates against (Codex is fully shipped; Claude Code and Ollama drivers land in v1.6+)                             |
+| `prefer_teams`           | `auto` / `always` / `never`                         | `auto`     | Use parallel agent teams (when supported by your Codex CLI version)                                                                           |
+| `auto_uat`               | `true` / `false`                                    | `false`    | When QA passes, auto-route into UAT (`true`) or stop and ask (`false`)                                                                        |
+| `auto_push`              | `never` / `after_phase` / `always`                  | `never`    | When to push commits to `origin`                                                                                                              |
+| `planning_tracking`      | `manual` / `ignore` / `commit`                      | `manual`   | How `.swt-planning/` interacts with git: `manual` (you decide), `ignore` (gitignored), `commit` (auto-commit at planning checkpoints)         |
+| `agent_max_turns.{role}` | int                                                 | varies     | Per-agent turn cap. Defaults: scout 15, qa 25, architect 30, lead 50, dev 75, debugger 80                                                     |
+| `model_overrides.{role}` | string                                              | none       | Override the model for a specific agent (e.g. force the Architect onto a cheaper model for a low-stakes project)                              |
+
+Advanced blocks (not usually edited by hand): `telemetry`, `marketplace`, `hooks`. Run `swt config show` for the full live config.
+
+---
+
+## Command reference
+
+The CLI exposes ~30 commands. The full reference (with examples and flag details) is in [docs.stopwastingtokens.dev](https://docs.stopwastingtokens.dev). Quick index:
+
+**Lifecycle** `init` `vibe` `plan` `execute` `verify` `archive`
+**Quality** `qa` `fix` `debug` `audit`
+**Inspection** `status` `detect-phase` `watch` `whats-new`
+**Backlog** `todo` `phase` `assumptions`
+**Research** `research` `discuss`
+**Workspace** `map` `worktree` `lease` `pause` `resume`
+**Maintenance** `doctor` `config` `skills` `update` `uninstall` `release` `version`
+
+Every command supports `--help`:
+
+```bash
+swt vibe --help
+swt qa --help
+```
+
+---
+
+## Troubleshooting
+
+**`swt: command not found` after install**
+Your global npm bin directory isn't on `PATH`. Run `npm config get prefix` and add `<prefix>/bin` to your shell rc.
+
+**`swt --version` reports `0.0.0` after a manual rebuild**
+You're running a locally-built bundle from before the `CURRENT_VERSION` constant was wired up. Reinstall from npm: `npm install -g stop-wasting-tokens`.
+
+**`swt vibe` keeps asking the same confirmation**
+Your `autonomy` is set to `cautious` or `standard` (the default). Switch with `swt config set autonomy confident` to auto-chain phases, or `pure-vibe` to auto-loop until a hard error.
+
+**Phase detection is in a weird state**
+Run `swt detect-phase` for a JSON dump of what SWT thinks the state is. The `phase_detect_error=true` line points at root cause. As a last resort, `swt pause` saves your in-progress work and lets you restart cleanly.
+
+**Codex CLI says it can't find `~/.codex/config.toml [mcp_servers.swt]`**
+The agent TOMLs reference `~/.codex/config.toml` (the documented Codex MCP path). If you're on an older Codex setup that uses `~/.codex/mcp.json`, upgrade Codex (`>= 0.124.0`).
+
+**Lots of CI failures right after a push**
+Check whether you're using v1.5.0 or earlier — the build pipeline didn't actually compile until v1.5.1. Update with `npm install -g stop-wasting-tokens@latest`.
+
+---
+
+## Status
+
+Currently shipping **v1.5.1**. v1 milestones (1–15) are complete. v1.5 forward-compatibility is in place for additional backend drivers (Claude Code, Ollama) — see [`docs/roadmap/v1.5.md`](docs/roadmap/v1.5.md). v1 itself targets the Codex CLI only.
+
+Per-version changes are tracked in [CHANGELOG.md](CHANGELOG.md). Stable release notes are in [RELEASE-NOTES-v1.0.md](RELEASE-NOTES-v1.0.md).
+
+---
+
+## Contributing, security, license
+
+- Contributions: [CONTRIBUTING.md](CONTRIBUTING.md). Governed by the [Code of Conduct](CODE_OF_CONDUCT.md).
+- Security disclosures: [SECURITY.md](SECURITY.md).
+- License: MIT, see [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,57 @@
+# Security Policy
+
+## Supported versions
+
+`stop-wasting-tokens` is currently in alpha. Only the latest published version on the `main` branch is supported. Pre-release versions (`v0.x.y`) may receive fixes only in the most recent release.
+
+| Version            | Supported |
+| ------------------ | --------- |
+| latest pre-release | Yes       |
+| older pre-releases | No        |
+
+Once the project reaches v1.0, this matrix will be updated to cover at least the current major and the previous major.
+
+## Reporting a vulnerability
+
+Please **do not** open a public GitHub issue for security reports.
+
+Instead, report privately by emailing the maintainer at:
+
+> `security@stopwastingtokens.dev` _(placeholder — to be activated when the domain is registered; until then please use GitHub's private "Report a vulnerability" feature on the repository's Security tab)_
+
+Include:
+
+- A description of the issue and its potential impact.
+- Steps to reproduce, including version numbers, OS, and Codex CLI version.
+- Any proof-of-concept code or commands.
+
+## Response process
+
+1. We will acknowledge receipt within **72 hours**.
+2. We will provide an initial assessment within **7 days**, including whether we accept the report and a tentative timeline.
+3. We will work on a fix and coordinate disclosure with you. Standard target: a fix released within **90 days** of accepted disclosure.
+4. Once a fix is released, we will publish a security advisory on GitHub crediting you (unless you prefer to remain anonymous).
+
+## Scope
+
+In scope:
+
+- The `stop-wasting-tokens` source code in this repository.
+- Published npm artefacts under the project name.
+- Configuration parsing and command-line argument handling.
+
+Out of scope:
+
+- Bugs in the OpenAI Codex CLI itself — please report those upstream.
+- Bugs in third-party dependencies — please report those to their respective projects (we will help with coordination if relevant).
+- Issues that require administrative access to a user's machine to exploit.
+
+## Safe harbour
+
+We will not pursue legal action against researchers who:
+
+- Make a good-faith effort to report vulnerabilities through the channel above.
+- Avoid privacy violations, destruction of data, and interruption or degradation of services.
+- Do not exploit a vulnerability beyond what is necessary to demonstrate it.
+
+Thank you for helping keep `stop-wasting-tokens` and its users safe.

package/dist/cli.d.ts

@@ -0,0 +1,51 @@
+declare const EXIT: {
+    readonly SUCCESS: 0;
+    readonly USAGE_ERROR: 1;
+    readonly NOT_IMPLEMENTED: 2;
+};
+type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+
+interface ParsedArgv {
+    /** First positional argument — the verb (e.g. "config"). */
+    readonly verb: string | undefined;
+    /** Remaining positional arguments after the verb. */
+    readonly positionals: readonly string[];
+    /** Parsed flag values keyed by flag name (without the leading --). */
+    readonly flags: Readonly<Record<string, string | boolean | undefined>>;
+}
+
+interface CommandIO {
+    readonly stdout: NodeJS.WritableStream;
+    readonly stderr: NodeJS.WritableStream;
+    readonly cwd: string;
+}
+type CommandHandler = (parsed: ParsedArgv, io: CommandIO) => Promise<ExitCode> | ExitCode;
+interface CommandSpec {
+    readonly name: string;
+    readonly description: string;
+    readonly handler: CommandHandler;
+    /** Optional usage line shown by `swt help`. */
+    readonly usage?: string;
+}
+declare class CommandRegistry {
+    private readonly commands;
+    register(spec: CommandSpec): this;
+    get(name: string): CommandSpec | undefined;
+    list(): readonly CommandSpec[];
+}
+declare function dispatch(registry: CommandRegistry, parsed: ParsedArgv, io: CommandIO): Promise<ExitCode>;
+
+interface MainDeps {
+    readonly cwd?: string;
+    readonly stdout?: NodeJS.WritableStream;
+    readonly stderr?: NodeJS.WritableStream;
+    readonly version?: string;
+    readonly registry?: CommandRegistry;
+}
+declare function buildRegistry(version?: string): CommandRegistry;
+declare function main(argv?: readonly string[], deps?: MainDeps): Promise<ExitCode>;
+
+declare const PACKAGE_NAME = "@swt-labs/cli";
+declare const VERSION = "0.0.0";
+
+export { type CommandHandler, type CommandIO, CommandRegistry, type CommandSpec, EXIT, PACKAGE_NAME, VERSION, buildRegistry, dispatch, main };