@promptctl/cc-candybar 1.41.3 → 1.42.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.41.3",
+  "version": "1.42.1",
   "description": "Statusline renderer for Claude Code — a JSON5-configurable DSL with daemon-cached data sources, byte-clean palette-aware composition, and OSC8 click verbs.",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -91,9 +91,9 @@
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.41.3",
-    "@promptctl/cc-candybar-darwin-x64": "1.41.3",
-    "@promptctl/cc-candybar-linux-x64": "1.41.3",
-    "@promptctl/cc-candybar-linux-arm64": "1.41.3"
+    "@promptctl/cc-candybar-darwin-arm64": "1.42.1",
+    "@promptctl/cc-candybar-darwin-x64": "1.42.1",
+    "@promptctl/cc-candybar-linux-x64": "1.42.1",
+    "@promptctl/cc-candybar-linux-arm64": "1.42.1"
   }
 }

package/src/cli-flags.ts

@@ -0,0 +1,8 @@
+// [LAW:one-source-of-truth] The bare flags Node answers itself. The dispatch in
+// index.ts reads it, `--help` renders its own lines from it, and the Rust client
+// routes exactly these to Node (its NODE_FLAGS; check-protocol diffs the two),
+// so a spelling added here without its mirror fails the build, not the user.
+export const NODE_FLAGS = {
+  help: ["-h", "--help"],
+  version: ["-V", "--version"],
+} as const;

package/src/daemon/client-stats.ts

