Release v0.3.1: CLI input validation + CI/CD supply chain hardening

Bug-fix release covering issues found in /devex-review and /cso audits.

Fixed:
- selftest reports the canonical VERSION (was hardcoded "0.2.0")
- unknown subcommands now error with did-you-mean instead of silently
  running the default summary
- numeric flags (--days, --top, --port, --interval, --cache-ttl, etc.)
  reject non-positive-integer input via a commander argParser
- whatif --swap validates both sides against the pricing table; closes
  a single-letter prefix loophole
- README commands table now matches `--help` output

Security:
- Pinned all GitHub Actions by commit SHA (actions/checkout,
  actions/setup-node, softprops/action-gh-release) in ci.yml and
  release.yml. Closes a tag-repoint / namespace-takeover risk on the
  release pipeline that handles NPM_TOKEN.
- Added .github/dependabot.yml for weekly github-actions + npm updates
  with grouping, so SHA pins stay fresh automatically.

Tests:
- New test/cli-validation.test.ts (20 cases) locks in every fix above.
  Total 55 tests, <1s runtime.

See CHANGELOG.md for full details.

Author: vnmoorthy

.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+updates:
+  # Keep workflow action SHAs current. Dependabot opens a PR when an upstream
+  # tag's commit changes, so SHA-pinning stays maintainable.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns:
+          - "*"
+
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      dev-dependencies:
+        dependency-type: development
+      prod-dependencies:
+        dependency-type: production

.github/workflows/ci.yml

@@ -14,8 +14,8 @@ jobs:
         os: [ubuntu-latest, macos-latest, windows-latest]
         node: [20, 22]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: ${{ matrix.node }}
           cache: npm

.github/workflows/release.yml

@@ -9,8 +9,8 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: 22
           cache: npm
@@ -21,6 +21,6 @@ jobs:
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
       - name: GitHub release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2
         with:
           generate_release_notes: true

.gitignore

@@ -28,3 +28,7 @@ docs/_frame_*.jpg
 
 # Claude Code working files (in case they ever land here)
 .claude/
+
+python/__pycache__/
+*.pyc
+.gstack/

CHANGELOG.md

