cc-cream 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to cc-cream are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.3.0] — 2026-05-30
+
+### Added
+- **`cc-cream-setup --status` — a read-only footprint report.** Because no Claude Code host removal path drops our `statusLine` or garbage-collects the version cache, users couldn't easily tell whether cc-cream had fully gone away. `--status` reports the whole footprint in one shot: the `statusLine` wiring (flagging a stale/ghost line whose entrypoint is missing), every cached plugin version, the marketplace clone + both registrations, the auto-wire marker, session state, config, and the manual runtime copy — with a "clean slate" verdict when nothing remains and removal guidance when something does (CREAM-zgdcbmfj).
+
+### Fixed
+- **The status bar no longer zombies after the plugin is uninstalled.** No Claude Code host removal path deletes our `statusLine` *or* the version cache: `/plugin uninstall` is partial (it deregisters the plugin but leaves the cache tree and our `statusLine`), so the entrypoint still exists and the `[ -f … ] || exit 0` guard can never fire — the bar kept rendering every session, with no in-product way out (`/cc-cream:uninstall` deregisters with the plugin). The renderer now defends itself: when it detects it's running **from the plugin cache** while cc-cream is **absent from `~/.claude/plugins/installed_plugins.json`**, it exits 0 silently. The check costs one tiny read and runs *only* on the plugin-cache path — manual/npm installs skip it entirely. A corrupt/unreadable registry is treated as "still installed" so a transient glitch can't suppress a live bar (CREAM-uchemxln).
+- **Non-interactive `--force` no longer prints a contradictory "Declined … then replaced" receipt.** The installer's consent path printed the detection-only first plan pass — including a speculative "Declined — your existing statusLine is unchanged." — and then replaced the line anyway. It now resolves consent first and prints a single coherent result (CREAM-hpjebzes).
+
+### Changed
+- **Setup/uninstall copy now matches how the bar actually appears.** The status line shows on the **next message** of a new session — no restart needed; a restart only matters for an already-open session. The installer note, the `SessionStart` hook message, and the uninstall receipt were reworded accordingly (dropping the misleading "Restart Claude Code" framing) (CREAM-wvtiftfw).
+- **`/cc-cream:uninstall` is now self-sufficient.** It auto-cleans the regenerable scratch (the copied runtime and `cc-cream-state.json`) with no prompt — the old interactive artifact prompt was dead code, since both the `!` bang runner and the slash commands run without a TTY. `--purge` additionally removes the user-authored `~/.claude/cc-cream.json`, and `commands/uninstall.md` now forwards `$ARGUMENTS` so `/cc-cream:uninstall --purge` actually reaches the script. The closing receipt enumerates the final state and the leftovers the host *doesn't* clean — the version cache (`rm -rf ~/.claude/plugins/cache/cc-cream`), `/plugin marketplace remove`, the slash commands that linger until restart, and the npm-free cache-path escape hatch (CREAM-lznfgrap, CREAM-wvtiftfw).
+
+### Internal
+- **One-command releases (`npm run release <patch|minor|major>`).** A new `scripts/release.mjs` bumps every version location in lockstep — `package.json`, `package-lock.json`, and `.claude-plugin/plugin.json` — and rolls the CHANGELOG's `[Unreleased]` section into a dated `## [x.y.z]` heading, gates on the test suite, then commits + tags (and pushes + creates the GitHub Release with `--publish`). It removes the hand-syncing every prior release required, where `npm version` touched only the first two and the version-match gate punished the drift. A new CI gate (`features/25`) now also asserts `plugin.json`'s version matches `package.json`, so that manifest can no longer go stale.
+
 ## [0.2.0] — 2026-05-30
 
 ### Added

package/README.md

@@ -136,36 +136,56 @@ Plugin users — two steps, **in this order** (Claude Code can't clean
 from the cache):
 ```
 /cc-cream:uninstall          # 1. removes the statusLine wiring (run this FIRST)
-/plugin uninstall cc-cream   # 2. drops the plugin from the cache
+/plugin uninstall cc-cream   # 2. drops the plugin
 ```
