cc-cream 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -6,6 +6,24 @@ All notable changes to cc-cream are documented here. Format follows
 
 ## [Unreleased]
 
+## [0.3.3] — 2026-05-30
+
+### Changed
+- **The post-publish `npx` smoke test now uses `--safe-chain-skip-minimum-package-age`** so the `@manual` "npm indexing" scenario works immediately after a release without waiting for the package-age guard to lift (CREAM-elrbkfot).
+- **TTL segment now displays minutes only** (`ttl:60`, `ttl:8`, `ttl:0`) instead of the previous `HH:MM` format (`ttl:01:00`). Simpler to read at a glance; matches the 60-second refresh cadence (CREAM-vhhdhydn).
+
+### Documentation
+- **The `cache` segment's `drop` / `drop_recover` config keys are now documented.** They've been live since cache drop-detection shipped but never appeared in the README — the segment catalog listed `cache` as "neutral" with no mention that it turns red on a sharp hit-rate drop, nor that the trip/recover thresholds are configurable. Added a "`cache` drop detection" subsection, surfaced the keys in the example config, and corrected the catalog color note. This is the documentation outcome of CREAM-wwsdavum (configure-via-`/cc-cream:` command), which is otherwise declined as a dup of the deliberately-closed CREAM-udibxkch.
+
+## [0.3.2] — 2026-05-30
+
+### Fixed
+- **`npm run coverage` (and the pre-push hook) no longer crash on Node ≥ 26.** `c8@11` does `require('yargs/yargs')`, and yargs 17's `exports` map resolves that to an **extensionless** CJS file; under Node 26's `require(ESM)` loader an extensionless file in a `"type": "module"` package is parsed as ESM, throwing `ReferenceError: require is not defined in ES module scope`. This broke the `simple-git-hooks` pre-push gate, forcing `SKIP_SIMPLE_GIT_HOOKS=1` on every push. Pinned yargs to `^18.0.0` via `overrides` — its `./yargs` export is a proper `.mjs` that Node 26 loads cleanly, and `c8@11` works against it unchanged (all 248 scenarios green under coverage). Dev-only; no runtime-dependency or published-package impact.
+- **The uninstall receipt's cache-path escape hatch is now copy-pasteable.** It printed `…/cc-cream/cc-cream/<version>/src/install.js`, but the receipt reaches the user through the `/cc-cream:uninstall` slash command, whose output Claude Code renders as **markdown — which strips `<version>` as an HTML-like tag**. The user saw `cc-cream//src` (empty version) and pasting it failed with `MODULE_NOT_FOUND`, breaking the documented npm-free recovery path exactly when it's needed. The receipt now prints install.js's own resolved absolute path — via the slash command that's the real versioned cache copy — so it's both version-accurate and free of any stripped placeholder. The README uses a markdown-safe `VERSION` placeholder with an `ls` hint to read off the real one (CREAM-rhtrzwss).
+
+### Internal
+- **Internal spec/working docs and the fp-managed `FP_CLAUDE.md` are no longer tracked in git.** `docs/` (PRD, release plan, code-review notes, install-lifecycle notes) and `FP_CLAUDE.md` are local working references, now gitignored and removed from the repo to keep the public tree focused on shipped code. No effect on the published npm package — its `files` allowlist (`src/`, `LICENSE`, `README.md`, `CHANGELOG.md`) never included them.
+
 ## [0.3.1] — 2026-05-30
 
 ### Fixed

package/README.md

@@ -151,14 +151,17 @@ message — restart an already-open session to drop it immediately.
 > `statusLine` line still lingers in `settings.json`.
 >
 > To clear that leftover line once the plugin is gone, the **guaranteed** route is
-> the copy of the uninstaller still in the cache — npm-free and always present:
+> the copy of the uninstaller still in the cache — npm-free and always present.
+> `VERSION` is the single directory under that path (run the `ls` first to read it
+> off); `/cc-cream:uninstall` also prints the fully-resolved command:
 > ```bash
-> node ~/.claude/plugins/cache/cc-cream/cc-cream/<version>/src/install.js --uninstall
+> ls ~/.claude/plugins/cache/cc-cream/cc-cream/        # e.g. 0.3.1
+> node ~/.claude/plugins/cache/cc-cream/cc-cream/VERSION/src/install.js --uninstall
 > # add --purge to also remove your config
 > ```
 > The npm bin does the same job, but **not always**: a *freshly published* version
-> is blocked by npm's min-package-age safe-chain guard (it reports "command not
-> found") until it ages in, so use it only if the cache route isn't handy:
+> is blocked by npm's min-package-age safe-chain guard (it reports "No versions
+> available") until it ages in, so use it only if the cache route isn't handy:
 > ```bash
 > npx -y -p cc-cream cc-cream-setup --uninstall
 > ```