@@ -4,6 +4,51 @@ All notable changes to ccmeter will be documented here. Format: [Keep a Changelo
 
 ## [Unreleased]
 
+## [0.3.1] — 2026-04-28
+
+Bug-fix release driven by a `/devex-review` of the CLI surface and a `/cso`
+security audit. No behavior changes for valid inputs; better errors for invalid
+ones; tighter CI/CD supply chain.
+
+### Fixed
+
+- **`ccmeter selftest` reports the wrong version.** `src/cli/commands/selftest.ts:327`
+  hardcoded `"0.2.0"` as a fallback, so `selftest` printed an old version even on
+  fresh installs. Now imports the canonical `VERSION` constant from
+  `src/cli/index.ts`.
+- **Unknown subcommands silently ran `summary`.** Typing `ccmeter dahsboard`
+  produced a default summary instead of an error. Now prints
+  `ccmeter: unknown command 'dahsboard'. Did you mean 'dashboard'?` and exits 1.
+  Levenshtein-based did-you-mean across all 27 commands.
+- **`--days abc` printed `last NaN days`.** No int validation on numeric flags.
+  Added a positive-integer parser (`parsePositiveInt`) on `--days`, `--top`,
+  `--bottom`, `--port`, `--interval`, `--quiet`, `--cache-ttl`, `--max-files`,
+  `--sample-turns`. Bad input now errors via commander before the command runs.
+- **`whatif --swap xyz->abc` returned a confident fake savings number.**
+  `parseSwaps` accepted any token because `pricingFor` falls back to default
+  pricing for unknown models. Now validates both sides of the swap against
+  family aliases (`opus`/`sonnet`/`haiku`) and the built-in pricing table, and
+  rejects single-letter prefixes that previously slipped through.
+- **`README.md` commands table missing rows.** Added `selftest`, `prompts`,
+  `notify`, `reconcile`, `pricing` so the table matches `--help`.
+
+### Security
+
+- **Pinned all GitHub Actions by commit SHA** in `ci.yml` and `release.yml`
+  (`actions/checkout`, `actions/setup-node`, `softprops/action-gh-release`).
+  Prevents a tag-repoint or namespace-takeover attack from injecting code into
+  the release pipeline that handles `NPM_TOKEN`.
+- **Added `.github/dependabot.yml`** for `github-actions` (weekly, grouped) and
+  `npm` (weekly, dev/prod groups). Keeps SHA pins and dependencies fresh
+  automatically.
+
+### Tests
+
+- New `test/cli-validation.test.ts` (20 tests) covers every fix above —
+  selftest version, unknown-command rejection, `--days`/`--top` validators,
+  `whatif --swap` validation including the single-letter loophole. Total now
+  55 tests, still under one second.
+
 ## [0.3.0] — 2026-04-26
 
 Seven new features that knock items off the README roadmap. All in-tree;

README.md

@@ -75,6 +75,7 @@ Don't have Claude Code installed yet but want to see what ccmeter looks like? Tr
 | `ccmeter tools` | per-tool cost breakdown — answers "which subagent ate the budget" |
 | `ccmeter compare` | week-over-week (or any two-period) deltas across all metrics |
 | `ccmeter whatif` | simulate model swaps & cache TTL scenarios on YOUR data |
+| `ccmeter prompts` | rank assistant turns by output-tokens-per-dollar |
 | `ccmeter share` | shareable Markdown stat-card or social SVG (paths redacted) |
 | `ccmeter live` | full-screen ticker — each turn lands as it happens |
 | `ccmeter dashboard` | local web UI on `127.0.0.1:7777` (no network egress) |
@@ -83,10 +84,14 @@ Don't have Claude Code installed yet but want to see what ccmeter looks like? Tr
 | `ccmeter watch` | one-line live tail today's spend (perfect for tmux/PS1) |
 | `ccmeter prompt --budget 10` | one-line, color-coded $ for your shell prompt |
 | `ccmeter metrics` | Prometheus exposition — scrape into Grafana |
+| `ccmeter notify` | desktop notification when projected spend nears your budget |
 | `ccmeter tag <id> <label>` | annotate a session for grouped reporting |
 | `ccmeter budget --set 200` | set & track a monthly budget |
 | `ccmeter digest --webhook URL` | post a weekly digest to Slack/Discord |
 | `ccmeter merge a.json b.json` | combine analyses from multiple machines |
+| `ccmeter pricing` | print the active pricing table (built-in + your overrides) |
+| `ccmeter reconcile` | diff ccmeter's local total vs Anthropic's authoritative usage |
+| `ccmeter selftest` | validate the parser/pricing against your real data |
 | `ccmeter doctor` | diagnose your setup |
 | `ccmeter check-privacy` | exhaustive list of every file ccmeter would read |
 | `ccmeter clear-cache` | drop the parsed cache at `~/.cache/ccmeter` |

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccmeter",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Local-first spend & cache-efficiency dashboard for Claude Code. Reads ~/.claude/projects, tells you exactly what's costing you.",
   "keywords": [
     "claude",

src/cli/commands/selftest.ts

@@ -28,6 +28,7 @@ import { costForTurn } from "../../core/pricing/compute.js";
 import { turnHasUsage, turnTimestampMs, turnModel } from "../../core/jsonl/schema.js";
 import { redactPath } from "../../core/privacy.js";
 import { getPricingVerifiedDate } from "../../core/pricing/models.js";
+import { VERSION } from "../index.js";
 import pc from "picocolors";
 
 const { bold, dim, green, red, yellow, cyan } = pc;
@@ -322,9 +323,7 @@ export async function runSelftest(opts: SelftestOpts): Promise<void> {
 }
 
 function pkgVersion(): string {
-  // Avoid a hard import of package.json (which causes ESM resolution
-  // headaches under different bundlers); fall back to a constant.
-  return process.env.CCMETER_VERSION ?? "0.2.0";
+  return process.env.CCMETER_VERSION ?? VERSION;
 }
 
 function redactBasename(p: string): string {

src/cli/commands/whatif.ts

@@ -7,13 +7,13 @@
 
 import pc from "picocolors";
 import { analyze } from "../../core/analyze.js";
-import { pricingFor } from "../../core/pricing/models.js";
+import { pricingFor, listModels } from "../../core/pricing/models.js";
 import { bold, divider, fmtUSD } from "../ui/format.js";
 
 interface WhatIfOpts {
-  days?: string;
+  days?: number | string;
   swap?: string[];
-  cacheTtl?: string;
+  cacheTtl?: number | string;
   disableCache?: boolean;
 }
 
@@ -25,13 +25,16 @@ const FAMILY_TARGETS: Record<string, string> = {
 
 export async function runWhatIf(opts: WhatIfOpts): Promise<void> {
   const days = parseInt(String(opts.days ?? 30), 10);
+
+  // parseSwaps throws on malformed input; main()'s top-level catch in
+  // src/cli/index.ts prints the message in red and exits 1.
+  const swaps = parseSwaps(opts.swap ?? []);
+
   const a = await analyze({ days });
   const w = process.stdout.columns ? Math.min(process.stdout.columns, 88) : 80;
 
   process.stdout.write(`\n${bold(`What-if simulation — last ${days} days`)}\n${divider(w)}\n`);
   process.stdout.write(`Actual spend: ${bold(fmtUSD(a.totals.totalCost))}\n\n`);
-
-  const swaps = parseSwaps(opts.swap ?? []);
   let simulatedTotal = 0;
   for (const s of a.sessions) {
     const targetModel = pickTarget(s.primaryModel, swaps) ?? s.primaryModel;
@@ -57,12 +60,13 @@ export async function runWhatIf(opts: WhatIfOpts): Promise<void> {
   if (opts.disableCache) {
     process.stdout.write(`  • cache disabled (every read becomes full input)\n`);
   }
-  if (opts.cacheTtl && opts.cacheTtl !== "300") {
+  const ttlSec = opts.cacheTtl != null ? Number(opts.cacheTtl) : 300;
+  if (ttlSec !== 300) {
     process.stdout.write(
-      `  • cache TTL: ${opts.cacheTtl}s (would re-bucket busts; needs phase-2 work)\n`,
+      `  • cache TTL: ${ttlSec}s (would re-bucket busts; needs phase-2 work)\n`,
     );
   }
-  if (swaps.length === 0 && !opts.disableCache && (!opts.cacheTtl || opts.cacheTtl === "300")) {
+  if (swaps.length === 0 && !opts.disableCache && ttlSec === 300) {
     process.stdout.write(pc.dim(`  • no scenario flags set — try --swap opus->sonnet\n`));
   }
   process.stdout.write("\n");
@@ -89,11 +93,44 @@ interface Swap {
   to: string;
 }
 
-function parseSwaps(raw: string[]): Swap[] {
+export function parseSwaps(raw: string[]): Swap[] {
+  const knownModels = new Set(listModels().map((m) => m.id));
+  const knownFamilies = new Set(Object.keys(FAMILY_TARGETS));
+  const isValid = (token: string): boolean => {
+    if (!token) return false;
+    if (knownFamilies.has(token)) return true;
+    if (knownModels.has(token)) return true;
+    // Accept partial / dated suffixes that prefix-match a known model id
+    // (mirrors pricingFor's lenient resolution). Require at least one hyphen
+    // in the token so single-letter prefixes like "c" don't sneak through.
+    if (!token.includes("-")) return false;
+    for (const id of knownModels) if (token.startsWith(id) || id.startsWith(token)) return true;
+    return false;
+  };
+
   const out: Swap[] = [];
   for (const r of raw) {
+    if (!r.includes("->")) {
+      throw new Error(
+        `--swap expects 'from->to' (got "${r}"). Example: --swap opus->sonnet.`,
+      );
+    }
     const [from, to] = r.split("->").map((s) => s.trim().toLowerCase());
-    if (!from || !to) continue;
+    if (!from || !to) {
+      throw new Error(
+        `--swap expects 'from->to' (got "${r}"). Example: --swap opus->sonnet.`,
+      );
+    }
+    if (!isValid(from)) {
+      throw new Error(
+        `--swap: unknown model '${from}'. Use one of: ${[...knownFamilies].join(", ")} (or run 'ccmeter pricing' for full ids).`,
+      );
+    }
+    if (!isValid(to)) {
+      throw new Error(
+        `--swap: unknown model '${to}'. Use one of: ${[...knownFamilies].join(", ")} (or run 'ccmeter pricing' for full ids).`,
+      );
+    }
     out.push({ from, to });
   }
   return out;