Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
21.3 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Update notices (spec AST-081 FR10): when each one applies, its exact
 * two lines, the upgrade command for each package manager, and that it prints
 * at most once a day and never when the environment turns notices off.
 */

import {afterEach, describe, expect, it} from 'vitest';
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {spawn} from 'node:child_process';
import {
  recordDeclaredCliCommands,
  runWithCliDoor,
} from '../env/cli-command.mjs';
import {
  NOTICE_INTERVAL_MS,
  availableLine,
  globalBehind,
  globalUpgradeCommand,
  noticeLines,
  oldGlobalCommand,
  oldGlobalLines,
  projectLag,
  alignCliAndCore,
  lastNoticeSkip,
  recordNoticeSkip,
  takeNotice,
  upgradeLine,
} from './notices.mjs';
import {
  readGlobalState,
  stateLockHolder,
  tryStateLock,
  updateGlobalState,
} from './global-state.mjs';
import {
  cleanupFixtures,
  installCore,
  installStandInCli,
  project,
  tempDir,
  writeJson,
} from '../../test-utils/release-fixtures.mjs';

afterEach(cleanupFixtures);

const DAY = 24 * 60 * 60_000;

/**
 * An Astryx CLI package on a search path folder, with or without the hand-off.
 * @param {string} version
 * @param {{handsOff?: boolean, prefix?: string[]}} [options]
 */
function cliOnPath(version, {handsOff = false, prefix = ['lib']} = {}) {
  const root = tempDir('prefix');
  const pkg = path.join(
    root,
    ...prefix,
    'node_modules',
    '@astryxdesign',
    'cli',
  );
  fs.mkdirSync(pkg, {recursive: true});
  writeJson(path.join(pkg, 'package.json'), {
    name: '@astryxdesign/cli',
    version,
  });
  fs.writeFileSync(path.join(pkg, 'bin.mjs'), '#!/usr/bin/env node\n');
  fs.chmodSync(path.join(pkg, 'bin.mjs'), 0o755);
  if (handsOff) {
    fs.mkdirSync(path.join(pkg, 'foundation', 'release'), {recursive: true});
    fs.writeFileSync(path.join(pkg, 'foundation', 'release', 'choose.mjs'), '');
  }
  fs.mkdirSync(path.join(root, 'bin'));
  fs.symlinkSync(path.join(pkg, 'bin.mjs'), path.join(root, 'bin', 'astryx'));
  return {bin: path.join(root, 'bin'), pkg, root};
}

/** A state folder whose last check found `version`, needing Node `node`. */
function checked(version = '0.7.3', node = null) {
  const stateDir = tempDir('state');
  updateGlobalState(
    {latest: version, latestNode: node, checkOkAt: 1},
    stateDir,
  );
  return stateDir;
}

describe('takeNotice', () => {
  it('lets a notice print once in any 24 hours, per key', () => {
    const stateDir = tempDir('state');
    expect(takeNotice('a', {stateDir, now: 1000})).toBe(true);
    expect(takeNotice('a', {stateDir, now: 1000 + DAY - 1})).toBe(false);
    expect(takeNotice('b', {stateDir, now: 2000})).toBe(true);
    expect(takeNotice('a', {stateDir, now: 1000 + NOTICE_INTERVAL_MS})).toBe(
      true,
    );
    expect(readGlobalState(stateDir).notifiedAt).toEqual({
      a: 1000 + NOTICE_INTERVAL_MS,
      b: 2000,
    });
  });

  it('lets exactly one of many runs finishing at once take a notice (b18)', async () => {
    const stateDir = tempDir('state');
    const notices = new URL('./notices.mjs', import.meta.url).href;
    const source = `
      const {takeNotice} = await import(${JSON.stringify(notices)});
      const at = Number(process.argv[1]);
      while (Date.now() < at) {}
      process.stdout.write(takeNotice('global', {stateDir: ${JSON.stringify(stateDir)}}) ? 'took' : 'skip');
    `;
    const at = String(Date.now() + 1500);
    const runs = await Promise.all(
      Array.from(
        {length: 10},
        () =>
          new Promise(resolve => {
            const child = spawn(
              process.execPath,
              ['--input-type=module', '-e', source, at],
              {stdio: ['ignore', 'pipe', 'inherit']},
            );
            let out = '';
            child.stdout.on('data', d => (out += d));
            child.on('close', () => resolve(out));
          }),
      ),
    );
    expect(runs.filter(r => r === 'took')).toHaveLength(1);
    expect(runs.filter(r => r === 'skip')).toHaveLength(9);
    expect(fs.existsSync(path.join(stateDir, '.lock-state'))).toBe(false);
  });

  it('prints nothing when the time cannot be recorded', () => {
    const file = path.join(tempDir('state'), 'file');
    fs.writeFileSync(file, '');
    expect(takeNotice('a', {stateDir: file, now: 1})).toBe(false);
  });
});

