@pithy-sh/cli 0.1.0

package/src/notifier/check.ts

@@ -0,0 +1,129 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { detectInstaller } from "./installer";
+import type { NotifierState } from "./state";
+
+/**
+ * The background update check (docs/CLI.md §5.1): a 24-hour-gated query of the npm registry for the latest
+ * `@pithy-sh/cli` version, plus the per-capability version lookups `pithy doctor` runs. Every network path
+ * is silent on failure — offline, DNS, a non-200, or a timeout all leave the cached value in place and
+ * never surface an error. Update checks are non-essential; they must never break the actual CLI.
+ */
+
+/** A minimal `fetch` shape — the real `globalThis.fetch` satisfies it, and tests inject a fake. */
+export type FetchLike = (url: string, init?: { signal?: AbortSignal }) => Promise<FetchResponse>;
+
+/** The slice of a `fetch` `Response` the notifier reads. */
+export interface FetchResponse {
+  ok: boolean;
+  status: number;
+  json(): Promise<unknown>;
+}
+
+/** The npm scope every Pithy package ships under. */
+const SCOPE = "@pithy-sh";
+/** How long a stale check waits before giving up on the registry, so a hung request never delays exit. */
+const DEFAULT_TIMEOUT_MS = 3_000;
+/** The cache window: at most one background check per 24 hours. */
+export const CACHE_MS = 24 * 60 * 60 * 1000;
+
+/** The registry `latest`-manifest URL for an unscoped `@pithy-sh/<name>` package (matches docs/CLI.md §5.1). */
+export function registryUrl(unscopedName: string): string {
+  return `https://registry.npmjs.org/${SCOPE}%2F${unscopedName}/latest`;
+}
+
+/** The latest published version of a package, plus whether the release is security-flagged. */
+export interface LatestInfo {
+  version: string;
+  securityFlagged: boolean;
+}
+
+/** Read the `pithy:security` marker off a registry manifest: a top-level flag or a nested `pithy.security`. */
+function readSecurityFlag(manifest: Record<string, unknown>): boolean {
+  if (manifest["pithy:security"] === true) return true;
+  const pithy = manifest.pithy;
+  return typeof pithy === "object" && pithy !== null && (pithy as { security?: unknown }).security === true;
+}
+
+/**
+ * Query the registry for a package's latest version. Returns `null` on any failure — a rejected fetch, a
+ * non-200, a timeout, or an unparseable body — so callers keep using their cached value. A short timeout
+ * bounds a hung registry. The security flag defaults to not-flagged when it can't be determined.
+ */
+export async function fetchLatestVersion(
+  unscopedName: string,
+  options: { fetch?: FetchLike; timeoutMs?: number } = {},
+): Promise<LatestInfo | null> {
+  const doFetch = options.fetch ?? (globalThis.fetch as unknown as FetchLike);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  // Don't let the abort timer itself hold the event loop open — the update check must never delay the CLI's
+  // exit past its own work. (Node timers expose unref; guard for non-Node timers.)
+  timer.unref?.();
+  try {
+    const response = await doFetch(registryUrl(unscopedName), { signal: controller.signal });
+    if (!response.ok) return null;
+    const body = (await response.json()) as Record<string, unknown>;
+    const version = body.version;
+    if (typeof version !== "string") return null;
+    return { version, securityFlagged: readSecurityFlag(body) };
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Options for {@link refreshCliState} — the version-check inputs, all injectable for deterministic tests. */
+export interface RefreshOptions {
+  /** Injected `fetch`; defaults to the global. */
+  fetch?: FetchLike;
+  /** The clock; defaults to `Date.now`. */
+  now?: () => number;
+  /** Bypass the 24-hour cache and always query (what `pithy doctor` passes). */
+  bypassCache?: boolean;
+  /** The cache window in ms; defaults to 24 hours. */
+  cacheMs?: number;
+  /** `process.argv[1]`, used to detect the installer once when it is still `unknown`. */
+  argv1?: string;
+  /** Registry request timeout in ms. */
+  timeoutMs?: number;
+}
+
+/** The outcome of a refresh: the (possibly-updated) state and whether a successful network check changed it. */
+export interface RefreshResult {
+  state: NotifierState;
+  /** True only when a network query succeeded and updated the state — the signal to persist it. */
+  updated: boolean;
+}
+
+/**
+ * Apply the 24-hour cache gate to the CLI version check and, when due, refresh the state from the registry.
+ *
+ * - Within the cache window (and not bypassing): no network request; the cached state is returned unchanged.
+ * - Stale (or bypassing): one registry query. On success, `lastCheck`, `latestVersion`, `securityFlagged`,
+ *   and — if still `unknown` — `installer` are updated, and `updated` is true (persist it).
+ * - On any network failure: the cached state is returned unchanged with `updated` false, so no partial
+ *   state is ever written and the previously-known `latestVersion` continues to drive the notification.
+ */
+export async function refreshCliState(state: NotifierState, options: RefreshOptions = {}): Promise<RefreshResult> {
+  const now = options.now ?? Date.now;
+  const cacheMs = options.cacheMs ?? CACHE_MS;
+  const fresh = now() - state.lastCheck < cacheMs;
+  if (fresh && !options.bypassCache) return { state, updated: false };
+
+  const latest = await fetchLatestVersion("cli", { fetch: options.fetch, timeoutMs: options.timeoutMs });
+  if (!latest) return { state, updated: false };
+
+  return {
+    state: {
+      ...state,
+      lastCheck: now(),
+      latestVersion: latest.version,
+      securityFlagged: latest.securityFlagged,
+      installer: state.installer === "unknown" ? detectInstaller(options.argv1) : state.installer,
+    },
+    updated: true,
+  };
+}

package/src/notifier/installer.ts

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * Detect which package manager installed the `pithy` binary and, from that, the exact upgrade command to
+ * offer. Ships docs/CLI.md §5.3 verbatim: path-based detection over `process.argv[1]`, order-sensitive so
+ * the `.bun`/`.deno` install roots win before the generic `node_modules` npm test. Detection runs once and
+ * is cached in the notifier state file — a binary's install location doesn't change under it.
+ */
+
+/** The package managers Pithy recognizes, plus `unknown` for anything unmatched (which falls back to npm). */
+export type Installer = "npm" | "pnpm" | "yarn" | "bun" | "deno" | "brew" | "unknown";
+
+/**
+ * Detect the installer from a binary path (defaults to `process.argv[1]`). Backslashes are normalized to
+ * forward slashes first so a Windows path matches the same tests. Order matters: `.bun`/`.deno` roots are
+ * tested before the generic npm `node_modules` catch, and Homebrew before yarn.
+ */
+export function detectInstaller(argv1: string = process.argv[1] ?? ""): Installer {
+  const binPath = argv1.replace(/\\/g, "/");
+
+  if (binPath.includes("/.bun/")) return "bun";
+  if (binPath.includes("/.deno/")) return "deno";
+  if (/\/pnpm\/|\/\.pnpm\//.test(binPath)) return "pnpm";
+  if (/\/(?:home|linux)brew\/|\/Cellar\//.test(binPath)) return "brew";
+  if (/\/\.yarn\/|\/yarn\/global\//.test(binPath)) return "yarn";
+  if (/\/npm\/|\/node_modules\//.test(binPath)) return "npm";
+
+  return "unknown";
+}
+
+/** The upgrade command for an installer. `npm`/`unknown` fall back to a global npm install — anyone with Node has npm. */
+export function upgradeCommandFor(installer: Installer): string {
+  switch (installer) {
+    case "bun":
+      return "bun update -g @pithy-sh/cli";
+    case "pnpm":
+      return "pnpm update -g @pithy-sh/cli";
+    case "yarn":
+      return "yarn global upgrade @pithy-sh/cli";
+    case "deno":
+      return "deno install --reload -g -A -n pithy npm:@pithy-sh/cli";
+    case "brew":
+      return "brew upgrade pithy";
+    default:
+      return "npm i -g @pithy-sh/cli";
+  }
+}

package/src/notifier/notify.ts

@@ -0,0 +1,152 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { saffron } from "../terminal/style";
+import { type FetchLike, refreshCliState } from "./check";
+import { type Installer, upgradeCommandFor } from "./installer";
+import { readState, stateFilePath, writeState } from "./state";
+import { type Bump, classifyBump, parseVersion } from "./version";
+
+/**
+ * The end-of-command update notice (docs/CLI.md §5.2): its suppression rules, its exact stderr strings, and
+ * {@link runUpdateNotifier} — the fire-and-forget entry point `bin.ts` calls after a command's primary work.
+ * The check is `setImmediate`-scheduled so it never blocks the command, silent on every failure, and the
+ * notice prints to stderr only when every suppression rule holds.
+ */
+
+/** The inputs the four suppression rules read. All must hold for the notice to print. */
+export interface SuppressionInput {
+  /** `process.stderr.isTTY` — piped/CI output suppresses the whole notice. */
+  isTTY: boolean;
+  /** Environment map — `PITHY_NO_UPDATE_NOTIFIER` (any value) suppresses. */
+  env: NodeJS.ProcessEnv;
+  /** The state opt-out flag: `false` suppresses. */
+  notifierEnabled: boolean;
+  /** The version gap. */
+  bump: Bump;
+  /** Whether the latest release is security-flagged (lets a patch bump through). */
+  securityFlagged: boolean;
+}
+
+/**
+ * Whether the update notice may print. Every rule must hold: stderr is a TTY, `PITHY_NO_UPDATE_NOTIFIER`
+ * is unset, the state flag is enabled, and the bump is minor/major (or a security-flagged patch). A plain
+ * patch is suppressed — patch noise trains users to ignore the surface. `NO_COLOR` is deliberately not a
+ * rule here: it only drops the accent (handled by the `saffron` seam), never suppresses.
+ */
+export function shouldNotify(input: SuppressionInput): boolean {
+  if (!input.isTTY) return false;
+  if (input.env.PITHY_NO_UPDATE_NOTIFIER) return false;
+  if (!input.notifierEnabled) return false;
+  if (input.bump === "minor" || input.bump === "major") return true;
+  if (input.bump === "patch" && input.securityFlagged) return true;
+  return false;
+}
+
+/** Parameters for the notice string. `accent` is the saffron seam, injectable so tests can assert placement. */
+export interface NoticeInput {
+  installed: string;
+  latest: string;
+  installer: Installer;
+  bump: Bump;
+  accent?: (text: string) => string;
+}
+
+/**
+ * Build the stderr notice. Starts with a blank line (it follows the command's `Done.`). The new version and
+ * the word `available` carry the accent; a major bump adds the `(Major release — see changelog.)` note and a
+ * `Changelog:` line pointing at `https://pithy.sh/changelog/<newMajor>.0`.
+ */
+export function formatUpdateNotice(input: NoticeInput): string {
+  const accent = input.accent ?? saffron;
+  const command = upgradeCommandFor(input.installer);
+  const major = parseVersion(input.latest)?.major ?? 0;
+
+  const lead = `pithy ${accent(input.latest)} ${accent("available")}. You have ${input.installed}.`;
+  const lines = [""];
+  if (input.bump === "major") {
+    lines.push(`${lead} (Major release — see changelog.)`);
+    lines.push(`Update: ${command}`);
+    lines.push(`Changelog: https://pithy.sh/changelog/${major}.0`);
+  } else {
+    lines.push(lead);
+    lines.push(`Update: ${command}`);
+  }
+  return lines.join("\n");
+}
+
+/** Options for {@link runUpdateNotifier} — every side-effecting dependency is injectable for tests. */
+export interface RunUpdateNotifierOptions {
+  /** The currently-running CLI version (from the CLI's own package.json). */
+  installedVersion: string;
+  /** Injected `fetch`; defaults to the global. */
+  fetch?: FetchLike;
+  /** The clock; defaults to `Date.now`. */
+  now?: () => number;
+  /** Override the state file path (defaults to the resolved `~/.config/pithy/state.json`). */
+  stateFile?: string;
+  /** `process.argv[1]`, for one-time installer detection. */
+  argv1?: string;
+  /** Environment map; defaults to `process.env`. */
+  env?: NodeJS.ProcessEnv;
+  /** Whether stderr is a TTY; defaults to `process.stderr.isTTY`. */
+  isTTY?: boolean;
+  /** stderr writer; defaults to writing to `process.stderr`. */
+  stderr?: (text: string) => void;
+  /** Scheduler; defaults to `setImmediate` — the notice fires after the command's work. */
+  schedule?: (fn: () => void) => void;
+  /** The accent seam; defaults to `saffron`. */
+  accent?: (text: string) => string;
+}
+
+/**
+ * The background job: refresh the state within the 24-hour gate, persist it when a check succeeded, then
+ * print the notice if every suppression rule holds. Every failure is swallowed by the caller's `.catch`.
+ */
+async function notifierJob(options: RunUpdateNotifierOptions): Promise<void> {
+  const file = options.stateFile ?? stateFilePath();
+  const now = options.now ?? Date.now;
+  const env = options.env ?? process.env;
+  const isTTY = options.isTTY ?? Boolean(process.stderr.isTTY);
+  const write = options.stderr ?? ((text: string) => void process.stderr.write(text));
+
+  const current = await readState(file);
+  const { state, updated } = await refreshCliState(current, {
+    fetch: options.fetch,
+    now,
+    argv1: options.argv1,
+  });
+  if (updated) await writeState(file, state);
+
+  if (!state.latestVersion) return;
+  const bump = classifyBump(options.installedVersion, state.latestVersion);
+  const eligible = shouldNotify({
+    isTTY,
+    env,
+    notifierEnabled: state.notifier,
+    bump,
+    securityFlagged: state.securityFlagged ?? false,
+  });
+  if (!eligible) return;
+
+  const notice = formatUpdateNotice({
+    installed: options.installedVersion,
+    latest: state.latestVersion,
+    installer: state.installer,
+    bump,
+    accent: options.accent,
+  });
+  write(`${notice}\n`);
+}
+
+/**
+ * Fire the update notifier — the entry point `bin.ts` calls after the command's primary work. Returns
+ * immediately: the check is scheduled via `setImmediate` (so the command's output, including `Done.`, is
+ * already flushed) and runs fire-and-forget, with every error swallowed. It never blocks or delays exit.
+ */
+export function runUpdateNotifier(options: RunUpdateNotifierOptions): void {
+  const schedule = options.schedule ?? setImmediate;
+  schedule(() => {
+    void notifierJob(options).catch(() => {});
+  });
+}

package/src/notifier/state.ts

@@ -0,0 +1,248 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { mkdir, readFile } from "node:fs/promises";
+import { homedir as osHomedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { ConflictError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { assertValidProjectName, kebab } from "@pithy-sh/core/src/naming/resource";
+import { z } from "zod";
+import { writeFileAtomic } from "../project/atomic";
+
+/**
+ * The update-notifier state file (docs/CLI.md §5.1). One small JSON document under the user's config dir
+ * that caches the last registry check so the notifier stays within its 24-hour cadence, remembers the
+ * detected installer (so it isn't re-derived every run), and carries the opt-out flag. It is advisory,
+ * never load-bearing: a missing or corrupt file resolves to a safe default rather than breaking the CLI.
+ */
+export const NotifierState = z
+  .object({
+    lastCheck: z
+      .number()
+      .int()
+      .nonnegative()
+      .describe("Epoch-ms timestamp of the last registry check — the 24-hour cache gate compares against it."),
+    latestVersion: z
+      .string()
+      .nullable()
+      .describe("The latest CLI version the last successful check saw, or null before any check succeeded."),
+    installer: z
+      .enum(["npm", "pnpm", "yarn", "bun", "deno", "brew", "unknown"])
+      .describe("The package manager that installed the binary — detected once, cached, drives the upgrade command."),
+    notifier: z
+      .boolean()
+      .describe("Notifier opt-out state: true is enabled, false suppresses the update notice (set via pithy doctor)."),
+    securityFlagged: z
+      .boolean()
+      .optional()
+      .describe("Whether the latest release carries a `pithy:security` marker — lets a patch bump notify anyway."),
+  })
+  .describe(
+    "Cached update-notifier state (~/.config/pithy/state.json): last check, latest version, installer, opt-out.",
+  );
+export type NotifierState = z.output<typeof NotifierState>;
+
+/** The safe default returned when the state file is missing, malformed, or fails validation. Never throws. */
+export function defaultState(): NotifierState {
+  return { lastCheck: 0, latestVersion: null, installer: "unknown", notifier: true };
+}
+
+/** Injectable environment seams so path resolution is testable without touching the real HOME/APPDATA. */
+export interface StatePathOptions {
+  /** The platform, defaulting to `process.platform`. */
+  platform?: NodeJS.Platform;
+  /** Environment map, defaulting to `process.env` (read for `PITHY_CONFIG_DIR` / `XDG_CONFIG_HOME` / `APPDATA`). */
+  env?: NodeJS.ProcessEnv;
+  /** The user's home directory, defaulting to `os.homedir()`. */
+  homedir?: string;
+}
+
+/**
+ * The one environment variable that relocates everything Pithy keeps per machine — the notifier state,
+ * `<project>/dev.json`, and `<project>/secrets.jsonc`.
+ *
+ * **Required, not a convenience (#156).** Dev secrets live under this directory now, so without an
+ * override every test that scaffolds a project called `replay` writes to the operator's real file, and
+ * CI — which has no home directory worth writing to — writes to whatever `$HOME` happens to be. One
+ * variable moves the whole tree, which is also what makes per-worktree isolation a later configuration
+ * change rather than a redesign.
+ */
+const CONFIG_DIR_ENV = "PITHY_CONFIG_DIR";
+
+/**
+ * The one way a test may resolve the operator's real config directory: say so, in the environment, and
+ * mean it. Any non-blank value.
+ *
+ * It exists so {@link stateDir}'s refusal is a rule rather than a wall — a suite that genuinely needs the
+ * real location has an answer, and it is one line a reviewer can see. Nothing in this repository sets it,
+ * and `packages/cli/src/ci/testIsolation.test.ts` fails if a vitest config ever does: granting the
+ * exemption to one suite is a decision, granting it to a whole package is an accident waiting.
+ */
+const ALLOW_REAL_ENV = "PITHY_ALLOW_REAL_CONFIG_DIR";
+
+/**
+ * Whether this process is a vitest run.
+ *
+ * Two signals, because either alone has a gap. `VITEST` is set in every worker and is inherited by a CLI
+ * this suite spawns — which is the point, since a spawned `pithy` inherits `PITHY_CONFIG_DIR` with it.
+ * `__vitest_worker__` is on the runner's `globalThis` and survives a test that hands product code a
+ * curated environment, which the variable does not.
+ */
+function underVitest(): boolean {
+  if ((process.env.VITEST ?? "").length > 0) return true;
+  return "__vitest_worker__" in globalThis;
+}
+
+/**
+ * Refuse to answer with the operator's own machine.
+ *
+ * Called at each point where the resolution is about to read something the caller did not choose:
+ * `process.env` is the operator's shell, `os.homedir()` is their home directory. Outside vitest both are
+ * exactly the right answer, so this returns and the resolver carries on.
+ */
+function refuseRealDirectory(env: NodeJS.ProcessEnv, detail: string): void {
+  if (!underVitest()) return;
+  const allowed = env[ALLOW_REAL_ENV];
+  if (allowed !== undefined && allowed.trim().length > 0) return;
+  throw new ConflictError({
+    message: `A test asked for the real Pithy config directory. Set ${CONFIG_DIR_ENV} to a throwaway directory instead.`,
+    action: `Pass \`paths\`/\`StatePathOptions\` at the call site, or let the repo-root \`vitest.setup.ts\` set ${CONFIG_DIR_ENV}. A suite that means the operator's own directory sets ${ALLOW_REAL_ENV}=1.`,
+    detail: `stateDir() refused under vitest: ${detail}. That directory holds minted dev master keys and account credentials — #200.`,
+  });
+}
+
+/** The home directory to resolve against. Refuses to hand back the operator's under vitest. */
+function homeDirectory(options: StatePathOptions, env: NodeJS.ProcessEnv): string {
+  if (options.homedir !== undefined) return options.homedir;
+  refuseRealDirectory(env, "no injected homedir, so the answer would be the operator's home directory");
+  return osHomedir();
+}
+
+/**
+ * The Pithy config directory: `$PITHY_CONFIG_DIR` when set, else `%APPDATA%\pithy` on Windows,
+ * `$XDG_CONFIG_HOME/pithy` when that is set, else `~/.config/pithy`. This is the exact directory
+ * `pithy doctor` reports (tilde-abbreviated).
+ *
+ * **The override is the directory itself, with no `pithy` segment appended.** `XDG_CONFIG_HOME` names a
+ * config *root* shared with every other program, so Pithy has to claim a subdirectory of it; this names
+ * Pithy's own directory, so appending would make `PITHY_CONFIG_DIR=/tmp/x` resolve to `/tmp/x/pithy` and
+ * every harness that reads `$PITHY_CONFIG_DIR/<project>/secrets.jsonc` back would find nothing.
+ *
+ * **Absolute, always.** A relative value is resolved against the cwd once, here — every error raised
+ * about a file under this directory names its absolute path, and a relative root would make that path
+ * mean a different place in each command that resolves its own working directory. Blank is no override:
+ * an unset variable and one exported empty by a shell script are the same intention.
+ *
+ * **Under vitest it refuses rather than resolve the operator's own machine (#200).** This is the single
+ * resolver — dev secrets, dev preferences, `cloudflare.json` and the notifier state all come through
+ * here — which is what makes the invariant checkable in one place. A test may answer with
+ * `PITHY_CONFIG_DIR`, or with seams that supply whatever the resolution needs; it may not answer with
+ * `process.env` or `os.homedir()`, because a test chose neither. A suite that means the real directory
+ * sets {@link ALLOW_REAL_ENV}. Outside vitest nothing changes, and a real `pithy` run never sees this.
+ */
+export function stateDir(options: StatePathOptions = {}): string {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+
+  const override = env[CONFIG_DIR_ENV];
+  if (override !== undefined && override.trim().length > 0) return resolve(override);
+
+  // No override, and the environment about to decide the answer is the operator's shell rather than one
+  // the caller built. Everything below this line would be their machine.
+  if (options.env === undefined) {
+    refuseRealDirectory(env, `${CONFIG_DIR_ENV} is unset and no environment was injected`);
+  }
+
+  if (platform === "win32") {
+    const appData = env.APPDATA ?? join(homeDirectory(options, env), "AppData", "Roaming");
+    return join(appData, "pithy");
+  }
+  const xdg = env.XDG_CONFIG_HOME;
+  return xdg ? join(xdg, "pithy") : join(homeDirectory(options, env), ".config", "pithy");
+}
+
+/** The state file path: `<stateDir>/state.json`. */
+export function stateFilePath(options: StatePathOptions = {}): string {
+  return join(stateDir(options), "state.json");
+}
+
+/**
+ * `<config>/<project>/` — **the one door a project name goes through to become a directory**, and the
+ * one place the rule that it may is stated (#212).
+ *
+ * That directory holds every dev secret a project has: `secrets.jsonc`, `dev.json`, `tokens.json`, and
+ * since #206 the account-scoped credentials sit beside it. The gates that guard project writes do not
+ * reach it — `ensureScaffoldPath` guards writes *inside a project*, and this path is in the config
+ * directory, outside every checkout. There is no second line of defense, so the join states its own.
+ *
+ * **It was safe before this, and that is the point.** Every caller passes a name already through
+ * `requireProjectName` or `kebab`. What was missing is where the rule *lived*: at each call site, which
+ * is the #183 shape — #171 narrowed a manifest's default values, #174 an option's key and describe, #183
+ * the capability's own name, three rounds for one rule that was never stated where it belonged. A caller
+ * that is safe because it happens to have normalized earlier is safe by a property of the call graph,
+ * and #206 added a caller to this family within a day of the last one.
+ *
+ * **Two halves, because a name arrives two ways (#206).** {@link assertValidProjectName} is read *after*
+ * kebabbing, deliberately: `Acme Corp` is a legal project name because it *becomes* `acme-corp`. So it
+ * is a statement about the slug, not about the string in hand — `My/Project` passes it whole, and joined
+ * verbatim it is two path segments. The second half is that the value **is** its own normalized form, so
+ * the typed name and the slug are held to one rule rather than the rule being true of only one of them.
+ */
+export function projectConfigDir(project: string, options: StatePathOptions = {}): string {
+  return join(stateDir(options), projectConfigSegment(project));
+}
+
+/**
+ * The validator every config string passes before it is joined into the config directory.
+ *
+ * Separate from the join because that is what the gate in `./state.test.ts` can see: the invariant is
+ * "no config string is joined into the config directory without passing a validator", stated that way
+ * rather than as a list of the joiners known today — enumerating is what produced the second and third
+ * instance of every other class of this in the tree.
+ *
+ * A `ValidationError`, and it names the value: a project name is something a human typed into
+ * `pithy.config.ts`, and it is not a secret.
+ */
+export function projectConfigSegment(project: string): string {
+  assertValidProjectName(project);
+  if (project !== kebab(project)) {
+    throw new ValidationError({
+      message: `"${project}" can't be a directory name.`,
+      action: "Use the normalized project name — lowercase letters, digits, and single hyphens.",
+      detail: `"${project}" is a valid project name only after kebabbing to "${kebab(project)}", and it is joined into the Pithy config directory verbatim. Pass the name requireProjectName returns.`,
+    });
+  }
+  return project;
+}
+
+/**
+ * Read and validate the state file. A missing file, malformed JSON, or a payload that fails validation all
+ * resolve to {@link defaultState} — a corrupt state file must never break the CLI (docs/CLI.md §5.1). A
+ * hand-edited `"notifier": false` is honored, since it round-trips through the same schema.
+ */
+export async function readState(file: string): Promise<NotifierState> {
+  let raw: string;
+  try {
+    raw = await readFile(file, "utf8");
+  } catch {
+    return defaultState();
+  }
+  try {
+    return NotifierState.parse(JSON.parse(raw));
+  } catch {
+    return defaultState();
+  }
+}
+
+/** Write the state file atomically, creating its directory on first write. Validates before writing. */
+export async function writeState(file: string, state: NotifierState): Promise<void> {
+  const validated = NotifierState.parse(state);
+  await mkdir(dirname(file), { recursive: true });
+  await writeFileAtomic(file, `${JSON.stringify(validated, null, 2)}\n`);
+}
+
+/** Set the notifier opt-out flag in the state file, preserving every other field. Used by `pithy doctor`. */
+export async function setNotifierFlag(file: string, enabled: boolean): Promise<void> {
+  const state = await readState(file);
+  await writeState(file, { ...state, notifier: enabled });
+}

package/src/notifier/version.ts

@@ -0,0 +1,59 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * Version comparison for the update notifier — the core semver primitive, deliberately narrowed.
+ *
+ * `@pithy-sh/core/src/semver/semver` parses and orders full semver, prereleases included. This module
+ * keeps only `major.minor.patch`, because the notifier decides between "notify" and "stay quiet", not
+ * which prerelease channel somebody is on: nagging a user on the stable channel about an `rc.1` is the
+ * defect, and dropping the prerelease field is how it is prevented (docs/CLI.md §5).
+ *
+ * The narrowing is here rather than in the primitive, so the one place that wants it is the one place
+ * that has it.
+ */
+
+import { compareSemver, parseSemver } from "@pithy-sh/core/src/semver/semver";
+
+/** The kind of version gap between the installed CLI and the latest published one. */
+export type Bump = "none" | "patch" | "minor" | "major";
+
+/** A parsed semver triple; `null` when the string isn't a recognizable `x.y.z`. */
+interface Parsed {
+  major: number;
+  minor: number;
+  patch: number;
+}
+
+/** Parse `x.y.z` (leading `v` and any `-prerelease`/`+build` suffix ignored). `null` when unparseable. */
+export function parseVersion(version: string): Parsed | null {
+  const parsed = parseSemver(version);
+  if (!parsed) return null;
+  // The prerelease is dropped here rather than carried and ignored downstream. A `Parsed` that held it
+  // would be a `Parsed` some later caller compared, which is the nagging this module exists to avoid.
+  return { major: parsed.major, minor: parsed.minor, patch: parsed.patch };
+}
+
+/** `-1 | 0 | 1` for `a` vs `b`. Unparseable versions sort as equal (the safe, quiet default). */
+export function compareVersions(a: string, b: string): -1 | 0 | 1 {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  if (!pa || !pb) return 0;
+  const order = compareSemver({ ...pa, prerelease: null }, { ...pb, prerelease: null });
+  return order === 0 ? 0 : order > 0 ? 1 : -1;
+}
+
+/**
+ * Classify the gap from `installed` to `latest`. `none` when the installed version is at or ahead of the
+ * latest (nothing to offer). Otherwise the highest-order component that changed: a new major is `major`,
+ * a new minor within the same major is `minor`, anything else is `patch`. An unparseable pair is `none`.
+ */
+export function classifyBump(installed: string, latest: string): Bump {
+  const from = parseVersion(installed);
+  const to = parseVersion(latest);
+  if (!from || !to) return "none";
+  if (compareVersions(latest, installed) <= 0) return "none";
+  if (to.major > from.major) return "major";
+  if (to.minor > from.minor) return "minor";
+  return "patch";
+}