@@ -207,7 +210,7 @@ cc-cream-setup --check-config   # reports unknown keys / out-of-domain values; e
   "percentage": "consumed",
   "segments": {
     "ctx":          { "on": true,  "row": 1, "order": 2, "amber": 30, "orange": 40, "red": 50, "basis": "window", "ceiling": 200000, "display": "basis" },
-    "cache":        { "on": true,  "row": 1, "order": 3 },
+    "cache":        { "on": true,  "row": 1, "order": 3, "drop": 20, "drop_recover": 80 },
     "write":        { "on": false, "row": 1, "order": 3.5 },
     "ttl":          { "on": true,  "row": 1, "order": 4, "amber": 50, "red": 80 },
     "cost":         { "on": true,  "row": 1, "order": 5 },
@@ -251,7 +254,7 @@ Colored segments additionally accept threshold keys. Thresholds mark the
 | Segment | Default | Example | Meaning | Color |
 |---|---|---|---|---|
 | `ctx` | on, row 1 | `ctx:19% [38k]` | context-window occupancy + input-token magnitude | `<30` green · `30–40` amber · `40–50` orange · `≥50` red |
-| `cache` | on, row 1 | `cache:95%` | last-turn cache hit rate (reads / total tokens) | neutral |
+| `cache` | on, row 1 | `cache:95%` | last-turn cache hit rate (reads / total tokens) | neutral; **red** on a sharp drop (see below) |
 | `write` | **off**, row 1 | `write:4%` | last-turn cache creation rate (new writes / total tokens) | neutral |
 | `ttl` | on, row 1 | `ttl:00:52` | time remaining before cache expires (counts down to 00:00) | `<50%` green · `50–80%` amber · `≥80%` red |
 | `cost` | on, row 1 | `~$4.50` | session cost incl. subagents; `~` = CC's estimate | neutral; hidden when zero |
@@ -298,6 +301,18 @@ default row via config must land in a zone to appear on row 1.
 
 Default: `amber: 30`, `orange: 40`, `red: 50` (percent consumed).
 
+### `cache` drop detection
+
+The `cache` segment stays neutral while the hit rate is healthy, but turns **red**
+when it falls sharply from one turn to the next — a cue that the prompt cache was
+just invalidated (e.g. an edit far back in context forced a re-read). This relies
+on per-session state, so it only fires when `session_id` is present in stdin.
+
+- `drop`: percentage-point fall from the previous turn that trips red. Default `20`
+  (95% → 74% trips; 95% → 80% does not).
+- `drop_recover`: once tripped, the segment stays red until the hit rate climbs
+  back to at least this value. Default `80`.
+
 ### `ttl` thresholds
 
 Default: `amber: 50`, `red: 80` (percent of the resolved TTL consumed).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-cream",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Claude Code cache/context/cost status-line tool",
   "directories": {
     "doc": "docs"
@@ -60,5 +60,8 @@
     "c8": "^11.0.0",
     "knip": "^6.14.2",
     "simple-git-hooks": "^2.13.1"
+  },
+  "overrides": {
+    "yargs": "^18.0.0"
   }
 }

package/src/install.js

@@ -21,6 +21,12 @@ import { isEntrypoint } from './utils.js';
 
 export { writeFileAtomic } from './settings.js';
 
+// Absolute path of THIS install.js. When the /cc-cream:uninstall slash command
+// runs it, that's the versioned plugin-cache copy — the durable, npm-free
+// escape hatch we advertise in the uninstall receipt (resolved, not guessed, so
+// it carries the real version and no markdown-stripped placeholder).
+const SELF_PATH = fileURLToPath(import.meta.url);
+
 const TRUST_NOTE =
   'The bar appears on your next message — restart only an already-open session, and the workspace must be trusted.';
 
@@ -255,18 +261,32 @@ async function uninstall({ purge }) {
   printUninstallReceipt();
 }
 
+// Shorten an absolute path under $HOME to a `~/…` form for display. The shell
+// still expands `~`, so the result stays copy-pasteable.
+function tildeify(p) {
+  const home = os.homedir();
+  return p === home || p.startsWith(`${home}/`) ? `~${p.slice(home.length)}` : p;
+}
+
 // The closing receipt. No Claude Code host removal path drops our statusLine OR
 // the version cache, so spell out what's gone, what the host leaves behind, and
 // the npm-free escape hatch (the lingering cache always has a working install.js).
 // See project memory cc-cream-plugin-lifecycle-findings.
+//
+// The escape-hatch line prints SELF_PATH — this install.js's real, resolved
+// location — NOT a `<version>` placeholder. The receipt reaches the user through
+// the slash command, whose output Claude Code renders as markdown; `<version>`
+// was silently stripped to an empty segment (cc-cream//src), breaking copy-paste
+// exactly when it's needed (CREAM-rhtrzwss). Via the slash command SELF_PATH IS
+// the versioned cache copy, so the path is both accurate and markdown-safe.
 function printUninstallReceipt() {
   console.log('\nDone — the bar disappears on your next message (restart an already-open session to drop it now).');
   console.log('The host leaves the rest behind; to fully remove cc-cream:');
   console.log('  • Plugin: /plugin uninstall cc-cream  then  /plugin marketplace remove cc-cream');
   console.log('  • Version cache (never auto-removed): rm -rf ~/.claude/plugins/cache/cc-cream');
   console.log('  • The /cc-cream:* slash commands linger in this session until you restart Claude Code.');
-  console.log('Already removed the plugin? This same uninstall lives in the cache:');
-  console.log('  node ~/.claude/plugins/cache/cc-cream/cc-cream/<version>/src/install.js --uninstall [--purge]');
+  console.log('Re-run this uninstall later (e.g. the plugin is gone but the bar lingers) — it lives at:');
+  console.log(`  node ${tildeify(SELF_PATH)} --uninstall [--purge]`);
 }
 
 // `cc-cream-setup --check-config`: lint ~/.claude/cc-cream.json against the

package/src/segments.js

@@ -63,7 +63,7 @@ function segTtl(cfg, ttlMin, now, anchorMs) {
   if (!isNum(anchorMs)) return null;
   const elapsedMin = Math.floor(Math.max(0, now - anchorMs) / 60000);
   const remainingMin = Math.max(0, ttlMin - elapsedMin);
-  const text = `ttl:${pad2(Math.floor(remainingMin / 60))}:${pad2(remainingMin % 60)}`;
+  const text = `ttl:${remainingMin}`;
   const s = cfg.segments.ttl;
   const pctTtl = ttlMin > 0 ? (elapsedMin / ttlMin) * 100 : 0;
   return { text, color: band(pctTtl, s.amber, s.red) };