context-carwash 0.1.0 → 0.1.2

package/README.md

@@ -5,7 +5,7 @@ A small, local-first utility for Claude Code.
 - **Meter:** a quiet estimate of the active context window in the status line.
 - **Wash:** when you ask, Claude writes a short handoff brief, and your next `/clear` starts a fresh session that begins with it.
 
-Nothing happens automatically, and nothing leaves your machine.
+Nothing happens automatically, and nothing leaves your machine. The one exception: the installer asks npm whether a newer version is out.
 
 **Status:** pre-release. The meter and the typed `/wash` command work today. Clickable links in the status line and the one-step restart are not built yet. See [plan-3.md](plan-3.md) for the design.
 
@@ -18,7 +18,7 @@ npx context-carwash preview     # sample meters in your terminal, nothing instal
 npx context-carwash install     # lists what it will change, then asks
 ```
 
-To update later, run `npx context-carwash@latest install` again. Waiting briefs are kept.
+To update later, run `npx context-carwash@latest install` again. Waiting briefs are kept. The `@latest` matters: without it npx may rerun the copy it downloaded last time. If it does, the installer says a newer version is out before asking to go ahead.
 
 The installer copies itself to `~/.carwash/app` and makes three changes to Claude Code, all listed before you confirm:
 
@@ -31,16 +31,16 @@ Start a new Claude Code session afterwards. The first one explains the meter and
 ## The meter
 
 ```text
-context ~136k  [██████████░░░░░]  /wash to compress & save context, then /clear
+session context ~136k  [██████████░░░░░]  /wash to compress & save context, then /clear keeps compressed context
 ```
 
 The number is how many tokens the conversation is using. It comes from Claude Code and is an estimate. The bar shows how close that is to the most the model's context window holds, and changes colour as it fills. From three quarters on, the meter also says so in words:
 
 ```text
