Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

9.9 KB
Raw Blame
/**
 * Unit tests for the npm floor advisory.
 *
 * Lockfiles written by npm >=11.11.0 and re-written by older npm differ in
 * their `libc` fields, so `client/package-lock.json` shows up
 * modified after every install. These tests pin the three things that make the
 * advisory useful: it fires only below the floor, it never turns into a hard
 * failure, and it names the shadowed-global-npm case that makes the version
 * skew hard to spot.
 */
import { afterEach, describe, it, expect, vi } from 'vitest';
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  rmSync,
  writeFileSync,
} from 'fs';
import { tmpdir } from 'os';
import { dirname, join } from 'path';
import { fileURLToPath } from 'url';

import {
  MIN_NPM,
  npmAdvisory,
  parseNpmUserAgent,
  readBundledNpmVersion,
  warnOnOutdatedNpm,
} from './checkNpmVersion.js';

const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
const readJson = (rel) => JSON.parse(readFileSync(join(REPO_ROOT, rel), 'utf8'));
const tempRoots = [];

afterEach(() => {
  for (const root of tempRoots.splice(0)) rmSync(root, { recursive: true, force: true });
});

describe('MIN_NPM', () => {
  it('is the first npm release whose lockfile writer records `libc`', () => {
    // npm 11.11.0 ships arborist 9.4.0, which adds libc to pkgMetaKeys.
    // npm 11.10.1 ships arborist 9.3.1 and still omits it.
    expect(MIN_NPM).toBe('11.11.0');
  });
});

describe('parseNpmUserAgent', () => {
  it('reads the version out of the user agent npm exports to run-scripts', () => {
    expect(parseNpmUserAgent('npm/9.6.0 node/v24.10.0 win32 x64 workspaces/false')).toBe('9.6.0');
    expect(parseNpmUserAgent('npm/12.0.2 node/v24.10.0 darwin arm64 workspaces/false')).toBe('12.0.2');
  });

  it('is not fooled by a lookalike earlier in the string', () => {
    // `pnpm/9.0.0` ends in "npm/9.0.0"; only a token boundary counts.
    expect(parseNpmUserAgent('pnpm/9.0.0 node/v24.10.0 linux x64')).toBeNull();
    expect(parseNpmUserAgent('yarn/4.1.0 npm/? node/v24.10.0 linux x64')).toBeNull();
  });

  it('returns null when there is no npm user agent to read', () => {
    // NOT `parseNpmUserAgent(undefined)`: the parameter defaults to
    // `process.env.npm_config_user_agent`, and passing an explicit `undefined`
    // is indistinguishable from omitting the argument — so under `npm test`
    // that call reads the ambient agent and returns a version, not null.
    expect(parseNpmUserAgent('')).toBeNull();
    expect(parseNpmUserAgent(null)).toBeNull();
  });

  it('falls back to the ambient npm_config_user_agent, and to null without one', () => {
    vi.stubEnv('npm_config_user_agent', 'npm/10.9.0 node/v22.12.0 linux x64');
    expect(parseNpmUserAgent()).toBe('10.9.0');
    // The "not running under npm" case the default parameter exists for. Stubbed
    // rather than assumed, because the suite itself usually runs under npm.
    vi.stubEnv('npm_config_user_agent', '');
    expect(parseNpmUserAgent()).toBeNull();
    vi.unstubAllEnvs();
  });
});

describe('readBundledNpmVersion', () => {
  it('returns null instead of throwing when no npm sits beside the binary', () => {
    expect(readBundledNpmVersion(join(REPO_ROOT, 'no', 'such', 'node'))).toBeNull();
  });

  it('reads bundled npm from both supported Node install layouts', () => {
    const root = mkdtempSync(join(tmpdir(), 'portos-npm-version-'));
    tempRoots.push(root);

    const adjacentBin = join(root, 'adjacent', 'bin');
    const adjacentManifest = join(adjacentBin, 'node_modules', 'npm', 'package.json');
    mkdirSync(dirname(adjacentManifest), { recursive: true });
    writeFileSync(adjacentManifest, JSON.stringify({ version: '11.17.0' }));
    expect(readBundledNpmVersion(join(adjacentBin, 'node'))).toBe('11.17.0');

    const prefixBin = join(root, 'prefix', 'bin');
    const prefixManifest = join(root, 'prefix', 'lib', 'node_modules', 'npm', 'package.json');
    mkdirSync(dirname(prefixManifest), { recursive: true });
    writeFileSync(prefixManifest, JSON.stringify({ version: '12.0.1' }));
    expect(readBundledNpmVersion(join(prefixBin, 'node'))).toBe('12.0.1');
  });
});