@@ -64,6 +64,7 @@ export function formatStats(s: StatsSnapshot): string {
   lines.push(`process`);
   lines.push(`  pid           ${s.pid}`);
   lines.push(`  version       ${s.version}`);
+  lines.push(`  protocol      ${s.protocolVersion}`);
   lines.push(`  startedAt     ${s.startedAt}`);
   lines.push(`  uptime        ${fmtUptime(s.uptimeSec)}`);
   lines.push(`  rss           ${fmtBytes(s.rssBytes)}`);

package/src/daemon/stats.ts

@@ -5,6 +5,7 @@
 import type { LaunchCategory } from "../proc/launch";
 import type { LaunchStatsHandle } from "../proc/stats-handle";
 import { PROTOCOL_VERSION } from "./protocol";
+import { PACKAGE_VERSION } from "../version";
 
 // Rolling window for "last minute" counts. Keep timestamps for each launch in
 // a ring buffer; eviction happens lazily on read.
@@ -28,7 +29,11 @@ const HISTOGRAM_CAP = 16;
 
 export interface StatsSnapshot {
   pid: number;
-  version: number;
+  // [LAW:one-source-of-truth] The daemon's own baked package stamp — set
+  // against `cc-candybar --version` to diagnose client-vs-daemon skew in one
+  // step. The wire contract number is a different fact under its own name.
+  version: string;
+  protocolVersion: number;
   startedAt: string;
   uptimeSec: number;
   rssBytes: number;
@@ -199,7 +204,8 @@ export class RuntimeStats {
     const mem = process.memoryUsage();
     return {
       pid: process.pid,
-      version: PROTOCOL_VERSION,
+      version: PACKAGE_VERSION,
+      protocolVersion: PROTOCOL_VERSION,
       startedAt: this.startedAt.toISOString(),
       uptimeSec: Math.floor((Date.now() - this.startedAt.getTime()) / 1000),
       rssBytes: mem.rss,

package/src/help-text.ts

@@ -1,5 +1,6 @@
 import { DISCLOSURE_GLYPH_CLOSED } from "./config/disclosure";
 import { HELP_GLYPH_CLOSED } from "./config/help";
+import { NODE_FLAGS } from "./cli-flags";
 
 // [LAW:effects-at-boundaries] Pure data, no I/O — index.ts owns the console.log
 // effect. Kept as its own module so the text is importable (and testable) without
@@ -36,7 +37,8 @@ cc-candybar - Beautiful powerline statusline for Claude Code
 Usage: cc-candybar [options]
 
 Standalone Commands:
-  -h, --help               Show this help
+  ${NODE_FLAGS.help.join(", ").padEnd(25)}Show this help
+  ${NODE_FLAGS.version.join(", ").padEnd(25)}Print the version of this runtime (cc-candybar <version>)
 
 Debugging:
   CC_CANDYBAR_DEBUG=1      Enable debug logging for troubleshooting

package/src/index.ts

@@ -16,6 +16,8 @@ import { runCheck } from "./check";
 import { obtainDaemonKick } from "./daemon/acquire";
 import { planOutcome } from "./render/outcome-plan";
 import { HELP_TEXT } from "./help-text";
+import { NODE_FLAGS } from "./cli-flags";
+import { PACKAGE_VERSION } from "./version";
 
 // Read terminal width from the live shell context (no subprocess). Returns
 // undefined when nothing reliable is available; the daemon falls back to its
@@ -52,6 +54,9 @@ function detectTermCols(): number | undefined {
 // widen recall of a fact that is otherwise reported as a plain `false`.
 const SSH_ENV_VARS = ["SSH_CONNECTION", "SSH_CLIENT", "SSH_TTY"] as const;
 
+const hasFlag = (flags: readonly string[]): boolean =>
+  flags.some((f) => process.argv.includes(f));
+
 // [LAW:dataflow-not-control-flow] A fold over the vocabulary, not a chain of
 // ifs — adding a name is a data edit.
 //
@@ -69,20 +74,25 @@ function showHelpText(): void {
 
 async function main(): Promise<void> {
   try {
-    const showHelp =
-      process.argv.includes("--help") || process.argv.includes("-h");
-
-    if (showHelp) {
+    if (hasFlag(NODE_FLAGS.help)) {
       showHelpText();
       process.exit(0);
     }
+    // [LAW:one-type-per-behavior] Answers "what is THIS binary" from the baked
+    // stamp alone — never a daemon probe, which would fail exactly when the
+    // flag is most needed (no working daemon). Daemon skew is the stats
+    // snapshot's `version` field.
+    if (hasFlag(NODE_FLAGS.version)) {
+      console.log(`cc-candybar ${PACKAGE_VERSION}`);
+      process.exit(0);
+    }
 
     // [LAW:dataflow-not-control-flow] Subcommand dispatch is data: argv[2]
     // selects the handler. Each handler short-circuits via process.exit().
     // Default fallthrough = the existing stdin-driven render flow.
     const subcommand = process.argv[2];
     if (subcommand === "install") {
-      runInstall(process.argv.slice(3));
+      await runInstall(process.argv.slice(3));
       process.exit(0);
     }
     if (subcommand === "install-url-handler") {

package/src/install/currency.ts

@@ -0,0 +1,197 @@
+// Is the runtime `install` just staged the newest published release? pnpm
+// resolves `@latest` through its dlx cache and its release-age gate
+// (`minimumReleaseAge`), either of which can hand back an older release with
+// no error — so `pnpm dlx @promptctl/cc-candybar@latest install` can stage a
+// version several releases behind and report success. This module answers the
+// currency question as data: a strict version parser at the border, the
+// registry lookup as an `Outcome`, one total fold into a `Currency`, and one
+// formatter that describes the report for `runInstall` to perform.
+
+import { ABSENT, failed, type Outcome } from "../utils/outcome";
+
+// [LAW:types-are-the-program] A release version is exactly MAJOR.MINOR.PATCH.
+// semantic-release on `main` mints nothing else, and the ordering the currency
+// verdict needs is total only over that shape — so the parser refuses anything
+// else rather than admitting a prerelease it could not order.
+export type Version = readonly [major: number, minor: number, patch: number];
+
+const RELEASE_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+
+// A parse either produces a value or fails with a reason; "absent" is not a
+// shape text can have.
+type Parsed<T> = Exclude<Outcome<T>, { kind: "absent" }>;
+
+// [LAW:parse-dont-validate] The one crossing from text to `Version`. Both the
+// baked stamp and the registry's dist-tag pass through here; downstream code
+// takes `Version` and never re-checks the shape. The failure is typed, not
+// thrown: on either side it flows into the `unchecked` verdict, so the
+// advisory check can never take the install down with it.
+export function parseReleaseVersion(text: string): Parsed<Version> {
+  const m = RELEASE_VERSION.exec(text);
+  return m
+    ? { kind: "ok", value: [Number(m[1]), Number(m[2]), Number(m[3])] }
+    : {
+        kind: "failed",
+        reason: `"${text}" is not a release version (expected MAJOR.MINOR.PATCH)`,
+      };
+}
+
+export function formatVersion(v: Version): string {
+  return v.join(".");
+}
+
+// Lexicographic over the triple: the first differing component decides.
+function compareVersions(
+  [aMajor, aMinor, aPatch]: Version,
+  [bMajor, bMinor, bPatch]: Version,
+): number {
+  return aMajor - bMajor || aMinor - bMinor || aPatch - bPatch;
+}
+
+export const REGISTRY_URL = "https://registry.npmjs.org";
+
+// The check rides at the end of an install; it may not hang one. A registry
+// that answers slower than this is reported as unreachable, not waited on.
+export const REGISTRY_TIMEOUT_MS = 5_000;
+
+// [LAW:effects-at-boundaries] The one network effect in the install path. It
+// takes `fetch` as a parameter so the pure core above and the tests never
+// touch the wire; the caller hands in the global. Every way the lookup can
+// fail to answer — refused, timed out, non-2xx, unparseable body, dist-tag not
+// a release — collapses to `failed` with its reason preserved, and a registry
+// that lists no `latest` tag at all is `absent`. [LAW:no-silent-failure] None
+// of those is ever reported as "current".
+export async function fetchLatestVersion(
+  packageName: string,
+  fetchImpl: typeof fetch,
+): Promise<Outcome<Version>> {
+  const url = `${REGISTRY_URL}/-/package/${encodeURIComponent(packageName)}/dist-tags`;
+  try {
+    const res = await fetchImpl(url, {
+      signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+      return failed(`registry responded ${res.status} for ${url}`);
+    }
+    const tags = (await res.json()) as { latest?: unknown };
+    if (typeof tags.latest !== "string") {
+      return ABSENT;
+    }
+    return parseReleaseVersion(tags.latest);
+  } catch (err) {
+    return failed(err instanceof Error ? err.message : String(err));
+  }
+}
+
+// [LAW:types-are-the-program] The verdict. `unchecked` is its own arm rather
+// than a `current` with a flag: an install that could not compare has no
+// currency, and no consumer may read it as having one. It carries the stamp
+// as text because the stamp itself may be what failed to parse.
+export type Currency =
+  | { readonly kind: "current"; readonly installed: Version }
+  | {
+      readonly kind: "stale";
+      readonly installed: Version;
+      readonly latest: Version;
+    }
+  | {
+      readonly kind: "ahead";
+      readonly installed: Version;
+      readonly latest: Version;
+    }
+  | {
+      readonly kind: "unchecked";
+      readonly installed: string;
+      readonly reason: string;
+    };
+
+// [LAW:dataflow-not-control-flow] One total fold: the stamp, the lookup
+// outcome, and the version ordering all flow in as values, and every
+// combination lands in exactly one arm.
+export function assessCurrency(
+  stamp: string,
+  latest: Outcome<Version>,
+): Currency {
+  const installed = parseReleaseVersion(stamp);
+  if (installed.kind === "failed") {
+    return { kind: "unchecked", installed: stamp, reason: installed.reason };
+  }
+  switch (latest.kind) {
+    case "failed":
+      return { kind: "unchecked", installed: stamp, reason: latest.reason };
+    case "absent":
+      return {
+        kind: "unchecked",
+        installed: stamp,
+        reason: "the registry lists no `latest` dist-tag",
+      };
+    case "ok": {
+      const order = compareVersions(installed.value, latest.value);
+      if (order < 0) {
+        return {
+          kind: "stale",
+          installed: installed.value,
+          latest: latest.value,
+        };
+      }
+      if (order > 0) {
+        return {
+          kind: "ahead",
+          installed: installed.value,
+          latest: latest.value,
+        };
+      }
+      return { kind: "current", installed: installed.value };
+    }
+  }
+}
+
+// A description of the report, not the report itself: `runInstall` owns the
+// write. Warnings go to stderr, confirmations to stdout — the CLI's stream
+// contract, so a scripted install can separate the two.
+export interface CurrencyReport {
+  readonly stream: "stdout" | "stderr";
+  readonly text: string;
+}
+
+// [LAW:no-silent-failure] The stale arm names the cause and the exact command
+// that gets the current release now; the unchecked arm says the check was
+// skipped and why, and never implies the install is current.
+export function currencyReport(
+  packageName: string,
+  currency: Currency,
+): CurrencyReport {
+  switch (currency.kind) {
+    case "current":
+      return {
+        stream: "stdout",
+        text: `✓ cc-candybar ${formatVersion(currency.installed)} is the latest release.\n`,
+      };
+    case "ahead":
+      return {
+        stream: "stdout",
+        text:
+          `cc-candybar ${formatVersion(currency.installed)} is newer than the registry's latest release ` +
+          `(${formatVersion(currency.latest)}): an unpublished build.\n`,
+      };
+    case "stale": {
+      const latest = formatVersion(currency.latest);
+      return {
+        stream: "stderr",
+        text:
+          `⚠ cc-candybar ${formatVersion(currency.installed)} was staged, but the latest release is ${latest}.\n` +
+          `  pnpm's release-age gate (minimumReleaseAge) and its dlx cache can both\n` +
+          `  resolve \`@latest\` to an older release without saying so.\n` +
+          `  To install ${latest} now, name it explicitly:\n` +
+          `    pnpm dlx ${packageName}@${latest} install\n`,
+      };
+    }
+    case "unchecked":
+      return {
+        stream: "stderr",
+        text:
+          `⚠ Could not check for a cc-candybar release newer than ${currency.installed} ` +
+          `(${currency.reason}); the registry check was skipped.\n`,
+      };
+  }
+}

package/src/install/index.ts

@@ -8,12 +8,8 @@ import type { PermanentOutcome } from "../daemon/client-transport";
 import { obtainDaemonKick } from "../daemon/acquire";
 import { URL_SCHEME, VERB_COPY } from "../click/wire";
 import { DISCLOSURE_GLYPH_CLOSED } from "../config/disclosure";
-
-// [LAW:one-source-of-truth] Replaced at build time by tsdown's `define` option
-// from package.json — the single version stamp install output reports.
-declare const __PACKAGE_VERSION__: string;
-const PACKAGE_VERSION =
-  typeof __PACKAGE_VERSION__ !== "undefined" ? __PACKAGE_VERSION__ : "dev";
+import { PACKAGE_VERSION } from "../version";
+import { assessCurrency, currencyReport, fetchLatestVersion } from "./currency";
 
 const PACKAGE_NAME = "@promptctl/cc-candybar";
 const BUNDLE_ID = "com.cccandybar.url-handler";
@@ -456,7 +452,7 @@ function installSuccessMessage(): string {
   );
 }
 
-export function runInstall(rendererArgs: string[]): void {
+export async function runInstall(rendererArgs: string[]): Promise<void> {
   const force = rendererArgs.includes("--force");
   const filteredArgs = rendererArgs.filter((a) => a !== "--force");
 
@@ -476,6 +472,21 @@ export function runInstall(rendererArgs: string[]): void {
   updateClaudeSettings(staged.binPath, argsToInstall, force);
 
   process.stdout.write(installSuccessMessage());
+
+  // Last: a stale-version warning is the final thing on screen, and the
+  // lookup starts only after the synchronous work above — spawnSync blocks
+  // the event loop, so a fetch started earlier could not progress and would
+  // burn its timeout budget idle. [LAW:no-ambient-temporal-coupling] The
+  // staged runtime works either way; the verdict informs, it never fails the
+  // install. [LAW:no-silent-failure]
+  const report = currencyReport(
+    PACKAGE_NAME,
+    assessCurrency(
+      PACKAGE_VERSION,
+      await fetchLatestVersion(PACKAGE_NAME, fetch),
+    ),
+  );
+  process[report.stream].write(report.text);
 }
 
 function updateClaudeSettings(

package/src/version.ts

@@ -0,0 +1,17 @@
+// [LAW:one-source-of-truth] THE version stamp of this runtime. package.json is
+// the sole authority: tsdown's `define` bakes it into the bundle, and
+// scripts/version-stamp.cjs preloads it for untranspiled source. Every consumer
+// — `--version`, the install banner, the daemon's stats snapshot — reads this
+// one export.
+declare const __PACKAGE_VERSION__: string;
+
+// [LAW:no-silent-failure] A runtime that cannot say what it is must say THAT.
+// The old `"dev"` fallback was an answer-shaped void in a flag whose whole job
+// is answering this question; an unsubstituted build now fails at module load.
+if (typeof __PACKAGE_VERSION__ === "undefined") {
+  throw new Error(
+    "__PACKAGE_VERSION__ was not substituted: build via tsdown (define), or preload scripts/version-stamp.cjs when running source",
+  );
+}
+
+export const PACKAGE_VERSION: string = __PACKAGE_VERSION__;