toiljs 0.0.31 → 0.0.33

package/src/cli/index.ts

@@ -9,6 +9,7 @@ import { build, dev, start } from 'toiljs/compiler';
 import { runConfigure } from './configure.js';
 import { runCreate, type Template } from './create.js';
 import { runDoctor } from './doctor.js';
+import { notifyIfOutdated } from './notify.js';
 import { runUpdate } from './update.js';
 import { type Preprocessor, PREPROCESSORS } from './features.js';
 import { accent, banner, bold, danger, dim, success, version } from './ui.js';
@@ -147,6 +148,9 @@ function printHelp(): void {
             cmd('--target <t>', 'update: latest | minor | patch | newest | greatest'),
             cmd('-v, --version', 'print the toiljs version'),
             '',
+            dim('  Every command checks npm for a newer toiljs and warns when outdated.'),
+            dim('  Set TOILJS_NO_UPDATE_CHECK=1 to opt out.'),
+            '',
         ].join('\n') + '\n',
     );
 }
@@ -161,6 +165,11 @@ async function main(): Promise<void> {
 
     const flags = parseArgs(rest);
 
+    // Every invocation (including `npm run dev` / `npm run build`, which call this CLI)
+    // checks that the installed toiljs is the latest release. Warns on stderr, never blocks
+    // the command; opt out with TOILJS_NO_UPDATE_CHECK=1.
+    await notifyIfOutdated(flags.root);
+
     switch (command) {
         case 'create':
             banner();

package/src/cli/notify.ts

@@ -0,0 +1,125 @@
+/**
+ * Automatic update check, run on every CLI invocation (so `npm run dev` / `npm run build`,
+ * which call the toiljs CLI, are covered too). Asks the npm registry for the latest toiljs
+ * release (answer cached for an hour in the user's cache dir, network capped at 2 seconds),
+ * then warns on stderr when the project's installed toiljs or the running CLI is behind.
+ * Never throws and never fails the command. Opt out with TOILJS_NO_UPDATE_CHECK=1 (also
+ * honors NO_UPDATE_NOTIFIER and CI).
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { detectPackageManager } from './update.js';
+import { accent, bold, box, dim, version as cliVersion, warn } from './ui.js';
+import {
+    findOutdated,
+    isCacheFresh,
+    type OutdatedRow,
+    parseCheckCache,
+} from './version-check.js';
+
+const REGISTRY_URL = 'https://registry.npmjs.org/toiljs/latest';
+const FETCH_TIMEOUT_MS = 2000;
+
+/** Where the registry answer is cached: `$XDG_CACHE_HOME`/`~/.cache` + `toiljs/`. */
+function cacheFile(): string {
+    const base = process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), '.cache');
+    return path.join(base, 'toiljs', 'update-check.json');
+}
+
+/** Asks the npm registry for the latest published version; null on any failure. */
+async function fetchLatest(): Promise<string | null> {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => {
+        ctrl.abort();
+    }, FETCH_TIMEOUT_MS);
+    try {
+        const res = await fetch(REGISTRY_URL, {
+            signal: ctrl.signal,
+            headers: { accept: 'application/json' },
+        });
+        if (!res.ok) return null;
+        const data: unknown = await res.json();
+        if (typeof data !== 'object' || data === null) return null;
+        const v = (data as Record<string, unknown>).version;
+        return typeof v === 'string' ? v : null;
+    } catch {
+        return null;
+    } finally {
+        clearTimeout(timer);
+    }
+}
+
+/**
+ * The latest published toiljs version, from the cache when fresh, otherwise from the registry.
+ * Failures are cached too (as null) so an offline machine backs off for the TTL instead of
+ * paying the fetch timeout on every command.
+ */
+async function resolveLatest(): Promise<string | null> {
+    const file = cacheFile();
+    try {
+        const cached = parseCheckCache(fs.readFileSync(file, 'utf8'));
+        if (cached && isCacheFresh(cached, Date.now())) return cached.latest;
+    } catch {}
+    const latest = await fetchLatest();
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify({ latest, checkedAt: Date.now() }));
+    } catch {}
+    return latest;
+}
+
+/** Reads the version of the toiljs resolved in the project's node_modules, if any. */
+function projectToiljsVersion(root: string): string | null {
+    try {
+        const raw = fs.readFileSync(
+            path.join(root, 'node_modules', 'toiljs', 'package.json'),
+            'utf8',
+        );
+        const parsed: unknown = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null) return null;
+        const v = (parsed as Record<string, unknown>).version;
+        return typeof v === 'string' ? v : null;
+    } catch {
+        return null;
+    }
+}
+
+function noticeLines(latest: string, rows: OutdatedRow[]): string {
+    const header = warn('⚠ ') + bold(`a newer toiljs is available: ${accent(latest)}`);
+    const body = rows.map((row) => {
+        const where = row.scope === 'project' ? 'this project has' : 'your global CLI is';
+        return `${where} ${row.installed}${dim(', update with')} ${accent(row.command)}`;
+    });
+    return '\n' + box([header, '', ...body], warn) + '\n';
+}
+
+/**
+ * Checks the project install and the running CLI against the latest release and prints a
+ * warning to stderr when either is behind. Safe to await unconditionally: bounded by the
+ * cache TTL + fetch timeout, and it swallows every error.
+ */
+export async function notifyIfOutdated(rootArg: string | undefined): Promise<void> {
+    try {
+        const env = process.env;
+        if (env.TOILJS_NO_UPDATE_CHECK || env.NO_UPDATE_NOTIFIER || env.CI) return;
+
+        const latest = await resolveLatest();
+        if (!latest) return;
+
+        const root = path.resolve(rootArg ?? process.cwd());
+        const cliDir = path.dirname(fileURLToPath(import.meta.url));
+        const cliIsLocal = cliDir.startsWith(path.join(root, 'node_modules') + path.sep);
+        const rows = findOutdated(
+            latest,
+            projectToiljsVersion(root),
+            cliVersion(),
+            cliIsLocal,
+            detectPackageManager(root).name,
+        );
+        if (rows.length === 0) return;
+        process.stderr.write(noticeLines(latest, rows));
+    } catch {}
+}