describe('why a notice did not print (diagnostic state)', () => {
  it('records an already-shown skip, at most once an hour for the same reason', () => {
    const stateDir = tempDir('state');
    expect(takeNotice('global', {stateDir, now: 1000})).toBe(true);
    expect(takeNotice('global', {stateDir, now: 2000})).toBe(false);
    expect(readGlobalState(stateDir).noticeSkips).toEqual({
      global: {reason: 'already-shown', at: 2000},
    });
    // Within the hour: not rewritten.
    expect(takeNotice('global', {stateDir, now: 3000})).toBe(false);
    expect(readGlobalState(stateDir).noticeSkips?.global.at).toBe(2000);
    // After it: recorded again.
    expect(takeNotice('global', {stateDir, now: 2000 + 60 * 60_000})).toBe(
      false,
    );
    expect(readGlobalState(stateDir).noticeSkips?.global.at).toBe(
      2000 + 60 * 60_000,
    );
    expect(lastNoticeSkip({stateDir})).toEqual({
      key: 'global',
      reason: 'already-shown',
      at: 2000 + 60 * 60_000,
    });
  });

  // The setup reminder shares the once-a-day record but is no update
  // notice: no skip is recorded for it, and an old one is never reported.
  it('records no skip for the setup reminder, and lastNoticeSkip ignores one', () => {
    const stateDir = tempDir('state');
    updateGlobalState({latest: '0.7.1'}, stateDir);
    expect(takeNotice('setup:/app', {stateDir, now: 1000})).toBe(true);
    expect(takeNotice('setup:/app', {stateDir, now: 2000})).toBe(false);
    expect(readGlobalState(stateDir).noticeSkips).toBeUndefined();
    expect(lastNoticeSkip({stateDir})).toBeNull();
    updateGlobalState(
      {noticeSkips: {'setup:/app': {reason: 'already-shown', at: 3000}}},
      stateDir,
    );
    expect(lastNoticeSkip({stateDir})).toBeNull();
    expect(takeNotice('global', {stateDir, now: 4000})).toBe(true);
    expect(takeNotice('global', {stateDir, now: 5000})).toBe(false);
    expect(lastNoticeSkip({stateDir})).toEqual({
      key: 'global',
      reason: 'already-shown',
      at: 5000,
    });
  });

  it('says a held lock timed out, and who holds it', () => {
    const stateDir = tempDir('state');
    const lockDir = path.join(stateDir, '.lock-state');
    fs.mkdirSync(lockDir, {recursive: true});
    fs.writeFileSync(
      path.join(lockDir, 'owner.json'),
      JSON.stringify({pid: process.pid, host: os.hostname(), at: Date.now()}),
    );
    expect(tryStateLock(stateDir, () => 'ran')).toEqual({
      ran: false,
      reason: 'lock-timeout',
    });
    expect(stateLockHolder(stateDir)).toMatchObject({pid: process.pid});
    fs.rmSync(lockDir, {recursive: true});
    expect(stateLockHolder(stateDir)).toBeNull();
    // Nothing is recorded where no state file exists yet.
    recordNoticeSkip('global', 'no-newer', {stateDir, now: 4});
    expect(fs.existsSync(path.join(stateDir, 'state.json'))).toBe(false);
  }, 10_000);

  it('records nothing for a notice the lock kept from printing, and writes no other file', () => {
    const stateDir = tempDir('state');
    updateGlobalState({latest: '0.7.1'}, stateDir);
    const lockDir = path.join(stateDir, '.lock-state');
    fs.mkdirSync(lockDir, {recursive: true});
    expect(takeNotice('global', {stateDir, now: 6})).toBe(false);
    fs.rmSync(lockDir, {recursive: true});
    expect(lastNoticeSkip({stateDir})).toBeNull();
    expect(fs.readdirSync(stateDir).sort()).toEqual(['state.json']);
  }, 10_000);
});

