@raidiant/notifai 8.0.0 → 9.1.0

package/dist/url-policy.js

@@ -0,0 +1,369 @@
+import { lookup as dnsLookup } from 'node:dns/promises';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { BlockList, isIP } from 'node:net';
+import { Readable } from 'node:stream';
+/**
+ * The URL trust policy: which network destinations this CLI will touch on
+ * input it did not author. `docs/TRUST.md` is the written policy; this module
+ * is its enforcement, and the two must change together.
+ *
+ * The threat is not a hostile user — it is hostile *input* reaching a
+ * trusted user's CLI: a cloned repository, a compromised server response, or
+ * an agent following text it found in a working tree. Every rule here is
+ * therefore fail-closed, and every escape hatch resolves only from
+ * configuration layers the User owns — never from a repository.
+ */
+/** The one dashboard origin the shipped service uses for pairing approval. */
+export const CANONICAL_DASHBOARD_ORIGIN = 'https://app.notifai.sh';
+/** Redirect hops a remote image fetch may follow, each re-validated. */
+export const MEDIA_REDIRECT_LIMIT = 3;
+/** One address attempt must not hold an agent command indefinitely. */
+export const MEDIA_FETCH_TIMEOUT_MS = 15_000;
+/**
+ * Normalize one configured origin entry to `scheme://host[:port]`, or null
+ * when the entry is not a bare http(s) origin. Paths, queries, fragments, and
+ * userinfo are rejected rather than stripped: a config entry that carries
+ * them says the author expected them to matter, and silently ignoring parts
+ * of a trust rule is how allowlists rot.
+ */
+export function normalizeOrigin(entry) {
+    let url;
+    try {
+        url = new URL(entry);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+        return null;
+    if (url.username !== '' || url.password !== '')
+        return null;
+    if (url.pathname !== '/' || url.search !== '' || url.hash !== '')
+        return null;
+    // `https://*.example` parses, and would then match exactly one impossible
+    // host while reading like a wildcard. Refusing it is how someone finds out
+    // that origins are exact before they trust one that never matches.
+    if (!/^(?:[a-z0-9-]+(?:\.[a-z0-9-]+)*|\[[0-9a-f:.]+\])$/i.test(url.hostname))
+        return null;
+    return url.origin;
+}
+/**
+ * Addresses that are not publicly routable: loopback, RFC 1918, link-local
+ * (including cloud metadata at 169.254.169.254), CGNAT, benchmark,
+ * documentation, multicast, and reserved space; for IPv6 also unspecified,
+ * unique-local, site-local, and discard prefixes. IPv4-mapped IPv6 addresses
+ * are classified as the IPv4 address they carry.
+ */
+const NON_PUBLIC = new BlockList();
+const PUBLIC_IPV6 = new BlockList();
+PUBLIC_IPV6.addSubnet('2000::', 3, 'ipv6');
+for (const [subnet, prefix] of [
+    ['0.0.0.0', 8],
+    ['10.0.0.0', 8],
+    ['100.64.0.0', 10],
+    ['127.0.0.0', 8],
+    ['169.254.0.0', 16],
+    ['172.16.0.0', 12],
+    ['192.0.0.0', 24],
+    ['192.0.2.0', 24],
+    ['192.88.99.0', 24],
+    ['192.168.0.0', 16],
+    ['198.18.0.0', 15],
+    ['198.51.100.0', 24],
+    ['203.0.113.0', 24],
+    ['224.0.0.0', 4],
+    ['240.0.0.0', 4],
+]) {
+    NON_PUBLIC.addSubnet(subnet, prefix, 'ipv4');
+}
+for (const [subnet, prefix] of [
+    ['::', 128],
+    ['::1', 128],
+    ['64:ff9b::', 96], // NAT64 — fail closed rather than trust the embedded address
+    ['64:ff9b:1::', 48],
+    ['100::', 64],
+    ['2001::', 32], // Teredo embeds an IPv4 destination
+    ['2001:2::', 48],
+    ['2001:10::', 28],
+    ['2001:20::', 28],
+    ['2001:db8::', 32],
+    ['2002::', 16], // 6to4 embeds an IPv4 address; fail closed
+    ['3fff::', 20],
+    ['fc00::', 7],
+    ['fe80::', 10],
+    ['fec0::', 10],
+    ['ff00::', 8],
+    // Deliberately no `::ffff:0:0/96` rule: Node checks an IPv4 address against
+    // IPv6 rules through its own IPv4-mapped form, so that entry would classify
+    // every address on the internet as private. `mappedIpv4` handles the mapped
+    // spellings instead.
+]) {
+    NON_PUBLIC.addSubnet(subnet, prefix, 'ipv6');
+}
+/**
+ * The IPv4 address an IPv4-mapped IPv6 address carries, in either spelling:
+ * `::ffff:127.0.0.1` and `::ffff:7f00:1` are the same address, and only the
+ * first would survive being classified as IPv6.
+ */
+function mappedIpv4(address) {
+    const lower = address.toLowerCase();
+    if (!lower.startsWith('::ffff:'))
+        return null;
+    const rest = lower.slice('::ffff:'.length);
+    if (isIP(rest) === 4)
+        return rest;
+    const hex = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(rest);
+    if (hex === null)
+        return null;
+    const high = Number.parseInt(hex[1], 16);
+    const low = Number.parseInt(hex[2], 16);
+    return `${high >> 8}.${high & 0xff}.${low >> 8}.${low & 0xff}`;
+}
+/** Whether one IP literal is publicly routable. */
+export function isPublicAddress(address) {
+    const candidate = mappedIpv4(address) ?? address;
+    const family = isIP(candidate);
+    if (family === 0)
+        return false;
+    // Fail closed outside the currently allocated global-unicast block. This
+    // catches reserved IPv6 space without depending on an inevitably stale
+    // enumeration; explicit exclusions below then carve special-use prefixes
+    // out of global unicast itself.
+    if (family === 6 && !PUBLIC_IPV6.check(candidate, 'ipv6'))
+        return false;
+    return !NON_PUBLIC.check(candidate, family === 6 ? 'ipv6' : 'ipv4');
+}
+/** A URL hostname as an address-or-name: IPv6 hosts arrive bracketed. */
+function hostnameAddress(hostname) {
+    return hostname.startsWith('[') && hostname.endsWith(']')
+        ? hostname.slice(1, -1)
+        : hostname;
+}
+export function isLoopbackHostname(hostname) {
+    const host = hostnameAddress(hostname).toLowerCase();
+    if (host === 'localhost' || host.endsWith('.localhost'))
+        return true;
+    const family = isIP(host);
+    if (family === 4)
+        return host.startsWith('127.');
+    if (family === 6)
+        return host === '::1' || /^::ffff:127\./.test(host);
+    return false;
+}
+async function resolveAddresses(hostname, policy) {
+    if (policy.lookup !== undefined) {
+        try {
+            return await policy.lookup(hostname);
+        }
+        catch {
+            return null;
+        }
+    }
+    try {
+        const results = await dnsLookup(hostname, { all: true, verbatim: true });
+        return results.map((entry) => entry.address);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether one URL is a destination remote media may be fetched from.
+ *
+ * Default policy: `https` to a host every resolved address of which is
+ * publicly routable. A User-allowed origin skips the scheme and address
+ * checks — the User said that exact origin is theirs to trust — but nothing
+ * skips the userinfo refusal, and every redirect hop is checked again.
+ *
+ * The approved addresses come back with the verdict rather than being
+ * rediscovered later: `fetchMediaUrl` connects to one of exactly these, so a
+ * resolver that would answer differently on a second lookup cannot rebind the
+ * request onto a private address between the check and the connection.
+ */
+export async function checkMediaUrl(target, policy) {
+    if (target.username !== '' || target.password !== '') {
+        return { ok: false, reason: 'Image URLs with embedded credentials are never fetched.' };
+    }
+    if (target.protocol !== 'https:' && target.protocol !== 'http:') {
+        return { ok: false, reason: `Only http(s) image URLs are supported, not ${target.protocol.replace(/:$/, '')}.` };
+    }
+    const userAllowed = policy.allowOrigins.includes(target.origin);
+    const escapeHatch = 'Remote images use public HTTPS; for a self-hosted or intranet image server, allow its exact origin with `notifai config set media_origins <origin>`.';
+    if (!userAllowed && target.protocol !== 'https:') {
+        return { ok: false, reason: `${target.origin} is http. ${escapeHatch}` };
+    }
+    const literal = hostnameAddress(target.hostname);
+    if (isIP(literal) !== 0) {
+        return userAllowed || isPublicAddress(literal)
+            ? { ok: true, addresses: [literal] }
+            : { ok: false, reason: `${target.hostname} is not a public address. ${escapeHatch}` };
+    }
+    const addresses = await resolveAddresses(target.hostname, policy);
+    if (addresses === null || addresses.length === 0) {
+        return { ok: false, reason: `Could not resolve ${target.hostname}.` };
+    }
+    if (addresses.some((address) => isIP(address) === 0)) {
+        return { ok: false, reason: `${target.hostname} resolved to an invalid address.` };
+    }
+    if (!userAllowed && !addresses.every((address) => isPublicAddress(address))) {
+        return { ok: false, reason: `${target.hostname} resolves to a non-public address. ${escapeHatch}` };
+    }
+    return { ok: true, addresses };
+}
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+function responseHeaders(response) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(response.headers)) {
+        if (Array.isArray(value)) {
+            for (const entry of value)
+                headers.append(name, entry);
+        }
+        else if (value !== undefined) {
+            headers.set(name, value);
+        }
+    }
+    return headers;
+}
+/**
+ * Fetch through one already-vetted address while retaining the URL hostname
+ * for Host and TLS verification. This closes the DNS-rebinding gap between
+ * policy resolution and the connection: the request cannot resolve the name
+ * a second time to a private address.
+ */
+async function fetchPinned(target, addresses) {
+    let lastError = new Error(`No address was available for ${target.hostname}.`);
+    for (const address of addresses) {
+        try {
+            return await new Promise((resolve, reject) => {
+                const family = isIP(address);
+                const request = (target.protocol === 'https:' ? httpsRequest : httpRequest)(target, {
+                    method: 'GET',
+                    headers: { 'accept-encoding': 'identity' },
+                    signal: AbortSignal.timeout(MEDIA_FETCH_TIMEOUT_MS),
+                    // Node asks for every address at once when it is racing address
+                    // families, and for a single one otherwise. Answering in the wrong
+                    // shape throws inside the connect path rather than failing the
+                    // request, so both forms are answered explicitly.
+                    lookup: (_hostname, options, callback) => {
+                        if (options.all === true) {
+                            callback(null, [{ address, family }]);
+                            return;
+                        }
+                        callback(null, address, family);
+                    },
+                }, (incoming) => {
+                    const status = incoming.statusCode ?? 500;
+                    const hasBody = ![101, 204, 205, 304].includes(status);
+                    const body = hasBody
+                        ? Readable.toWeb(incoming)
+                        : null;
+                    resolve(new Response(body, {
+                        status,
+                        ...(incoming.statusMessage === undefined
+                            ? {}
+                            : { statusText: incoming.statusMessage }),
+                        headers: responseHeaders(incoming),
+                    }));
+                });
+                request.once('error', reject);
+                request.end();
+            });
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw lastError;
+}
+/**
+ * Fetch a remote image under the media URL policy, following at most
+ * `MEDIA_REDIRECT_LIMIT` redirects and re-validating every hop — a public
+ * HTTPS URL redirecting into an intranet is the exact attack the per-hop
+ * check exists for.
+ */
+export async function fetchMediaUrl(source, policy, fetchImpl) {
+    let target;
+    try {
+        target = new URL(source);
+    }
+    catch {
+        return { ok: false, reason: `"${source}" is not a valid URL.` };
+    }
+    for (let hop = 0;; hop += 1) {
+        const allowed = await checkMediaUrl(target, policy);
+        if (!allowed.ok)
+            return allowed;
+        const response = fetchImpl === undefined
+            ? await fetchPinned(target, allowed.addresses)
+            : await fetchImpl(target, { redirect: 'manual' });
+        if (!REDIRECT_STATUSES.has(response.status))
+            return { ok: true, response };
+        const location = response.headers.get('location');
+        await response.body?.cancel();
+        if (location === null) {
+            return { ok: false, reason: `${target.origin} redirected without a destination.` };
+        }
+        if (hop >= MEDIA_REDIRECT_LIMIT) {
+            return { ok: false, reason: `${source} redirected more than ${MEDIA_REDIRECT_LIMIT} times.` };
+        }
+        try {
+            target = new URL(location, target);
+        }
+        catch {
+            return { ok: false, reason: `${target.origin} redirected to an invalid URL.` };
+        }
+    }
+}
+/**
+ * Whether a server-supplied pairing approval URL may be shown and opened.
+ *
+ * The server chooses `approve_url`, so a compromised or misconfigured one
+ * must not be able to drive this machine's browser to an arbitrary
+ * destination. Allowed: the canonical dashboard, the exact origin the user
+ * pointed this pairing at, loopback for local development, and origins the
+ * User allowed (`approve_origins`) for a self-host whose dashboard lives on
+ * a different origin than its API.
+ */
+export function checkApproveUrl(raw, baseUrl, allowOrigins) {
+    let target;
+    try {
+        target = new URL(raw);
+    }
+    catch {
+        return { ok: false, reason: `the server sent an invalid approval URL.` };
+    }
+    if (target.protocol !== 'https:' && target.protocol !== 'http:') {
+        return {
+            ok: false,
+            reason: `the server sent a ${target.protocol.replace(/:$/, '')} approval URL; only http(s) is ever opened.`,
+        };
+    }
+    if (target.username !== '' || target.password !== '') {
+        return { ok: false, reason: 'the server sent an approval URL with embedded credentials.' };
+    }
+    if (target.origin === CANONICAL_DASHBOARD_ORIGIN)
+        return { ok: true };
+    if (isLoopbackHostname(target.hostname))
+        return { ok: true };
+    let pairingOrigin = null;
+    try {
+        pairingOrigin = new URL(baseUrl).origin;
+    }
+    catch {
+        pairingOrigin = null;
+    }
+    if (allowOrigins.includes(target.origin))
+        return { ok: true };
+    if (pairingOrigin !== null &&
+        target.origin === pairingOrigin &&
+        target.protocol === 'https:') {
+        return { ok: true };
+    }
+    return {
+        ok: false,
+        reason: `the server sent an approval URL on ${target.origin}, which is not the Notifai dashboard, ` +
+            'the origin being paired with, loopback, or an origin in `approve_origins`.',
+    };
+}
+//# sourceMappingURL=url-policy.js.map

package/dist/url-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-policy.js","sourceRoot":"","sources":["../src/url-policy.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raidiant/notifai",
-  "version": "8.0.0",
+  "version": "9.1.0",
   "type": "module",
   "description": "Send native device notifications from agents and local programs",
   "bin": {
@@ -13,7 +13,7 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.json",
+    "build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.json && node ../../scripts/chmod-cli-bin.mjs",
     "pretest": "pnpm run build",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "node ../../scripts/run-cli-tests.mjs",
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@raidiant/notifai-protocol": "4.1.0",
+    "@raidiant/notifai-protocol": "5.0.0",
     "commander": "^14.0.0",
     "picocolors": "^1.1.1",
     "smol-toml": "^1.4.0"

package/src/atomic-file.ts

@@ -19,6 +19,12 @@ export interface AtomicWriteOptions {
   preserveMode?: boolean
   /** Reject a target owned by another user instead of replacing it. */
   requireCurrentUserOwner?: boolean
+  /**
+   * POSIX directory mode applied to the parent. Defaults to 0o700 when
+   * `requireCurrentUserOwner` is set so credential and config dirs match the
+   * hook-adapter and log directories.
+   */
+  directoryMode?: number
 }
 
 /**
@@ -34,8 +40,12 @@ export function atomicWriteFileSync(
   options: AtomicWriteOptions = {},
 ): void {
   const directory = path.dirname(file)
-  mkdirSync(directory, { recursive: true })
-  const parent = safeDirectory(directory, options.requireCurrentUserOwner ?? false)
+  const requireCurrentUserOwner = options.requireCurrentUserOwner ?? false
+  const directoryMode = options.directoryMode ?? (requireCurrentUserOwner ? 0o700 : undefined)
+  const parent = ensureDirectory(directory, {
+    requireCurrentUserOwner,
+    ...(directoryMode === undefined ? {} : { mode: directoryMode }),
+  })
   const target = targetMetadata(
     file,
     options.mode ?? 0o600,
@@ -69,6 +79,30 @@ export function atomicWriteFileSync(
   }
 }
 
+/**
+ * Create (or tighten) a directory that must not be world-readable.
+ *
+ * `mkdir` mode applies only to a newly created leaf, so an existing 0755
+ * credential directory would otherwise stay world-listable. POSIX chmod of
+ * the leaf is the matching repair; Windows has no equivalent mode bits.
+ */
+export function ensurePrivateDirectory(directory: string): void {
+  ensureDirectory(directory, { mode: 0o700, requireCurrentUserOwner: false })
+}
+
+function ensureDirectory(
+  directory: string,
+  options: { mode?: number; requireCurrentUserOwner: boolean },
+): { dev: number; ino: number } {
+  if (options.mode === undefined) mkdirSync(directory, { recursive: true })
+  else mkdirSync(directory, { recursive: true, mode: options.mode })
+  const parent = safeDirectory(directory, options.requireCurrentUserOwner)
+  if (options.mode !== undefined && process.platform !== 'win32') {
+    chmodSync(directory, options.mode)
+  }
+  return parent
+}
+
 /** Persist the published directory entry where the host supports directory fsync. */
 function syncDirectory(directory: string): void {
   if (process.platform === 'win32') return

package/src/cli-bin.test.ts

@@ -0,0 +1,38 @@
+import { chmodSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { cliBinReadiness, isExecutablePath, pathNotifaiEntries } from './cli-bin.js'
+
+describe('PATH notifai diagnosis', () => {
+  it('reports a non-executable PATH binary as a gap', () => {
+    if (process.platform === 'win32') return
+    const directory = mkdtempSync(path.join(os.tmpdir(), 'notifai-bin-gap-'))
+    const file = path.join(directory, 'notifai')
+    writeFileSync(file, '#!/usr/bin/env node\n')
+    chmodSync(file, 0o644)
+    expect(isExecutablePath(file, 'darwin')).toBe(false)
+    const state = cliBinReadiness({ PATH: directory }, 'darwin')
+    expect(state.status).toBe('gap')
+    expect(state.detail).toContain(file)
+    expect(state.remedy?.command).toBe('npm install -g @raidiant/notifai')
+  })
+
+  it('treats an executable PATH binary as ready', () => {
+    if (process.platform === 'win32') return
+    const directory = mkdtempSync(path.join(os.tmpdir(), 'notifai-bin-ok-'))
+    const file = path.join(directory, 'notifai')
+    writeFileSync(file, '#!/usr/bin/env node\n')
+    chmodSync(file, 0o755)
+    expect(pathNotifaiEntries({ PATH: directory }, 'darwin')).toEqual([file])
+    expect(cliBinReadiness({ PATH: directory }, 'darwin').status).toBe('ready')
+  })
+
+  it('is ready when PATH has no notifai entry', () => {
+    const directory = mkdtempSync(path.join(os.tmpdir(), 'notifai-bin-empty-'))
+    mkdirSync(directory, { recursive: true })
+    const state = cliBinReadiness({ PATH: directory }, process.platform)
+    expect(state.status).toBe('ready')
+    expect(state.detail).toContain('no notifai binary was on PATH')
+  })
+})

package/src/cli-bin.ts

@@ -0,0 +1,67 @@
+import { accessSync, constants, existsSync, lstatSync, realpathSync } from 'node:fs'
+import path from 'node:path'
+import type { ReadinessState } from './readiness.js'
+
+const POSIX_NAMES = ['notifai']
+const WINDOWS_NAMES = ['notifai.cmd', 'notifai.exe', 'notifai']
+
+export function pathNotifaiEntries(
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform = process.platform,
+): string[] {
+  const raw = platform === 'win32' ? (env['Path'] ?? env['PATH'] ?? '') : (env['PATH'] ?? '')
+  const delimiter = platform === 'win32' ? ';' : ':'
+  const names = platform === 'win32' ? WINDOWS_NAMES : POSIX_NAMES
+  const found: string[] = []
+  for (const directory of raw.split(delimiter)) {
+    if (directory === '') continue
+    for (const name of names) {
+      const candidate = path.join(directory, name)
+      if (!existsSync(candidate)) continue
+      if (!found.includes(candidate)) found.push(candidate)
+    }
+  }
+  return found
+}
+
+export function isExecutablePath(file: string, platform: NodeJS.Platform = process.platform): boolean {
+  if (!existsSync(file)) return false
+  if (platform === 'win32') return true
+  try {
+    const target = lstatSync(file).isSymbolicLink() ? realpathSync(file) : file
+    accessSync(target, constants.X_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function cliBinReadiness(
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform = process.platform,
+): ReadinessState {
+  const entries = pathNotifaiEntries(env, platform)
+  const broken = entries.find((file) => !isExecutablePath(file, platform))
+  if (broken !== undefined) {
+    return {
+      id: 'cli-bin',
+      title: 'notifai command',
+      status: 'gap',
+      detail: `${broken} is on PATH but is not executable`,
+      remedy: {
+        by: 'user-here',
+        summary: 'repair the global notifai command so it can run',
+        command: 'npm install -g @raidiant/notifai',
+      },
+    }
+  }
+  return {
+    id: 'cli-bin',
+    title: 'notifai command',
+    status: 'ready',
+    detail:
+      entries[0] === undefined
+        ? 'this process can run; no notifai binary was on PATH'
+        : `${entries[0]} is executable`,
+  }
+}

package/src/cli-release.test.ts

@@ -0,0 +1,46 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  compareCliSemVer,
+  latestPublishedCliVersion,
+  newerPublishedCli,
+  resetLatestPublishedCliVersionForTest,
+  shouldConsultCliRegistry,
+} from './cli-release.js'
+
+afterEach(() => {
+  resetLatestPublishedCliVersionForTest()
+})
+
+describe('CLI registry recommendation', () => {
+  it('is suppressed for JSON, non-interactive, and CI callers', () => {
+    expect(shouldConsultCliRegistry({ interactive: true })).toBe(true)
+    expect(shouldConsultCliRegistry({ interactive: true, json: true })).toBe(false)
+    expect(shouldConsultCliRegistry({ interactive: false })).toBe(false)
+    expect(shouldConsultCliRegistry({ interactive: true, env: { CI: 'true' } })).toBe(false)
+  })
+
+  it('never throws when the registry is unreachable', async () => {
+    const latest = await latestPublishedCliVersion(async () => {
+      throw new Error('network down')
+    })
+    expect(latest).toBeNull()
+  })
+
+  it('caches a successful dist-tag read', async () => {
+    let calls = 0
+    const fetchImpl: typeof fetch = async () => {
+      calls += 1
+      return new Response(JSON.stringify({ latest: '9.1.0' }), { status: 200 })
+    }
+    expect(await latestPublishedCliVersion(fetchImpl)).toBe('9.1.0')
+    expect(await latestPublishedCliVersion(fetchImpl)).toBe('9.1.0')
+    expect(calls).toBe(1)
+  })
+
+  it('only recommends a strictly newer published version', () => {
+    expect(newerPublishedCli('8.0.0', '8.0.1')).toBe('8.0.1')
+    expect(newerPublishedCli('8.0.0', '8.0.0')).toBeNull()
+    expect(newerPublishedCli('8.0.1', '8.0.0')).toBeNull()
+    expect(compareCliSemVer('8.0.0', '7.0.2')).toBeGreaterThan(0)
+  })
+})