package/src/cli/ui.ts

@@ -102,10 +102,69 @@ export function version(): string {
     return '0.0.0';
 }
 
-/** Prints the brand banner: gradient logo + tagline + version. */
+// eslint-disable-next-line no-control-regex -- matching our own escape sequences is the point
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+/** The on-screen width of `s`, ignoring ANSI color codes. */
+function visibleWidth(s: string): number {
+    return s.replace(ANSI_RE, '').length;
+}
+
+/**
+ * Frames already-colored lines in a rounded box sized to the widest line. `paint` colors the
+ * border (the content keeps its own colors); padding is measured on the visible text, so ANSI
+ * codes inside the lines never skew the right edge. Returns the box without a trailing newline.
+ */
+export function box(lines: readonly string[], paint: (s: string) => string = (s) => s): string {
+    const width = lines.reduce((w, l) => Math.max(w, visibleWidth(l)), 0);
+    const side = paint('│');
+    const body = lines.map(
+        (l) => `  ${side}  ${l}${' '.repeat(width - visibleWidth(l))}  ${side}`,
+    );
+    return [
+        '  ' + paint(`╭${'─'.repeat(width + 4)}╮`),
+        ...body,
+        '  ' + paint(`╰${'─'.repeat(width + 4)}╯`),
+    ].join('\n');
+}
+
+/**
+ * Banner taglines, one is picked at random per invocation. Each is a function so the accented
+ * words pick up the brand color (or stay plain when color is disabled). The theme: TOIL is the
+ * first full-stack framework for a globally distributed application delivery network.
+ */
+const TAGLINES: ReadonlyArray<(a: (s: string) => string) => string> = [
+    (a) => `the most performant ${a('react')} framework`,
+    (a) => `bringing ${a('hyper scale')} to anyone`,
+    (a) => `the first full-stack ${a('application delivery network')}`,
+    (a) => `your app, ${a('globally distributed')} by default`,
+    (a) => `one build, ${a('the whole planet')}`,
+    (a) => `full stack, ${a('zero distance')} to your users`,
+    (a) => `${a('react')} up front, ${a('wasm')} at every edge`,
+    (a) => `deployed where your ${a('users')} are`,
+    (a) => `the framework with a ${a('delivery network')} built in`,
+    (a) => `no regions, just ${a('the world')}`,
+    (a) => `${a('planet-scale')} apps from a single repo`,
+    (a) => `every request served ${a('next door')}`,
+    (a) => `frontend, backend, ${a('worldwide')}`,
+    (a) => `${a('hyper scale')} without the ops team`,
+    (a) => `your backend, ${a('compiled to wasm')}, running everywhere`,
+    (a) => `the internet is your ${a('runtime')}`,
+    (a) => `the speed of light is the ${a('only bottleneck')}`,
+    (a) => `static speed, ${a('dynamic everything')}`,
+    (a) => `scale to ${a('millions')} before lunch`,
+    (a) => `latency is a choice, choose ${a('zero')}`,
+    (a) => `build ${a('better')}, ship ${a('faster')}`,
+];
+
+/** A random brand tagline, accent words colored. */
+export function tagline(): string {
+    return TAGLINES[Math.floor(Math.random() * TAGLINES.length)](brand);
+}
+
+/** Prints the brand banner: gradient logo + random tagline + version. */
 export function banner(): void {
     const lines = colorEnabled() ? ART.map(gradientLine) : ART.slice();
-    const tagline = `  the most performant ${brand('react')} framework`;
     const ver = `${dim('  v')}${brand(version())}`;
-    process.stdout.write('\n' + lines.join('\n') + '\n\n' + tagline + '   ' + ver + '\n\n');
+    process.stdout.write('\n' + lines.join('\n') + '\n\n  ' + tagline() + '   ' + ver + '\n\n');
 }