describe('the lines', () => {
  it('match the gh form, naming the Node a release needs', () => {
    expect(availableLine('0.7.2', '0.7.3')).toBe(
      'A new release of Astryx is available: 0.7.2 → 0.7.3',
    );
    expect(
      upgradeLine('npm i -g @astryxdesign/cli@latest', '>=20', '22.0.0'),
    ).toBe('To upgrade, run: npm i -g @astryxdesign/cli@latest');
    expect(
      upgradeLine('npm i -g @astryxdesign/cli@latest', '>=24', '22.13.0'),
    ).toBe(
      'To upgrade, install Node >=24 (this computer runs Node 22.13.0), then run: npm i -g @astryxdesign/cli@latest',
    );
  });

  it('upgrade a CLI that npm installed under its own prefix into that prefix', () => {
    const linux = {
      execPath: '/usr/bin/node',
      home: '/home/a',
      platform: /** @type {const} */ ('linux'),
      env: {},
    };
    expect(
      globalUpgradeCommand(
        '/home/a/.local/lib/node_modules/@astryxdesign/cli',
        linux,
      ),
    ).toBe('npm i -g --prefix ~/.local @astryxdesign/cli@latest');
    expect(
      globalUpgradeCommand(
        '/home/a/.npm-global/lib/node_modules/@astryxdesign/cli',
        linux,
      ),
    ).toBe('npm i -g --prefix ~/.npm-global @astryxdesign/cli@latest');
    expect(
      globalUpgradeCommand(
        '/opt/tools/lib/node_modules/@astryxdesign/cli',
        linux,
      ),
    ).toBe('npm i -g --prefix /opt/tools @astryxdesign/cli@latest');
    // npm's default prefixes: Node's own, /usr/local, /usr.
    for (const cli of [
      '/usr/local/lib/node_modules/@astryxdesign/cli',
      '/usr/lib/node_modules/@astryxdesign/cli',
    ]) {
      expect(globalUpgradeCommand(cli, linux)).toBe(
        'npm i -g @astryxdesign/cli@latest',
      );
    }
    expect(
      globalUpgradeCommand(
        '/home/a/.nvm/versions/node/v22.1.0/lib/node_modules/@astryxdesign/cli',
        {
          ...linux,
          execPath: '/home/a/.nvm/versions/node/v22.1.0/bin/node',
        },
      ),
    ).toBe('npm i -g @astryxdesign/cli@latest');
    const win = {
      execPath: 'C:\\Program Files\\nodejs\\node.exe',
      home: 'C:\\Users\\a',
      platform: /** @type {const} */ ('win32'),
      env: {APPDATA: 'C:\\Users\\a\\AppData\\Roaming'},
    };
    expect(
      globalUpgradeCommand(
        'C:\\Users\\a\\AppData\\Roaming\\npm\\node_modules\\@astryxdesign\\cli',
        win,
      ),
    ).toBe('npm i -g @astryxdesign/cli@latest');
    expect(
      globalUpgradeCommand(
        'D:\\tools\\npm\\node_modules\\@astryxdesign\\cli',
        win,
      ),
    ).toBe('npm i -g --prefix D:\\tools\\npm @astryxdesign/cli@latest');
  });

  it('name the package manager that installed the global copy', () => {
    const at = (/** @type {string} */ p) =>
      globalUpgradeCommand(path.join(path.sep, ...p.split('/')), {
        home: '/home/a',
        platform: 'linux',
        env: {PNPM_HOME: '/home/a/pn'},
      });
    expect(at('usr/local/lib/node_modules/@astryxdesign/cli')).toBe(
      'npm i -g @astryxdesign/cli@latest',
    );
    expect(at('home/a/pn/global/5/node_modules/@astryxdesign/cli')).toBe(
      'pnpm add -g @astryxdesign/cli@latest',
    );
    expect(at('home/a/pn/global/v11/3f2a/node_modules/@astryxdesign/cli')).toBe(
      'pnpm add -g @astryxdesign/cli@latest',
    );
    expect(
      at('home/a/.config/yarn/global/node_modules/@astryxdesign/cli'),
    ).toBe('yarn global add @astryxdesign/cli@latest');
    expect(
      at('home/a/.bun/install/global/node_modules/@astryxdesign/cli'),
    ).toBe('bun add -g @astryxdesign/cli@latest');
    expect(
      at(
        'home/a/.volta/tools/image/packages/@astryxdesign/cli/lib/node_modules/@astryxdesign/cli',
      ),
    ).toBe('volta install @astryxdesign/cli@latest');
  });
});

