rippletide-package 0.1.1 → 0.2.0

package/PUBLISHING.md

@@ -7,9 +7,9 @@ subcommand of the same command:
 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`.
+> Published on npm as **`rippletide-package`**, and the installed command is also
+> **`rippletide-package`**. Via `npx`: `npx rippletide-package …`; after
+> `npm i -g rippletide-package` you run `rippletide-package …`.
 
 ## One product, many features
 
@@ -17,10 +17,10 @@ npx rippletide-package <feature-name> [flags]
 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`;
+- the npm package name and the installed command are both `rippletide-package`;
 - 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>`;
+- **flags** choose behavior *inside* a feature, e.g. `rippletide-package <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
@@ -49,7 +49,7 @@ When it graduates from experiment to a user-facing surface:
 
 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.
+single `rippletide-package` CLI worse.
 
 ## Package shape
 
@@ -57,7 +57,7 @@ single `rippletide` CLI worse.
 npm registry : https://registry.npmjs.org/
 repo folder  : ./
 package name : rippletide-package
-command      : rippletide
+command      : rippletide-package
 ```
 
 The published tarball ships the root dispatcher plus each user-facing feature's runtime and
@@ -91,28 +91,40 @@ 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
+### Publishing rights: CI (OIDC) 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.
+Releases go through CI using npm **Trusted Publishing (OIDC)** — no token and no 2FA. This is
+the recommended path and the reason it's used here: on this account 2FA is required to publish,
+and **npm access tokens do not bypass 2FA** (only classic Automation tokens do, and the npm UI
+now only offers granular tokens, which get `EOTP` in CI). OIDC sidesteps all of that: GitHub's
+workflow identity is the credential, verified cryptographically per run.
 
 **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:
+workflow*). The job has `permissions: id-token: write`, upgrades npm to a version that supports
+OIDC, and runs `npm publish` — no secret is involved. One-time setup (already done for this
+package):
 
-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).
+1. On npmjs.com → the **rippletide-package** package → **Settings** → **Trusted Publisher** →
+   *GitHub Actions*, with organization `rippletideco`, repository `rippletide-package`, and
+   workflow file `release.yml` (leave *Environment* blank). Allow the `npm publish` action.
+2. That's it. Release by pushing a version tag — **any teammate who can push** can cut a
+   release; no npm login, token, or OTP (see the checklist below). (Signed build provenance
+   is not enabled: npm provenance requires a public source repo, and this repo is internal.)
+
+**First publish caveat.** Trusted publishing (and provenance) can only be configured on a
+package that already exists, so the *very first* publish of a brand-new package name must be
+done manually (below), after which OIDC handles every subsequent release.
+
+**Manual publish (first publish, or a one-off).** With a passkey/WebAuthn 2FA method, npm can
+only complete the 2FA challenge in a browser, and it only offers that when it has a real
+terminal. So run it in an interactive terminal (not a script/CI context):
 
-**Manual publish by a teammate.** Have a current owner grant rights, then they publish with
-their own npm account:
+```bash
+npm publish            # prints "Authenticate your account at: <url>" — approve with Touch ID
+```
+
+To let a teammate publish manually, a current owner grants them rights:
 
 ```bash
 npm owner add <their-npm-username> rippletide-package   # run by a current owner
@@ -131,10 +143,12 @@ 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
+git push origin main --tags   # pushing the tag triggers CI, which publishes via OIDC
 ```
 
+Pushing the `rippletide-package-v*` tag is the whole release — the
+[release workflow](.github/workflows/release.yml) publishes it. No local `npm publish` needed.
+
 ## Hosted direction (optional, per feature)
 
 The CLI stays the user entry point. A feature may later move its heavy logic behind a hosted

package/README.md

@@ -3,9 +3,9 @@
 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>`.
+> Published on npm as **`rippletide-package`**, and the installed command is also
+> **`rippletide-package`**. So: `npx rippletide-package <feature-name>`, or
+> `npm i -g rippletide-package` then `rippletide-package <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
@@ -14,7 +14,7 @@ to the feature that owns it.
 
 ## Features
 
-Each feature is a **subcommand** of `rippletide`, implemented in its own top-level folder.
+Each feature is a **subcommand** of `rippletide-package`, 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.
 
@@ -27,7 +27,7 @@ npx rippletide-package <feature-name> [flags]
 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
+flags (e.g. `rippletide-package <feature-name> --<flag>`). Runtime code is not shared across feature
 folders until a shared contract is deliberately designed.
 
 ## Adding a feature

package/bin/rippletide.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
-// Rippletide product CLI — the single public entry point (`npx rippletide <feature> …`).
+// Rippletide product CLI — the single public entry point (`npx rippletide-package <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)
+//   rippletide-package review   [...]   -> reviewer/   (review, inspect, …)
+//   rippletide-package tide     [...]   -> tide/       (compile, install, check, …)
+//   rippletide-package counter  [...]   -> counter/    (live Codex calls/tokens/cost window)
 
 const argv = process.argv.slice(2);
 const sub = argv[0];