-
-> **Order matters.** `/cc-cream:uninstall` lives inside the plugin, so once you
-> run `/plugin uninstall` it's gone. The status line itself degrades to nothing
-> if the cache is missing (it won't error), but the now-inert `statusLine` block
-> lingers in `settings.json`. To clear it after the plugin is already gone, run
-> the npm bin (no global install needed):
+`/cc-cream:uninstall` also auto-cleans cc-cream's regenerable scratch (the copied
+runtime and session-state file); add `--purge` (`/cc-cream:uninstall --purge`) to
+also delete your `~/.claude/cc-cream.json` config. The bar disappears on your next
+message — restart an already-open session to drop it immediately.
+
+> **Order matters — but you're covered if you get it wrong.** `/cc-cream:uninstall`
+> lives inside the plugin, so once you run `/plugin uninstall` it's gone. Neither
+> host command clears the `statusLine` block *or* the version cache. The renderer
+> notices when it's running from a cache the host no longer lists as installed and
+> **self-suppresses**, so the bar stops on the next session even though the inert
+> `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:
+> ```bash
+> 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:
 > ```bash
 > npx -y -p cc-cream cc-cream-setup --uninstall
 > ```
-> or remove the `statusLine` key from `~/.claude/settings.json` by hand.
+> You can always remove the `statusLine` key from `~/.claude/settings.json` by hand.
 
 npm / manual users:
 ```bash
-cc-cream-setup --uninstall                 # npm (add --purge to also remove runtime + config)
+cc-cream-setup --uninstall                 # npm (add --purge to also remove the config)
 node cc-cream/src/install.js --uninstall   # manual clone
 ```
 
 Uninstall removes the `statusLine` block **only if it is cc-cream's** — a
-statusLine you wired for something else is left untouched. In a terminal it asks
-before deleting the copied runtime and session-state files; run **non-interactively**
-(as the `/cc-cream:uninstall` slash command does) it leaves those artifacts in
-place — pass `--purge` to remove them and your `~/.claude/cc-cream.json` config.
-Restart Claude Code to clear the bar.
+statusLine you wired for something else is left untouched. It always cleans the
+regenerable scratch (the copied runtime and session state, both recreated on a
+reinstall); `--purge` additionally removes your `~/.claude/cc-cream.json` config.
+The bar clears on your next message (restart an already-open session to drop it now).
 
 Likewise, `cc-cream-setup` run non-interactively will overwrite an existing
 *cc-cream* statusLine but never a foreign one — pass `--force` to replace
 regardless.
 