describe('globalBehind and projectLag', () => {
  it('need a completed check, and never report a current, newer, or prerelease version', () => {
    const self = {
      version: '0.7.2',
      root: '/usr/lib/node_modules/@astryxdesign/cli',
    };
    expect(globalBehind({self, stateDir: tempDir('state')})).toBeNull();
    const stateDir = checked('0.7.3', '>=24');
    expect(globalBehind({self, stateDir})).toEqual({
      current: '0.7.2',
      newest: '0.7.3',
      node: '>=24',
      command: 'npm i -g @astryxdesign/cli@latest',
    });
    for (const version of ['0.7.3', '0.8.0', '0.7.2-canary.1']) {
      expect(globalBehind({self: {...self, version}, stateDir})).toBeNull();
    }
  });

  it("name a project's install and upgrade commands for its package manager", () => {
    const stateDir = checked('0.7.3');
    const coreOnly = project(tempDir(), {'@astryxdesign/core': '0.7.1'});
    writeJson(path.join(coreOnly, 'package-lock.json'), {lockfileVersion: 3});
    installCore(coreOnly, '0.7.1');
    expect(
      projectLag({cwd: coreOnly, current: '0.7.1', stateDir}),
    ).toMatchObject({
      root: coreOnly,
      install: 'npm install @astryxdesign/[email protected] @astryxdesign/[email protected]',
      upgrade: 'npx astryx upgrade --from 0.7.1 --apply',
    });
    const pnpm = project(tempDir(), {
      '@astryxdesign/core': '0.7.1',
      '@astryxdesign/cli': '0.7.1',
    });
    fs.writeFileSync(
      path.join(pnpm, 'pnpm-lock.yaml'),
      "lockfileVersion: '9.0'\n",
    );
    installCore(pnpm, '0.7.1');
    installStandInCli(pnpm, '0.7.1');
    expect(projectLag({cwd: pnpm, current: '0.7.1', stateDir})).toMatchObject({
      install: 'pnpm add @astryxdesign/[email protected] @astryxdesign/[email protected]',
      upgrade: 'pnpm exec astryx upgrade --from 0.7.1 --apply',
    });
  });
});

describe('projectLag from a tool folder inside a project', () => {
  it("uses the project's own CLI release, so the project gets one notice and one --from", () => {
    const stateDir = checked('0.7.3');
    const app = project(tempDir(), {
      '@astryxdesign/core': '0.7.1',
      '@astryxdesign/cli': '0.7.2',
    });
    writeJson(path.join(app, 'package-lock.json'), {lockfileVersion: 3});
    installCore(app, '0.7.1');
    installStandInCli(app, '0.7.2');
    const tool = path.join(app, 'tools', 'codegen');
    writeJson(path.join(tool, 'package.json'), {name: 'codegen'});
    installCore(tool, '0.7.0');

    const fromApp = projectLag({cwd: app, current: '0.7.2', stateDir});
    const fromTool = projectLag({cwd: tool, current: '0.7.0', stateDir});
    expect(fromTool).toMatchObject({root: app, current: '0.7.2'});
    expect(fromTool?.upgrade).toBe(`cd ${app} && ${fromApp?.upgrade}`);
  });
});