@@ -22,6 +22,13 @@ if (sub === "counter") {
   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");
+// Every other subcommand (review, inspect, --help, …) is owned by the reviewer feature.
+// Its main() reads process.argv itself (command = argv[2]); call it explicitly here — the
+// module's own run-as-main guard doesn't fire when imported through this dispatcher.
+const { main } = await import("../reviewer/src/integrations/cli/rippletide.js");
+try {
+  await main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/counter/README.md

@@ -6,7 +6,7 @@ Ported from the [x-ray](https://github.com/tototozip/x-ray) counter — the coun
 token/cost half only (no risk scanning, no enforcement).
 
 ```bash
-rippletide counter
+rippletide-package counter
 ```
 
 Then use Codex — the desktop app or the CLI. The window updates on every model call.

package/counter/src/cli.js

@@ -1,11 +1,11 @@
-// The `counter` feature entry point — `rippletide counter`.
+// The `counter` feature entry point — `rippletide-package counter`.
 // Starts the Codex live counter: a floating sticky window that tallies LLM calls, tokens,
 // and estimated cost in real time. macOS for the window; counting works anywhere.
 import { run } from "./counter.js";
 
 const HELP = `counter — a live Codex sticky window: LLM calls, tokens, and estimated cost.
 
-Usage: rippletide counter
+Usage: rippletide-package counter
 
 Run it, then use Codex (the desktop app or the CLI). A floating window shows the running
 call count, total tokens, and estimated USD cost. It points Codex's openai_base_url at a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rippletide-package",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "private": false,
   "description": "Rippletide's CLI for AI coding agents — one command, each feature a subcommand.",
   "keywords": [
@@ -19,7 +19,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "bin": {
-    "rippletide": "bin/rippletide.js"
+    "rippletide-package": "bin/rippletide.js"
   },
   "files": [
     "bin/",

package/reviewer/README.md

@@ -24,7 +24,7 @@ RIPPLETIDE_MODEL=gpt-5.5
 Run a review with npx:
 
 ```bash
-npx rippletide review
+npx rippletide-package review
 ```
 
 The command reviews the current directory by default.
@@ -32,10 +32,10 @@ The command reviews the current directory by default.
 Explicit path:
 
 ```bash
-npx rippletide review /path/to/agent
+npx rippletide-package review /path/to/agent
 ```
 
-Current local reviewer mode requires `OPENAI_API_KEY`. The product direction is hosted-first, so the final `npx rippletide review` flow will use the Rippletide hosted reviewer instead of asking users to configure model keys.
+Current local reviewer mode requires `OPENAI_API_KEY`. The product direction is hosted-first, so the final `npx rippletide-package review` flow will use the Rippletide hosted reviewer instead of asking users to configure model keys.
 
 Run a review from a local checkout:
 

package/reviewer/src/integrations/cli/rippletide.js

@@ -290,17 +290,17 @@ function usage() {
   return `Rippletide Reviewer
 
 Usage:
-  rippletide review [path] [--evidence-budget 140000] [--fix]
-  rippletide inspect [path] [--evidence-budget 140000]
+  rippletide-package review [path] [--evidence-budget 140000] [--fix]
+  rippletide-package inspect [path] [--evidence-budget 140000]
   npm run inspect -- [path]
   npm run review -- [path]
 
 Example:
-  npx rippletide review
-  npx rippletide review ../my-agent
-  rippletide review ../my-agent
-  rippletide review ../my-agent --fix
-  rippletide inspect ../my-agent
+  npx rippletide-package review
+  npx rippletide-package review ../my-agent
+  rippletide-package review ../my-agent
+  rippletide-package review ../my-agent --fix
+  rippletide-package inspect ../my-agent
 
 Interactive fix mode:
   --fix shows a short findings menu first, then proposes an action for the finding you choose.

package/tide/README.md

@@ -5,7 +5,7 @@
 
 ## What it is
 
-Write your guardrails in plain English in a `POLICY.md`. `rippletide --tide` compiles
+Write your guardrails in plain English in a `POLICY.md`. `rippletide-package --tide` compiles
 that policy — **once**, with an LLM — into deterministic, reviewable rules, and then
 **enforces them at the agent's tool-call boundary at runtime** (no LLM in the hot path).
 
@@ -71,9 +71,9 @@ one interface, so switching later is a contained change.
 
 ## Usage (v1 — Codex)
 
-Node package (unified with the `rippletide` npm CLI). Locally: `cd tide && npm install`,
+Node package (unified with the `rippletide-package` npm CLI). Locally: `cd tide && npm install`,
 then use `node bin/tide.js <cmd>` (or the `tide` bin). Wired into the parent it's
-`rippletide tide <cmd>`.
+`rippletide-package tide <cmd>`.
 
 ```bash
 tide compile --policy POLICY.md --project .tide   # POLICY.md -> rules (LLM) + golden tests
@@ -111,7 +111,7 @@ local and needs no credentials.
 - **v1 shipped — Codex (Node):** compile (your key, model auto-matched) → deterministic
   engine → PreToolUse hook. Verified end-to-end against real `codex` instances:
   file-modifying commands **and** `apply_patch` edits are blocked; reads run; unit +
-  golden + e2e tests pass. Implemented in Node/ESM (`src/`) to unify with the `rippletide`
+  golden + e2e tests pass. Implemented in Node/ESM (`src/`) to unify with the `rippletide-package`
   npm package — one dependency (`js-yaml`).
 - **Placeholders:** Claude Code / OpenCode / Pi adapters are stubbed with their target seam
   (see [`PRD.md`](PRD.md) §8). **Escalate** currently holds by blocking-with-reason (a live

package/tide/bin/tide.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-// Tide CLI entry. Also the `--tide` feature entry point for the parent rippletide package.
+// Tide CLI entry. Also the tide feature entry point for the parent rippletide-package CLI.
 import { main } from "../src/cli.js";
 process.exit(await main(process.argv.slice(2)));

package/tide/src/cli.js

@@ -1,6 +1,6 @@
-// The `tide` CLI — and the `--tide` feature entry point for the parent rippletide package.
+// The `tide` CLI — and the tide feature entry point for the parent rippletide-package CLI.
 //   tide compile | test | check | install | uninstall | status
-// The parent wires `rippletide --tide <args>` to `main(args)`.
+// The parent wires `rippletide-package tide <args>` to `main(args)`.
 
 import fs from "node:fs";
 import path from "node:path";