toiljs 0.0.30 → 0.0.32

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/src/compiler/index.ts

@@ -6,8 +6,10 @@ import path from 'node:path';
 
 import pc from 'picocolors';
 import { build as viteBuild, createServer, mergeConfig, type ViteDevServer } from 'vite';
-import { startBackend, type RunningBackend } from 'toiljs/backend';
-import { startDevServer } from 'toiljs/devserver';
+// The server modules pull in @dacely/hyper-express, whose uWebSockets.js native
+// addon loads at import time. Only `dev`/`start` need them, so they are imported
+// lazily; `create`/`build`/`doctor` must never touch the native binary.
+import type { RunningBackend } from 'toiljs/backend';
 
 import { loadConfig } from './config.js';
 import { generate } from './generate.js';
@@ -263,6 +265,7 @@ export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer>
     const server = await createServer(viteConfig);
     await server.listen();
 
+    const { startDevServer } = await import('toiljs/devserver');
     const front = await startDevServer({
         root: cfg.root,
         port: cfg.port,
@@ -322,6 +325,7 @@ export async function start(opts: ToilCommandOptions = {}): Promise<RunningBacke
     if (!fs.existsSync(path.join(outDir, 'index.html'))) {
         throw new Error(`No build found in ${outDir}. Run \`toiljs build\` first.`);
     }
+    const { startBackend } = await import('toiljs/backend');
     return startBackend({ root: outDir, port: cfg.port, host: opts.host });
 }
 

package/src/devserver/index.ts

@@ -1,5 +1,5 @@
 /**
- * The toiljs WASM dev server: a uWebSockets.js front (via @btc-vision/hyper-express,
+ * The toiljs WASM dev server: a uWebSockets.js front (via @dacely/hyper-express,
  * the same stack as `toiljs/backend`) that dispatches HTTP requests into the
  * ToilScript-compiled server wasm exactly like the production edge does, and
  * proxies everything the server does not claim to an internal Vite dev server,
@@ -22,7 +22,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { Server, type Request, type Response } from '@btc-vision/hyper-express';
+import { Server, type Request, type Response } from '@dacely/hyper-express';
 import pc from 'picocolors';
 
 import { METHOD_CODES, type EnvelopeRequest } from './envelope.js';

package/src/devserver/proxy.ts

@@ -11,7 +11,7 @@ import {
     type Response,
     type Server,
     type Websocket,
-} from '@btc-vision/hyper-express';
+} from '@dacely/hyper-express';
 
 /** Where the internal Vite dev server listens (always loopback). */
 export interface ViteTarget {

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' },
+        ]);
+    });
+});