describe('the commands notices print go through the command-name picker (spec AST-081 FR5)', () => {
  /** A Core-only npm project behind the newest release. */
  const coreOnlyProject = () => {
    const dir = project(tempDir(), {'@astryxdesign/core': '0.7.1'});
    writeJson(path.join(dir, 'package-lock.json'), {lockfileVersion: 3});
    installCore(dir, '0.7.1');
    return dir;
  };

  it("use an integration's declared cliCommand for the upgrade step", () => {
    const stateDir = checked('0.7.3');
    const dir = coreOnlyProject();
    recordDeclaredCliCommands(dir, [
      {name: '@acme/a', cliCommand: 'acme astryx'},
    ]);
    try {
      expect(projectLag({cwd: dir, current: '0.7.1', stateDir})?.upgrade).toBe(
        'acme astryx upgrade --from 0.7.1 --apply',
      );
      expect(alignCliAndCore({cwd: dir, cli: '0.7.3', core: '0.7.1'})).toBe(
        'npm install @astryxdesign/[email protected], then acme astryx upgrade --from 0.7.1 --apply',
      );
    } finally {
      recordDeclaredCliCommands(dir, []);
    }
  });

  it("use a host's door when nothing is declared", () => {
    const stateDir = checked('0.7.3');
    const dir = coreOnlyProject();
    runWithCliDoor('host astryx', () => {
      expect(projectLag({cwd: dir, current: '0.7.1', stateDir})?.upgrade).toBe(
        'host astryx upgrade --from 0.7.1 --apply',
      );
      expect(alignCliAndCore({cwd: dir, cli: '0.7.3', core: '0.7.1'})).toBe(
        'npm install @astryxdesign/[email protected], then host astryx upgrade --from 0.7.1 --apply',
      );
    });
  });

  it("fall back to the project's own installed CLI", () => {
    const dir = coreOnlyProject();
    expect(alignCliAndCore({cwd: dir, cli: '0.7.3', core: '0.7.1'})).toBe(
      'npm install @astryxdesign/[email protected], then npx astryx upgrade --from 0.7.1 --apply',
    );
  });
});

describe.skipIf(process.platform === 'win32')('oldGlobalCommand', () => {
  it('names a first astryx that predates the hand-off with its own package manager, and not one that hands off', () => {
    const old = cliOnPath('0.7.1', {prefix: ['global', '5']});
    expect(oldGlobalCommand({searchPath: old.bin, platform: 'linux'})).toEqual({
      file: path.join(old.bin, 'astryx'),
      version: '0.7.1',
      command: 'pnpm add -g @astryxdesign/cli@latest',
    });
    expect(
      oldGlobalLines({
        version: '0.7.1',
        command: 'npm i -g @astryxdesign/cli@latest',
      }),
    ).toEqual([
      'The astryx command on this computer runs CLI 0.7.1, which answers every folder itself.',
      'To upgrade, run: npm i -g @astryxdesign/cli@latest',
    ]);
    const current = cliOnPath('0.8.0', {handsOff: true});
    expect(
      oldGlobalCommand({
        searchPath: [current.bin, old.bin].join(path.delimiter),
        platform: 'linux',
      }),
    ).toBeNull();
    expect(
      oldGlobalCommand({
        selfRoot: old.pkg,
        searchPath: old.bin,
        platform: 'linux',
      }),
    ).toBeNull();
  });
});

