rippletide-package 0.1.0

package/PUBLISHING.md

@@ -0,0 +1,144 @@
+# Publishing
+
+Rippletide is distributed from the repo root as **one npm CLI package**. Every feature is a
+subcommand of the same command:
+
+```bash
+npx rippletide-package <feature-name> [flags]
+```
+
+> Published on npm as **`rippletide-package`** (the name `rippletide` is already taken by
+> another package); the installed command is **`rippletide`**. Via `npx` use the package
+> name; after `npm i -g rippletide-package` you run `rippletide`.
+
+## One product, many features
+
+`rippletide-package` is a multi-feature repo — we expect to iterate on several product bets
+before product-market fit — but it should feel like **one product** to users:
+
+- the publishing unit is the repo root;
+- the npm package name is `rippletide-package`; the installed command is `rippletide`;
+- each user-facing feature is a **subcommand** (`<feature-name>`), implemented in its own
+  self-contained top-level folder;
+- **flags** choose behavior *inside* a feature, e.g. `rippletide <feature-name> --<flag>`;
+- a new feature becomes a subcommand or flag before we ever create another package name.
+
+This keeps experiments cheap without fragmenting the user experience: users learn one
+command, while the repo isolates each product bet in its own folder until a shared contract
+is worth designing. The root CLI ([`bin/rippletide.js`](bin/rippletide.js)) is a small,
+feature-agnostic dispatcher that routes each subcommand to the folder that owns it.
+
+## Adding a feature to the CLI
+
+Build the feature in its own top-level folder:
+
+```text
+<feature>/
+  package.json or build/deploy config, only if the feature needs it
+  src/ (and bin/, docs/, tests/, examples/ as needed)
+```
+
+When it graduates from experiment to a user-facing surface:
+
+1. Keep implementation code in its feature folder (no cross-folder imports).
+2. Add one route for it in `bin/rippletide.js`.
+3. Add its runtime files to the root `package.json` `files` (and any dependency it needs to
+   `dependencies`).
+4. Add root-level verification (extend the `check` script).
+5. Document its command in the root `README.md`.
+
+Do not create a new public npm package for every experiment. Create another package only
+when a feature needs a separate install surface, audience, or lifecycle that would make the
+single `rippletide` CLI worse.
+
+## Package shape
+
+```text
+npm registry : https://registry.npmjs.org/
+repo folder  : ./
+package name : rippletide-package
+command      : rippletide
+```
+
+The published tarball ships the root dispatcher plus each user-facing feature's runtime and
+docs (see `files` in `package.json`). It excludes curated test agents and generated artifacts.
+
+## Local verification
+
+From the repo root:
+
+```bash
+npm run release:check          # syntax-checks every feature + a packaging dry-run
+npm pack                        # build the tarball
+npx ./rippletide-package-0.1.0.tgz --help   # or: ... <feature-name> --help
+```
+
+## Publish
+
+Before the first publish:
+
+1. Confirm the package name is available or owned by Rippletide:
+   ```bash
+   npm view rippletide-package name version   # a 404 means the name is free
+   ```
+2. Confirm npm auth: `npm whoami`.
+3. Confirm the root `package.json` version is what you intend.
+
+Then, from a machine logged in as an owner:
+
+```bash
+npm run release:dry       # dry-run
+npm run release:publish   # publish (prompts for a 2FA OTP if your account requires one)
+```
+
+### Publishing rights: tokens, CI, and teammates
+
+Interactive `npm publish` asks for a 2FA one-time code if your npm account requires 2FA on
+writes. For releases, prefer a **token** — it never prompts for an OTP and isn't tied to one
+person's laptop.
+
+**CI release (recommended).** [`.github/workflows/release.yml`](.github/workflows/release.yml)
+publishes automatically when a `rippletide-package-v*` tag is pushed (or via Actions → *Run
+workflow*). One-time setup:
+
+1. On npmjs.com → **Access Tokens**, create a token with publish rights to this package — a
+   **Granular Access Token** scoped to `rippletide-package` with read+write is safest; a
+   classic **Automation** token also works. Both bypass 2FA.
+2. Store it as the repo secret **`RIPPLETIDE_PACKAGE_TOKEN`** (never commit it):
+   ```bash
+   gh secret set RIPPLETIDE_PACKAGE_TOKEN --repo rippletideco/rippletide-package   # paste the token when prompted
+   ```
+3. Release by pushing a version tag — **any teammate who can push** can do this; no npm login
+   or OTP needed (see the checklist below).
+
+**Manual publish by a teammate.** Have a current owner grant rights, then they publish with
+their own npm account:
+
+```bash
+npm owner add <their-npm-username> rippletide-package   # run by a current owner
+npm owner ls rippletide-package                          # see who can publish
+```
+
+## Repeatable release checklist
+
+From the repo root, every time:
+
+```bash
+git pull --ff-only origin main
+npm version patch --no-git-tag-version      # minor / major when warranted
+npm run release:dry
+VERSION=$(node -p "require('./package.json').version")
+git add package.json
+git commit -m "Release rippletide-package v${VERSION}"
+git tag "rippletide-package-v${VERSION}"
+git push origin main --tags
+npm run release:publish
+```
+
+## Hosted direction (optional, per feature)
+
+The CLI stays the user entry point. A feature may later move its heavy logic behind a hosted
+Rippletide API — the CLI collects and redacts local context, calls the service, and renders
+the result — without changing this release flow. Only that feature's implementation and its
+backend config change. Aim to avoid requiring users to configure model API keys in a
+hosted-first flow.