package/src/cli/update.ts

@@ -22,13 +22,13 @@ export interface UpdateOptions {
     readonly target?: string;
 }
 
-interface PackageManager {
+export interface PackageManager {
     readonly name: string;
     readonly ncuName: string;
 }
 
 /** Detects the package manager from the project's lockfile (defaults to npm). */
-function detectPackageManager(root: string): PackageManager {
+export function detectPackageManager(root: string): PackageManager {
     if (fs.existsSync(path.join(root, 'pnpm-lock.yaml'))) return { name: 'pnpm', ncuName: 'pnpm' };
     if (fs.existsSync(path.join(root, 'yarn.lock'))) return { name: 'yarn', ncuName: 'yarn' };
     if (fs.existsSync(path.join(root, 'bun.lockb'))) return { name: 'bun', ncuName: 'bun' };

package/src/cli/version-check.ts

@@ -0,0 +1,121 @@
+/**
+ * Pure helpers for the automatic toiljs update check that runs on every CLI invocation
+ * (and therefore on `npm run dev` / `npm run build`, which call the CLI). IO-free so it
+ * can be unit-tested; the registry fetch, cache file, and printing live in `notify.ts`.
+ */
+
+/** How long a registry answer is trusted before we ask npm again. */
+export const CHECK_TTL_MS = 60 * 60 * 1000;
+
+/** What we persist between runs: the latest known version and when we asked. */
+export interface CheckCache {
+    readonly latest: string | null;
+    readonly checkedAt: number;
+}
+
+/** Parses the cache file contents; returns null when malformed (forces a fresh check). */
+export function parseCheckCache(raw: string): CheckCache | null {
+    try {
+        const parsed: unknown = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null) return null;
+        const o = parsed as Record<string, unknown>;
+        const latest = typeof o.latest === 'string' ? o.latest : null;
+        const checkedAt = typeof o.checkedAt === 'number' ? o.checkedAt : NaN;
+        if (!Number.isFinite(checkedAt)) return null;
+        return { latest, checkedAt };
+    } catch {
+        return null;
+    }
+}
+
+/** True when the cached answer is still trustworthy (also stale if the clock went backwards). */
+export function isCacheFresh(cache: CheckCache, now: number, ttlMs: number = CHECK_TTL_MS): boolean {
+    return cache.checkedAt <= now && now - cache.checkedAt < ttlMs;
+}
+
+interface Parsed {
+    readonly nums: readonly [number, number, number];
+    readonly pre: string | null;
+}
+
+function parseSemver(v: string): Parsed {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(v.trim());
+    if (!m) return { nums: [0, 0, 0], pre: null };
+    return { nums: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ?? null };
+}
+
+/**
+ * Compares two semver strings: negative when `a < b`, 0 when equal, positive when `a > b`.
+ * A prerelease sorts below its release (`0.1.0-beta.1 < 0.1.0`); two prereleases compare
+ * lexicographically, which is enough for an update nudge.
+ */
+export function compareSemver(a: string, b: string): number {
+    const pa = parseSemver(a);
+    const pb = parseSemver(b);
+    for (let i = 0; i < 3; i++) {
+        if (pa.nums[i] !== pb.nums[i]) return pa.nums[i] < pb.nums[i] ? -1 : 1;
+    }
+    if (pa.pre === pb.pre) return 0;
+    if (pa.pre === null) return 1;
+    if (pb.pre === null) return -1;
+    return pa.pre < pb.pre ? -1 : 1;
+}
+
+/** True when `installed` is behind `latest`. */
+export function isOutdated(installed: string, latest: string): boolean {
+    return compareSemver(installed, latest) < 0;
+}
+
+/** The command that updates toiljs for the project's package manager, or globally. */
+export function installCommand(pm: string, scope: 'project' | 'global'): string {
+    if (scope === 'global') {
+        if (pm === 'pnpm') return 'pnpm add -g toiljs@latest';
+        if (pm === 'yarn') return 'yarn global add toiljs@latest';
+        if (pm === 'bun') return 'bun add -g toiljs@latest';
+        return 'npm install -g toiljs@latest';
+    }
+    if (pm === 'pnpm') return 'pnpm add toiljs@latest';
+    if (pm === 'yarn') return 'yarn add toiljs@latest';
+    if (pm === 'bun') return 'bun add toiljs@latest';
+    return 'npm install toiljs@latest';
+}
+
+/** One out-of-date install we want to nag about. */
+export interface OutdatedRow {
+    /** Where the stale copy lives: the project's node_modules or the global CLI. */
+    readonly scope: 'project' | 'global';
+    readonly installed: string;
+    readonly command: string;
+}
+
+/**
+ * Decides what (if anything) to warn about. `projectVersion` is the toiljs resolved in the
+ * project's node_modules (null when not installed there), `cliVersion` is the copy of the CLI
+ * actually running, and `cliIsLocal` tells us whether those are the same install.
+ */
+export function findOutdated(
+    latest: string,
+    projectVersion: string | null,
+    cliVersion: string,
+    cliIsLocal: boolean,
+    pm: string,
+): OutdatedRow[] {
+    const rows: OutdatedRow[] = [];
+    if (projectVersion !== null && isOutdated(projectVersion, latest)) {
+        rows.push({
+            scope: 'project',
+            installed: projectVersion,
+            command: installCommand(pm, 'project'),
+        });
+    }
+    // The running CLI only gets its own row when it is not the project install we already
+    // reported (global installs, or `npx toiljs` outside a project).
+    if (!cliIsLocal && isOutdated(cliVersion, latest)) {
+        rows.push({
+            scope: 'global',
+            installed: cliVersion,
+            command: installCommand('npm', 'global'),
+        });
+    }
+    return rows;
+}

package/test/ui.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+
+import { box, tagline } from '../src/cli/ui';
+
+describe('tagline', () => {
+    it('always yields a non-empty line, whichever variant is drawn', () => {
+        for (let i = 0; i < 100; i++) {
+            const t = tagline();
+            expect(t.length).toBeGreaterThan(0);
+            expect(t).not.toContain('undefined');
+        }
+    });
+});
+
+describe('box', () => {
+    it('frames lines in a rounded box sized to the widest line', () => {
+        expect(box(['hello', 'hi'])).toBe(
+            [
+                '  ╭─────────╮',
+                '  │  hello  │',
+                '  │  hi     │',
+                '  ╰─────────╯',
+            ].join('\n'),
+        );
+    });
+
+    it('pads on visible width, ignoring ANSI color codes', () => {
+        const colored = '\x1b[1mhello\x1b[22m';
+        const lines = box([colored, 'hi']).split('\n');
+        // Both content rows must end at the same column once colors are stripped.
+        const stripped = lines.map((l) => l.replace(/\x1b\[[0-9;]*m/g, ''));
+        expect(new Set(stripped.map((l) => l.length)).size).toBe(1);
+    });
+
+    it('paints only the border', () => {
+        const out = box(['hi'], (s) => `<${s}>`);
+        expect(out).toContain('<│>  hi  <│>');
+        expect(out).toContain('<╭──────╮>');
+    });
+});

package/test/version-check.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+    CHECK_TTL_MS,
+    compareSemver,
+    findOutdated,
+    installCommand,
+    isCacheFresh,
+    isOutdated,
+    parseCheckCache,
+} from '../src/cli/version-check';
+
+describe('compareSemver', () => {
+    it('orders plain versions', () => {
+        expect(compareSemver('0.0.31', '0.0.32')).toBeLessThan(0);
+        expect(compareSemver('0.0.32', '0.0.31')).toBeGreaterThan(0);
+        expect(compareSemver('0.0.31', '0.0.31')).toBe(0);
+        expect(compareSemver('0.9.9', '0.10.0')).toBeLessThan(0);
+        expect(compareSemver('1.0.0', '0.99.99')).toBeGreaterThan(0);
+    });
+
+    it('treats a prerelease as older than its release', () => {
+        expect(compareSemver('0.1.0-beta.1', '0.1.0')).toBeLessThan(0);
+        expect(compareSemver('0.1.0', '0.1.0-beta.1')).toBeGreaterThan(0);
+        expect(compareSemver('0.1.0-alpha', '0.1.0-beta')).toBeLessThan(0);
+    });
+
+    it('tolerates a leading v and garbage input', () => {
+        expect(compareSemver('v1.2.3', '1.2.3')).toBe(0);
+        expect(compareSemver('garbage', '0.0.0')).toBe(0);
+    });
+});
+
+describe('isOutdated', () => {
+    it('is true only when installed is behind latest', () => {
+        expect(isOutdated('0.0.31', '0.0.32')).toBe(true);
+        expect(isOutdated('0.0.32', '0.0.32')).toBe(false);
+        // A local build ahead of the registry must not warn.
+        expect(isOutdated('0.0.33', '0.0.32')).toBe(false);
+    });
+});
+
+describe('parseCheckCache', () => {
+    it('parses a valid cache entry', () => {
+        expect(parseCheckCache('{"latest":"0.0.32","checkedAt":1000}')).toEqual({
+            latest: '0.0.32',
+            checkedAt: 1000,
+        });
+    });
+
+    it('keeps a cached failure (latest null) so offline machines back off', () => {
+        expect(parseCheckCache('{"latest":null,"checkedAt":1000}')).toEqual({
+            latest: null,
+            checkedAt: 1000,
+        });
+    });
+
+    it('rejects malformed contents', () => {
+        expect(parseCheckCache('not json')).toBeNull();
+        expect(parseCheckCache('[]')).toBeNull();
+        expect(parseCheckCache('{"latest":"0.0.32"}')).toBeNull();
+        expect(parseCheckCache('{"latest":42,"checkedAt":"soon"}')).toBeNull();
+    });
+});
+
+describe('isCacheFresh', () => {
+    const cache = { latest: '0.0.32', checkedAt: 10_000 };
+
+    it('is fresh within the TTL and stale after it', () => {
+        expect(isCacheFresh(cache, 10_000 + CHECK_TTL_MS - 1)).toBe(true);
+        expect(isCacheFresh(cache, 10_000 + CHECK_TTL_MS)).toBe(false);
+    });
+
+    it('is stale when the clock went backwards past checkedAt', () => {
+        expect(isCacheFresh(cache, 9_999)).toBe(false);
+    });
+});
+
+describe('installCommand', () => {
+    it('targets the project with the detected package manager', () => {
+        expect(installCommand('npm', 'project')).toBe('npm install toiljs@latest');
+        expect(installCommand('pnpm', 'project')).toBe('pnpm add toiljs@latest');
+        expect(installCommand('yarn', 'project')).toBe('yarn add toiljs@latest');
+        expect(installCommand('bun', 'project')).toBe('bun add toiljs@latest');
+    });
+
+    it('targets the global install', () => {
+        expect(installCommand('npm', 'global')).toBe('npm install -g toiljs@latest');
+        expect(installCommand('pnpm', 'global')).toBe('pnpm add -g toiljs@latest');
+    });
+});
+
+describe('findOutdated', () => {
+    it('flags an outdated project install with the project command', () => {
+        const rows = findOutdated('0.0.32', '0.0.31', '0.0.31', true, 'pnpm');
+        expect(rows).toEqual([
+            { scope: 'project', installed: '0.0.31', command: 'pnpm add toiljs@latest' },
+        ]);
+    });
+
+    it('flags an outdated global CLI even when the project is current', () => {
+        const rows = findOutdated('0.0.32', '0.0.32', '0.0.30', false, 'npm');
+        expect(rows).toEqual([
+            { scope: 'global', installed: '0.0.30', command: 'npm install -g toiljs@latest' },
+        ]);
+    });
+
+    it('flags both when a stale global CLI runs inside a stale project', () => {
+        const rows = findOutdated('0.0.32', '0.0.31', '0.0.30', false, 'npm');
+        expect(rows.map((r) => r.scope)).toEqual(['project', 'global']);
+    });
+
+    it('does not double-report when the running CLI is the project install', () => {
+        const rows = findOutdated('0.0.32', '0.0.31', '0.0.31', true, 'npm');
+        expect(rows).toHaveLength(1);
+        expect(rows[0].scope).toBe('project');
+    });
+
+    it('reports nothing when everything is current or ahead', () => {
+        expect(findOutdated('0.0.32', '0.0.32', '0.0.32', true, 'npm')).toEqual([]);
+        expect(findOutdated('0.0.32', null, '0.0.33', false, 'npm')).toEqual([]);
+    });
+
+    it('handles a missing project install (npx outside a project)', () => {
+        const rows = findOutdated('0.0.32', null, '0.0.31', false, 'npm');
+        expect(rows).toEqual([
+            { scope: 'global', installed: '0.0.31', command: 'npm install -g toiljs@latest' },
+        ]);
+    });
+});