describe.skipIf(process.platform === 'win32')('noticeLines', () => {
  /** A global copy, outside a project. */
  const outside = () => {
    const global = cliOnPath('0.7.2', {handsOff: true});
    return {
      global,
      cwd: tempDir('empty'),
      self: {version: '0.7.2', root: global.pkg},
      choice: {inProject: false, version: '0.7.2'},
      cacheDir: tempDir('cache'),
      searchPath: global.bin,
      env: {},
    };
  };

  it('tells the global copy about a newer release, once a day', () => {
    const {global, ...input} = {...outside(), stateDir: checked('0.7.3')};
    // The fixture's global folder is a prefix of its own, so the upgrade
    // names it.
    const prefix = fs.realpathSync(global.root);
    expect(noticeLines({...input, now: 10})).toEqual([
      'A new release of Astryx is available: 0.7.2 → 0.7.3',
      `To upgrade, run: npm i -g --prefix ${prefix} @astryxdesign/cli@latest`,
    ]);
    expect(noticeLines({...input, now: 20})).toEqual([]);
    expect(lastNoticeSkip({stateDir: input.stateDir})).toEqual({
      key: 'global',
      reason: 'already-shown',
      at: 20,
    });
    expect(noticeLines({...input, now: 10 + DAY})).toHaveLength(2);
  });

  it('records that nothing newer was known when the global copy is current', () => {
    const {global: _global, ...input} = {
      ...outside(),
      stateDir: checked('0.7.2'),
    };
    expect(noticeLines({...input, now: 30})).toEqual([]);
    expect(lastNoticeSkip({stateDir: input.stateDir})).toEqual({
      key: 'global',
      reason: 'no-newer',
      at: 30,
    });
  });

  it('prints nothing with --json, in CI, or with NO_UPDATE_NOTIFIER, and keeps the notice for later', () => {
    const {global: _global, ...input} = {
      ...outside(),
      stateDir: checked('0.7.3'),
    };
    expect(noticeLines({...input, json: true, now: 10})).toEqual([]);
    expect(noticeLines({...input, env: {CI: 'true'}, now: 10})).toEqual([]);
    expect(
      noticeLines({...input, env: {NO_UPDATE_NOTIFIER: '1'}, now: 10}),
    ).toEqual([]);
    expect(noticeLines({...input, now: 10})).toHaveLength(2);
  });

  it('tells a project about its release, and an old astryx first on the search path, even with no check', () => {
    const stateDir = checked('0.7.3');
    const dir = project(tempDir(), {'@astryxdesign/core': '0.7.1'});
    writeJson(path.join(dir, 'package-lock.json'), {lockfileVersion: 3});
    installCore(dir, '0.7.1');
    const old = cliOnPath('0.7.1');
    const oldUpgrade = `To upgrade, run: npm i -g --prefix ${fs.realpathSync(old.root)} @astryxdesign/cli@latest`;
    const input = {
      cwd: dir,
      self: {version: '0.7.1', root: tempDir('self')},
      choice: {inProject: true, version: '0.7.1'},
      searchPath: old.bin,
      env: {},
    };
    expect(noticeLines({...input, stateDir, now: 10})).toEqual([
      'A new release of Astryx is available: 0.7.1 → 0.7.3',
      'To upgrade, run: npm install @astryxdesign/[email protected] @astryxdesign/[email protected], then npx astryx upgrade --from 0.7.1 --apply',
      'The astryx command on this computer runs CLI 0.7.1, which answers every folder itself.',
      oldUpgrade,
    ]);
    expect(
      noticeLines({...input, stateDir: tempDir('fresh'), now: 10}),
    ).toEqual([
      'The astryx command on this computer runs CLI 0.7.1, which answers every folder itself.',
      oldUpgrade,
    ]);
  });

  it('says nothing in a run inside the release cache, the CLI checking a release it installed', () => {
    const cacheDir = tempDir('cache');
    const tmp = path.join(cacheDir, 'releases', '.tmp-0.7.2-1-abc');
    fs.mkdirSync(tmp, {recursive: true});
    const stateDir = checked('0.7.3');
    const old = cliOnPath('0.7.1');
    const input = {
      cwd: tmp,
      self: {version: '0.7.2', root: tempDir('self')},
      choice: {inProject: true, version: '0.7.2'},
      cacheDir,
      stateDir,
      searchPath: old.bin,
      env: {},
      now: 10,
    };
    expect(noticeLines(input)).toEqual([]);
    expect(readGlobalState(stateDir).notifiedAt).toBeUndefined();
  });

  it('says nothing about a copy that is not the global copy outside a project', () => {
    const runner = {
      ...outside(),
      self: {
        version: '0.7.2',
        root: path.join(
          tempDir('npx'),
          '_npx',
          'x',
          'node_modules',
          '@astryxdesign',
          'cli',
        ),
      },
      stateDir: checked('0.7.3'),
    };
    expect(noticeLines({...runner, now: 10})).toEqual([]);
  });
});