package/README.md

@@ -0,0 +1,44 @@
+# rippletide-package
+
+Rippletide's product package. It ships as **one npm CLI** — `npx rippletide-package <feature-name>` —
+while each feature lives in its own self-contained top-level folder.
+
+> Published on npm as **`rippletide-package`** (the name `rippletide` is taken); the
+> installed command is **`rippletide`**. So: `npx rippletide-package <feature-name>`, or
+> `npm i -g rippletide-package` then `rippletide <feature-name>`.
+
+**Zero sharing between folders.** Each feature folder is fully self-contained — its own
+code, dependencies, config, and docs. Nothing imports from or reaches into another
+feature's folder. The only place features meet is the root CLI, which routes a subcommand
+to the feature that owns it.
+
+## Features
+
+Each feature is a **subcommand** of `rippletide`, implemented in its own top-level folder.
+**A feature is explained in its own folder** — see that folder's `README.md` (and any
+`PRD.md`/`docs`) for what it does and how to use it.
+
+```bash
+npx rippletide-package <feature-name> [flags]
+```
+
+## How it fits together
+
+One product, one command, many features. The root [`bin/rippletide.js`](bin/rippletide.js)
+is a small, **feature-agnostic dispatcher**: it reads the first argument and hands off to
+the feature folder that owns that subcommand. Behavior *within* a feature is chosen with
+flags (e.g. `rippletide <feature-name> --<flag>`). Runtime code is not shared across feature
+folders until a shared contract is deliberately designed.
+
+## Adding a feature
+
+Repeat this shape for every new feature:
+
+1. Create a top-level folder; keep everything it needs inside it (code, deps, docs, tests)
+   and explain it in that folder's `README.md`.
+2. When it becomes user-facing, add one route in `bin/rippletide.js`, and its runtime files
+   (plus any dependency it needs) to the root `package.json`.
+3. Prefer a subcommand or a flag over a new npm package; create a separate package only if a
+   single command would make the product worse.
+
+Publishing: [`PUBLISHING.md`](PUBLISHING.md).

package/bin/rippletide.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// Rippletide product CLI — the single public entry point (`npx rippletide <feature> …`).
+//
+// The repo is one product with several self-contained feature folders. This dispatcher
+// routes a subcommand to the feature that owns it; it is feature-agnostic — add one route
+// per user-facing feature. See PUBLISHING.md.
+//
+//   rippletide review  [...]   -> reviewer/   (review, inspect, …)
+//   rippletide tide     [...]   -> tide/       (compile, install, check, …)
+//   rippletide counter  [...]   -> counter/    (live Codex calls/tokens/cost window)
+
+const argv = process.argv.slice(2);
+const sub = argv[0];
+
+if (sub === "tide") {
+  const { main } = await import("../tide/src/cli.js");
+  process.exit(await main(argv.slice(1)));
+}
+
+if (sub === "counter") {
+  const { main } = await import("../counter/src/cli.js");
+  process.exit(await main(argv.slice(1)));
+}
+
+// Every other subcommand (review, inspect, --help, …) is owned by the reviewer feature,
+// which reads process.argv itself.
+await import("../reviewer/src/integrations/cli/rippletide.js");

package/counter/README.md

@@ -0,0 +1,37 @@
+# counter — live Codex calls / tokens / cost
+
+A floating **sticky window** that counts your Codex LLM usage in real time: the running
+**call count** (big number), and a caption with **total tokens** and **estimated cost**.
+Ported from the [x-ray](https://github.com/tototozip/x-ray) counter — the counting +
+token/cost half only (no risk scanning, no enforcement).
+
+```bash
+rippletide counter
+```
+
+Then use Codex — the desktop app or the CLI. The window updates on every model call.
+Press **Ctrl-C** (or close the window) to stop; your Codex config is restored on exit.
+
+## How it works
+
+- Points Codex's `openai_base_url` at a tiny local **reverse proxy** (a managed block in
+  `~/.codex/config.toml`, removed on exit).
+- The proxy forwards every model call to OpenAI **untouched**, and on the way back reads the
+  response `usage` to tally tokens and estimate cost from a per-model price table
+  (`gpt-5.x`, etc.). Each inference request bumps the call count.
+- Codex tries a **WebSocket** transport for `/v1/responses` first; the HTTP proxy can't carry
+  that upgrade, so it refuses the handshake (`426`) and Codex falls straight back to its HTTPS
+  transport — which the proxy does forward. This keeps the CLI fast (no reconnect stall) while
+  every call still flows through the counter.
+- A JXA sticky window (`frontend/window.jxa`) renders the live state
+  (`~/.local/state/rippletide/counter.json`): call count, tokens, cost, and a per-model
+  breakdown (click the window for details).
+- On macOS it relaunches the Codex **app** once so it picks up the base URL
+  (disable with `RIPPLETIDE_RELAUNCH_CODEX_APP=0`). The **CLI** picks it up on the next run.
+
+## Notes
+
+- The floating window is **macOS-only** (JXA); counting still runs elsewhere.
+- Nothing is sent anywhere — the proxy only forwards to OpenAI and reads token counts
+  locally. It never changes requests or responses.
+- Cost is an **estimate** from a local price table; treat it as a live gauge, not a bill.