+Not sure what's left behind? `cc-cream-setup --status` prints a read-only
+footprint report — the statusLine wiring, every cached plugin version (the host
+never garbage-collects these), the marketplace clone + registration, the auto-wire
+marker, session state, config, and the manual runtime copy — so you can confirm a
+clean slate or see exactly what to remove.
+
 ## Configuration
 
 Every display decision is read from `~/.claude/cc-cream.json`. Edit it by hand

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-cream",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Claude Code cache/context/cost status-line tool",
   "directories": {
     "doc": "docs"
@@ -16,6 +16,7 @@
     "coverage": "c8 cucumber-js",
     "watch": "cucumber-js --watch",
     "hooks": "simple-git-hooks",
+    "release": "node scripts/release.mjs",
     "prepublishOnly": "npm test"
   },
   "simple-git-hooks": {

package/src/cc-cream.js

@@ -7,6 +7,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
+import { fileURLToPath } from 'node:url';
 import { loadConfig, readConfigFile } from './config.js';
 import { buildSegments, render } from './render.js';
 import {
@@ -106,7 +107,83 @@ function logDebug(env, { data, cfg, now, prevSessionState, sessionId, rawLen, tt
   ]);
 }
 
+// --- Ghost-bar self-defense (CREAM-uchemxln) --------------------------------
+// No Claude Code host removal path deletes our statusLine OR the version cache:
+// `/plugin uninstall` and `/plugin marketplace remove` both leave the cache tree
+// AND the statusLine in settings.json. So a plugin-cache copy of this renderer
+// keeps executing every session after the plugin is gone — a zombie bar the user
+// has no in-product way to stop (`/cc-cream:uninstall` deregisters with the
+// plugin). The shell `[ -f entrypoint ] || exit 0` guard in install.js can't
+// cover this: the cache it checks for is never GC'd, so the file never goes
+// missing. The reliable signal is the host registry, not the filesystem — when we
+// detect we're running FROM the plugin cache, confirm cc-cream is still listed in
+// installed_plugins.json; if it's gone, exit 0 silently.
+
+function realpathOr(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+// If `selfPath` lives under `<root>/plugins/cache/<marketplace>/<plugin>/...`,
+// return { pluginsDir, pluginHome }; otherwise null (a manual/dev install, which
+// is never a cache orphan). Both paths are derived from the running location, so
+// the registry we consult is the one that actually governs THIS install — no
+// os.homedir()/CLAUDE_CONFIG_DIR assumption.
+function pluginCacheLocation(selfPath) {
+  const segs = realpathOr(selfPath).split(path.sep);
+  for (let i = 0; i + 3 < segs.length; i++) {
+    if (segs[i] === 'plugins' && segs[i + 1] === 'cache') {
+      return {
+        pluginsDir: segs.slice(0, i + 1).join(path.sep),
+        pluginHome: segs.slice(0, i + 4).join(path.sep),
+      };
+    }
+  }
+  return null;
+}
+
+function isWithin(parent, child) {
+  const rel = path.relative(parent, child);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+// True when this renderer is a plugin-cache orphan: running from the cache while
+// cc-cream is absent from the host's installed_plugins.json. Cost is one tiny
+// read, and ONLY on the plugin-cache path — manual/dev installs return early
+// before touching the disk. A missing registry (ENOENT) counts as orphaned; any
+// other read/parse failure is treated as not-orphaned, so a transient glitch can
+// never suppress a legitimately wired bar.
+function isOrphanedPluginRun(selfPath) {
+  const loc = pluginCacheLocation(selfPath);
+  if (!loc) return false;
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(path.join(loc.pluginsDir, 'installed_plugins.json'), 'utf8'));
+  } catch (err) {
+    return err?.code === 'ENOENT';
+  }
+  const plugins = parsed && typeof parsed === 'object' ? parsed.plugins : null;
+  if (!plugins || typeof plugins !== 'object') return true;
+  const home = realpathOr(loc.pluginHome);
+  for (const entries of Object.values(plugins)) {
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      if (entry && typeof entry.installPath === 'string' && isWithin(home, realpathOr(entry.installPath))) {
+        return false; // an installed cc-cream entry lives in our cache subtree
+      }
+    }
+  }
+  return true;
+}
+
 async function main() {
+  // Self-suppress a zombie bar left behind by an uninstalled plugin (before any
+  // stdin read — matching the intent of install.js's now-dead `[ -f ]` guard).
+  if (isOrphanedPluginRun(fileURLToPath(import.meta.url))) process.exit(0);
+
   const raw = await readStdin();
   const data = parseSession(raw);
   const cfg = loadConfig(readConfigFile());

package/src/install.js

@@ -22,7 +22,7 @@ import { isEntrypoint } from './utils.js';
 export { writeFileAtomic } from './settings.js';
 
 const TRUST_NOTE =
-  'Claude Code must be trusted and possibly restarted for the status line to appear.';
+  'The bar appears on your next message — restart only an already-open session, and the workspace must be trusted.';
 
 // The statusLine command: a missing-file guard, then exec node on an ABSOLUTE
 // entrypoint. Both install modes use this one shape — only the entrypoint path
@@ -217,8 +217,13 @@ function ask(question) {
   }));
 }
 