describe('npmAdvisory', () => {
  it('says nothing on npm at or above the floor', () => {
    expect(npmAdvisory({ npmVersion: MIN_NPM, bundledNpmVersion: '11.6.1' })).toEqual([]);
    expect(npmAdvisory({ npmVersion: '11.12.1' })).toEqual([]);
    expect(npmAdvisory({ npmVersion: '12.4.0', bundledNpmVersion: '11.6.1' })).toEqual([]);
  });

  it('says nothing when there is no npm to warn about', () => {
    // A bare `node scripts/checkNpmVersion.js` isn't running an install.
    expect(npmAdvisory({ npmVersion: null })).toEqual([]);
    expect(npmAdvisory({})).toEqual([]);
  });

  it('names the version, the floor, the symptom, and the fix below the floor', () => {
    const lines = npmAdvisory({ npmVersion: '11.10.1', bundledNpmVersion: '11.10.1' });
    const text = lines.join('\n');
    expect(text).toContain('11.10.1');
    expect(text).toContain(MIN_NPM);
    expect(text).toContain('package-lock.json');
    expect(text).toContain('libc');
    expect(text).toContain(`npm install -g npm@${MIN_NPM}`);
  });

  it('flags a stale global npm shadowing the one Node bundles', () => {
    const lines = npmAdvisory({
      npmVersion: '9.6.0',
      bundledNpmVersion: '11.6.1',
      nodeVersion: 'v24.10.0',
    });
    const shadow = lines.find((line) => line.includes('shadowing'));
    expect(shadow).toBeTruthy();
    expect(shadow).toContain('24.10.0');
    expect(shadow).toContain('11.6.1');
    expect(shadow).toContain('9.6.0');
    // The `v` is supplied by the message, not doubled up from the input.
    expect(shadow).not.toContain('vv');
  });

  it('omits the shadowing line when npm is the bundled one, or newer', () => {
    const bundled = npmAdvisory({ npmVersion: '11.6.1', bundledNpmVersion: '11.6.1' });
    expect(bundled.some((line) => line.includes('shadowing'))).toBe(false);
    const newer = npmAdvisory({ npmVersion: '11.9.0', bundledNpmVersion: '11.6.1' });
    expect(newer.some((line) => line.includes('shadowing'))).toBe(false);
  });

  it('omits the shadowing line when the bundled npm cannot be read', () => {
    const lines = npmAdvisory({ npmVersion: '9.6.0', bundledNpmVersion: null });
    expect(lines.some((line) => line.includes('shadowing'))).toBe(false);
    expect(lines.join('\n')).toContain(`npm install -g npm@${MIN_NPM}`);
  });
});

describe('warnOnOutdatedNpm', () => {
  it('prints each advisory line and reports that it warned', () => {
    const warn = vi.fn();
    const warned = warnOnOutdatedNpm({ npmVersion: '9.6.0', bundledNpmVersion: '11.6.1', warn });
    expect(warned).toBe(true);
    expect(warn.mock.calls.length).toBeGreaterThan(0);
    // Single-line logging: no multi-line blobs, no JSON dumps.
    for (const [line] of warn.mock.calls) expect(line).not.toContain('\n');
  });

  it('stays silent — and non-fatal — on a current npm', () => {
    const warn = vi.fn();
    expect(warnOnOutdatedNpm({ npmVersion: '12.0.2', bundledNpmVersion: '11.6.1', warn })).toBe(false);
    expect(warn).not.toHaveBeenCalled();
  });
});

describe('the advisory is actually reachable', () => {
  it.each(['setup', 'start', 'dev'])('the root `%s` script runs it before installing', (name) => {
    const script = readJson('package.json').scripts[name];
    expect(script).toContain('node scripts/checkNpmVersion.js &&');
    // After the Node gate (which is fatal) and before anything that installs.
    expect(script.indexOf('checkNodeVersion.js')).toBeLessThan(script.indexOf('checkNpmVersion.js'));
  });
});

describe('PortOS-managed installs preserve committed lockfiles', () => {
  it('passes --no-save through every setup, update, and dependency-repair install', () => {
    const managedEntrypoints = [
      ['package.json', /npm install(?: --prefix \w+)?/g],
      ['setup.ps1', /^npm install/gm],
      ['update.ps1', /Invoke-Logged npm install/g],
      ['update.sh', /run npm install/g],
      ['scripts/ensure-deps.js', /npmSpawn\(\['install'/g],
    ];

    for (const [rel, installPattern] of managedEntrypoints) {
      const body = readFileSync(join(REPO_ROOT, rel), 'utf8');
      const installs = [...body.matchAll(installPattern)];
      expect(installs.length, `${rel} has no managed npm installs to verify`).toBeGreaterThan(0);
      for (const install of installs) {
        const command = body.slice(install.index, install.index + 80);
        expect(command, `${rel}: ${install[0]} must preserve package-lock.json`).toContain('--no-save');
      }
    }
  });
});

describe('the floor is declared where npm itself reads it', () => {
  // The three scripts above cover `npm run setup|start|dev` and nothing else.
  // Direct `cd client && npm install` and `npm i <pkg>` are how lockfile churn
  // still gets introduced; only `engines.npm` reaches those authoring paths.
  const MANIFESTS = ['package.json', 'client/package.json', 'server/package.json', 'autofixer/package.json'];

  it.each(MANIFESTS)('%s declares engines.npm = the floor', (rel) => {
    expect(readJson(rel).engines?.npm).toBe(`>=${MIN_NPM}`);
    expect(readJson(rel.replace('package.json', 'package-lock.json')).packages[''].engines?.npm).toBe(`>=${MIN_NPM}`);
  });

  it.each(MANIFESTS)('%s ships a lockfile that the floor protects', (rel) => {
    // If a workspace stops carrying a lockfile, its engines.npm entry is just
    // noise — this is what would say so.
    const lockfile = join(REPO_ROOT, rel.replace(/package\.json$/, 'package-lock.json'));
    expect(existsSync(lockfile), `${rel} declares engines.npm but ships no lockfile`).toBe(true);
  });

  it.each(['.npmrc', 'client/.npmrc', 'server/.npmrc', 'autofixer/.npmrc'])(
    '%s leaves engine-strict off so the npm floor stays a warning',
    (rel) => {
      // engine-strict would turn EBADENGINE fatal for dependencies too, which is
      // the trap the node floor already documents. A churned lockfile is not
      // worth a broken install.
      expect(readFileSync(join(REPO_ROOT, rel), 'utf8')).not.toMatch(/^\s*engine-strict\s*=\s*true/m);
    }
  );
});