-context ~150k  [███████████░░░░]  getting full · /wash to compress & save context, then /clear
+session context ~150k  [███████████░░░░]  getting full · /wash to compress & save context, then /clear keeps compressed context
 ```
 
-Narrower windows show less: the sentence shortens first (`/wash to compress, then /clear` fits an 80-column window), then the bar goes.
+Narrower windows show less. The sentence shortens first: `/wash to compress & save context, then /clear` fits about half a Mac screen, `/wash to compress, then /clear` fits an 80-column window, and the narrowest windows show `/wash to compress`. Then the bar goes.
 
 A full meter is information. It never triggers anything.
 
@@ -76,7 +76,7 @@ Things worth knowing:
 
 ## Where things are kept
 
-Briefs are stored in `~/.carwash`, readable only by you, and never inside your project. Nothing is uploaded, and there is no telemetry.
+Briefs are stored in `~/.carwash`, readable only by you, and never inside your project. Nothing is uploaded, and there is no telemetry. The installer reads the newest version number from npm, and nothing else goes online; set `CARWASH_NO_UPDATE_CHECK=1` to skip even that.
 
 If a hook fails it stays silent and writes the error to `~/.carwash/errors.log`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-carwash",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A quiet context meter and deliberate fresh-session handoff for Claude Code.",
   "license": "MIT",
   "repository": {

package/src/cli.mjs

@@ -2,6 +2,7 @@ import { appendFileSync, existsSync, statSync, writeFileSync } from 'node:fs';
 import { createInterface } from 'node:readline';
 import { applyInstall, applyUninstall, describeInstall, describeUninstall, packageVersion, planInstall, planUninstall } from './install/install.mjs';
 import { UserError } from './install/settings.mjs';
+import { latestVersion, updateNotice } from './install/update.mjs';
 import { errorLogPath, welcomedPath } from './paths.mjs';
 import { render } from './statusline/render.mjs';
 import { statusline } from './statusline/run.mjs';
@@ -24,7 +25,7 @@ Inside Claude Code, once installed:
   /wash load [id]                  Make a waiting brief the one /clear will use
   /wash help                       Explain the meter and the options
 
-Nothing happens automatically, and nothing leaves this machine.`;
+Nothing happens automatically. Only install goes online, to ask npm for the newest version.`;
 
 async function readAll(stream) {
   if (stream.isTTY) return '';
@@ -87,7 +88,7 @@ function logError(env, error) {
   }
 }
 
-export async function main(argv, { env = process.env, stdin = process.stdin, stdout = process.stdout, stderr = process.stderr } = {}) {
+export async function main(argv, { env = process.env, stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, latest = latestVersion } = {}) {
   const [command, ...rest] = argv;
   const yes = rest.includes('--yes') || rest.includes('-y');
   try {
@@ -108,6 +109,9 @@ export async function main(argv, { env = process.env, stdin = process.stdin, std
       case 'install': {
         const plan = planInstall({ env });
         stdout.write(describeInstall(plan) + '\n\n');
+        // Last, so it sits right above the question it changes the answer to.
+        const notice = updateNotice(packageVersion(), await latest({ env }));
+        if (notice) stdout.write(notice + '\n\n');
         if (!(await confirm('Proceed?', { yes, stdin, stdout }))) {
           stdout.write('Nothing was changed.\n');
           return 1;

package/src/install/update.mjs

@@ -0,0 +1,44 @@
+// Whether a newer Context Carwash is on npm. Only the installer asks, since
+// npx can quietly rerun a copy it downloaded earlier. The meter and /wash never
+// use the network.
+
+const LATEST_URL = 'https://registry.npmjs.org/context-carwash/latest';
+const TIMEOUT_MS = 3000;
+
+const parse = (version) => {
+  const found = /^(\d+)\.(\d+)\.(\d+)$/.exec(String(version ?? '').trim());
+  return found ? found.slice(1).map(Number) : null;
+};
+
+// True when `latest` is a later release than `current`. Anything unreadable is
+// not newer.
+export function isNewer(latest, current) {
+  const a = parse(latest);
+  const b = parse(current);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] > b[i];
+  return false;
+}
+
+// The version npm calls latest, or null when it cannot say in time. Offline,
+// slow or opted out (CARWASH_NO_UPDATE_CHECK) all mean no answer, never an error.
+export async function latestVersion({ env = process.env, timeoutMs = TIMEOUT_MS } = {}) {
+  if (env.CARWASH_NO_UPDATE_CHECK) return null;
+  try {
+    const response = await fetch(LATEST_URL, { signal: AbortSignal.timeout(timeoutMs), headers: { accept: 'application/json' } });
+    if (!response.ok) return null;
+    const { version } = await response.json();
+    return parse(version) ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+// What the installer says before asking, or null when this is the latest.
+export function updateNotice(current, latest) {
+  if (!isNewer(latest, current)) return null;
+  return [
+    `A newer Context Carwash is out: ${latest}. This installer is ${current}.`,
+    'To install the newer one, answer no and run:  npx context-carwash@latest install',
+  ].join('\n');
+}

package/src/statusline/render.mjs

@@ -12,10 +12,13 @@ const FULL = 'getting full';
 
 // What /wash does, said plainly. The levels and their caps are left to the
 // command menu and /wash help, which show them when someone is choosing. The
-// middle form keeps the meaning in an 80-column window, the Terminal.app default.
+// full form needs a wide window, the long one fits about half a Mac screen, and
+// the middle one keeps the /clear step in an 80-column window, the Terminal.app
+// default.
+const HINT_FULL = '/wash to compress & save context, then /clear keeps compressed context';
 const HINT_LONG = '/wash to compress & save context, then /clear';
 const HINT_MID = '/wash to compress, then /clear';
-const HINT_SHORT = '/wash, then /clear';
+const HINT_SHORT = '/wash to compress';
 
 const finite = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
 
@@ -97,7 +100,7 @@ export function render(payload, options = {}) {
   // The reading is the tokens in use, and nothing else: a count is something
   // people can picture, and the bar already shows how much of the window that
   // is, so neither a percentage nor the window size is spelled out.
-  const usedSeg = `context ${used ? `~${formatTokens(used)}` : '--'}`;
+  const usedSeg = `session context ${used ? `~${formatTokens(used)}` : '--'}`;
   const barSeg = bar(pct, depth, options.barStyle ?? 'ramp');
   const caps = capLabels(used);
   // Only while inviting a wash: once one is under way there is nothing to add.
@@ -112,8 +115,8 @@ export function render(payload, options = {}) {
     candidates = [
       [usedSeg, barSeg, `${ready}. Old session stays in /resume.`],
       [usedSeg, barSeg, ready],
-      [usedSeg, barSeg, 'Brief ready ✓ · type /clear'],
-      [usedSeg, 'Brief ready ✓ · type /clear'],
+      [usedSeg, barSeg, 'Brief ready ✓ · /clear to start fresh'],
+      [usedSeg, 'Brief ready ✓ · /clear to start fresh'],
       [usedSeg, 'Brief ready ✓'],
     ];
   } else if (options.state?.washing) {
@@ -130,6 +133,7 @@ export function render(payload, options = {}) {
     ];
   } else {
     candidates = [
+      [usedSeg, barSeg, say(HINT_FULL)],
       [usedSeg, barSeg, say(HINT_LONG)],
       [usedSeg, barSeg, say(HINT_MID)],
       [usedSeg, barSeg, say(HINT_SHORT)],

package/src/wash/brief.mjs

@@ -111,10 +111,10 @@ export function loadedMessage(record, now, stale) {
 // Shown once, at the first session after install.
 export function welcomeMessage() {
   return [
-    'Context Carwash is installed. This note is shown once.',
-    'The status line shows how many tokens this conversation is using, and the bar shows how close that is to the model\'s limit. It changes colour as it fills and says "getting full" from three quarters on.',
-    'To start fresh without losing your place: /wash to compress & save context into a short brief, then /clear. The new session begins with the brief, and the old one stays in /resume.',
-    'Nothing happens unless you ask. /wash help shows the options.',
+    'Context Carwash installed ✓ (shown once)',
+    '  • Status line: tokens in use, and how full the context is',
+    '  • Getting full? /wash, then /clear. You start fresh, right where you left off',
+    '  • Nothing runs on its own · /wash help for options',
   ].join('\n');
 }