-// Remove the cc-cream wiring (and, with consent, its install artifacts). Keeps
-// the user's config (~/.claude/cc-cream.json) unless `--purge` is passed.
+// Remove the cc-cream wiring and its throwaway scratch. The copied runtime
+// (~/.claude/cc-cream) and session state (~/.claude/cc-cream-state.json) are
+// regenerable — reinstalling recreates them — so they're always cleaned, no
+// prompt. (The old interactive artifact prompt was dead code: both the `!` bang
+// runner and the slash commands run non-TTY — CREAM-lznfgrap.) `--purge`
+// additionally removes the one file worth keeping by default: the user-authored
+// config (~/.claude/cc-cream.json).
 async function uninstall({ purge }) {
   const file = settingsPath();
   const settings = readSettings(file);
@@ -226,42 +231,42 @@ async function uninstall({ purge }) {
   for (const m of result.messages) console.log(m);
   if (result.changed) {
     writeFileAtomic(file, `${JSON.stringify(result.settings, null, 2)}\n`);
-    console.log(`\nUpdated ${file}.`);
+    console.log(`Updated ${file}.`);
   }
 
   const home = path.join(os.homedir(), '.claude');
-  const runtimeDir = path.join(home, 'cc-cream');
-  const stateFile = path.join(home, 'cc-cream-state.json');
   const configFile = path.join(home, 'cc-cream.json');
 
-  const artifacts = [runtimeDir, stateFile].filter((p) => fs.existsSync(p));
-  if (artifacts.length) {
-    let remove = purge;
-    if (!remove && process.stdin.isTTY) {
-      remove = await ask(`Also delete the copied runtime and session state?\n  ${artifacts.join('\n  ')}`);
-    }
-    if (remove) {
-      for (const p of artifacts) fs.rmSync(p, { recursive: true, force: true });
-      console.log('Removed runtime and state files.');
-    } else if (process.stdin.isTTY) {
-      console.log('Left runtime and state files in place.');
+  // Auto-clean regenerable scratch (not user data — no prompt).
+  const scratch = [path.join(home, 'cc-cream'), path.join(home, 'cc-cream-state.json')]
+    .filter((p) => fs.existsSync(p));
+  for (const p of scratch) fs.rmSync(p, { recursive: true, force: true });
+  if (scratch.length) console.log('Removed the copied runtime and session state.');
+
+  if (fs.existsSync(configFile)) {
+    if (purge) {
+      fs.rmSync(configFile, { force: true });
+      console.log(`Removed your config ${configFile}.`);
     } else {
-      // Non-interactive (e.g. run via the /cc-cream:uninstall slash command, which
-      // has no TTY): never block on a prompt. The statusLine — the thing that
-      // matters — is already removed; keep the artifacts (deletion is destructive)
-      // and say how to remove them.
-      console.log(`Left runtime and session state in place — no terminal to confirm deletion:\n  ${artifacts.join('\n  ')}`);
-      console.log('Re-run in a terminal, or pass --purge, to remove them.');
+      console.log(`Kept your config ${configFile} (pass --purge to remove it too).`);
     }
   }
-  if (purge && fs.existsSync(configFile)) {
-    fs.rmSync(configFile, { force: true });
-    console.log(`Removed config ${configFile}.`);
-  } else if (fs.existsSync(configFile)) {
-    console.log(`Kept your config ${configFile} (pass --purge to remove it too).`);
-  }
 
-  console.log('\nRestart Claude Code to drop the bar.');
+  printUninstallReceipt();
+}
+
+// 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.
+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]');
 }
 
 // `cc-cream-setup --check-config`: lint ~/.claude/cc-cream.json against the
@@ -295,8 +300,119 @@ function checkConfigCli() {
   process.exit(1);
 }
 
+function listDirs(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function readJsonSafe(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// `cc-cream-setup --status`: a read-only report of cc-cream's entire on-disk
+// footprint. Because no Claude Code host removal path drops our statusLine or GCs
+// the version cache (project memory cc-cream-plugin-lifecycle-findings), users
+// can't otherwise tell whether cc-cream fully went away — this command answers
+// "clean slate?" in one shot, and points out what the host left behind.
+function statusCli() {
+  const home = path.join(os.homedir(), '.claude');
+  const plugins = path.join(home, 'plugins');
+  const items = [];
+  const add = (label, present, detail) => items.push({ label, present, detail });
+
+  // statusLine wiring
+  const { state, value } = readSettingsFile(settingsPath());
+  if (!isSafeToWrite(state)) {
+    add('statusLine wiring', false, `settings.json unreadable (${state}) — not inspected`);
+  } else if (isCcCreamStatusLine(value.statusLine)) {
+    const ep = (value.statusLine.command.match(/\[ -f "([^"]+)"/) || [])[1] || '';
+    const ok = ep && fs.existsSync(ep);
+    add('statusLine wiring', true, ok
+      ? `belongs to cc-cream, pinned to ${ep}`
+      : `belongs to cc-cream, pinned to ${ep || '(unknown)'} — entrypoint MISSING (stale/ghost wiring)`);
+  } else if (value.statusLine) {
+    add('statusLine wiring', false, 'present but not cc-cream’s (left untouched)');
+  } else {
+    add('statusLine wiring', false, 'none');
+  }
+
+  // plugin cache versions (the host never GCs these)
+  const versions = listDirs(path.join(plugins, 'cache', 'cc-cream', 'cc-cream'));
+  add('plugin cache', versions.length > 0, versions.length
+    ? `${versions.length} version(s) [${versions.join(', ')}] — host never GCs these; rm to reclaim`
+    : 'none');
+
+  // marketplace clone
+  const clone = path.join(plugins, 'marketplaces', 'cc-cream');
+  add('marketplace clone', fs.existsSync(clone), fs.existsSync(clone) ? clone : 'none');
+
+  // registrations
+  const installed = readJsonSafe(path.join(plugins, 'installed_plugins.json'));
+  const isRegistered = !!installed?.plugins && typeof installed.plugins === 'object'
+    && Object.keys(installed.plugins).some((k) => k.startsWith('cc-cream@'));
+  add('plugin registration', isRegistered, isRegistered
+    ? 'listed in installed_plugins.json'
+    : 'not listed in installed_plugins.json');
+
+  const known = readJsonSafe(path.join(plugins, 'known_marketplaces.json'));
+  const knownMkt = !!known && typeof known === 'object' && Object.hasOwn(known, 'cc-cream');
+  add('marketplace registration', knownMkt, knownMkt
+    ? 'listed in known_marketplaces.json'
+    : 'not listed in known_marketplaces.json');
+
+  // auto-wire marker (plugin data dir, falling back to the config dir)
+  const markerDir = process.env.CLAUDE_PLUGIN_DATA || path.join(plugins, 'data', 'cc-cream-cc-cream');
+  const marker = [path.join(markerDir, 'cc-cream-autowire-done'), path.join(home, 'cc-cream-autowire-done')]
+    .find((p) => fs.existsSync(p));
+  add('auto-wire marker', !!marker, marker || 'none');
+
+  // session state
+  const stateFile = path.join(home, 'cc-cream-state.json');
+  if (fs.existsSync(stateFile)) {
+    const obj = readJsonSafe(stateFile);
+    const n = obj && typeof obj === 'object' ? Object.keys(obj).length : '?';
+    add('session state', true, `${n} session(s) in cc-cream-state.json`);
+  } else {
+    add('session state', false, 'none');
+  }
+
+  // config
+  const configFile = path.join(home, 'cc-cream.json');
+  add('config', fs.existsSync(configFile), fs.existsSync(configFile) ? configFile : 'none (using defaults)');
+
+  // manual runtime copy
+  const runtimeDir = path.join(home, 'cc-cream');
+  add('manual runtime copy', fs.existsSync(runtimeDir), fs.existsSync(runtimeDir) ? runtimeDir : 'none');
+
+  console.log('cc-cream footprint:');
+  for (const it of items) console.log(`  [${it.present ? 'x' : ' '}] ${it.label}: ${it.detail}`);
+
+  if (items.every((i) => !i.present)) {
+    console.log('\nClean slate — no cc-cream footprint found.');
+    return;
+  }
+  console.log(`\n${items.filter((i) => i.present).length} component(s) present. To remove everything:`);
+  console.log('  /cc-cream:uninstall (or the cache-path install.js --uninstall) clears the statusLine + scratch;');
+  console.log('  then /plugin uninstall cc-cream + /plugin marketplace remove cc-cream;');
+  console.log('  then rm -rf ~/.claude/plugins/cache/cc-cream (the host never removes it).');
+}
+
 async function main() {
   const args = process.argv.slice(2);
+  if (args.includes('--status')) {
+    statusCli();
+    return;
+  }
   if (args.includes('--check-config')) {
     checkConfigCli();
     return;
@@ -343,12 +459,15 @@ async function main() {
   }
 
   let result = plan(settings, planOpts);
-  // If a replace needs consent, ask now and re-plan with the answer.
+  // A foreign statusLine needs consent before we replace it. This first plan()
+  // pass is detection only — do NOT print its messages: they include a
+  // speculative "Declined …" (consent was absent) that would contradict a
+  // subsequent --force replace. Resolve consent, re-plan, then print the single
+  // coherent second-pass result below (CREAM-hpjebzes).
   if (!result.changed && result.needsConsent) {
-    for (const m of result.messages) console.log(m);
     let yes;
     if (process.stdin.isTTY) {
-      yes = await ask('Replace it with cc-cream?');
+      yes = await ask('Replace your existing statusLine with cc-cream?');
     } else {
       // Non-interactive (e.g. run via the /cc-cream:setup slash command, which has
       // no TTY): never block on a prompt. Safe to overwrite our OWN wiring (an
@@ -356,7 +475,7 @@ async function main() {
       // statusLine without a terminal or an explicit --force.
       yes = force || isCcCreamStatusLine(settings.statusLine);
       console.log(yes
-        ? 'Non-interactive: replacing the existing cc-cream statusLine.'
+        ? 'Non-interactive: replacing the existing statusLine with cc-cream’s.'
         : 'Non-interactive: left your existing statusLine unchanged. Re-run in a terminal, or pass --force, to replace it.');
     }
     result = plan(settings, { ...planOpts, consent: yes });