Skip to content

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

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

/**
 * Direct API tests for `upgrade()` — the programmatic surface (`@astryxdesign/cli/api`).
 *
 * The CLI suites (cli/commands/upgrade*.test.mjs) drive `registerUpgrade` and
 * cover behavior end-to-end; these assert the API contract you get when calling
 * `upgrade()` in code: the typed receipt shape, thrown AstryxError codes, that
 * it honors the `cwd` option for detection/agent-docs, and that it stays SILENT
 * under the default noopLogger (no console spam for a scripted caller).
 */

import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
import * as fs from 'node:fs';
import * as path from 'node:path';
import * as os from 'node:os';
import {upgrade} from './upgrade.mjs';
import {logger} from '../logger.mjs';
import {AstryxError} from '../error.mjs';
import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
import {generateCompressedIndex} from '../../foundation/agent-docs/agent-docs.mjs';
import {
  createRegistryReceipt,
  registryReceiptTarget,
  serializeRegistryReceipt,
} from '../../authoring/shadcn/receipt.mjs';

vi.setConfig({testTimeout: 30000});

let tmpDir;
let originalCwd;

beforeEach(() => {
  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-upgrade-api-'));
  originalCwd = process.cwd();
});

afterEach(() => {
  process.chdir(originalCwd);
  fs.rmSync(tmpDir, {recursive: true, force: true});
  vi.restoreAllMocks();
  vi.unstubAllGlobals();
  logger.setSilent(true);
});

function writePkg(dir, deps = {}) {
  fs.writeFileSync(
    path.join(dir, 'package.json'),
    JSON.stringify({name: 'fixture', dependencies: deps}, null, 2),
  );
}

function writeInstalledCore(dir, version) {
  const d = path.join(dir, 'node_modules', '@astryxdesign', 'core');
  fs.mkdirSync(d, {recursive: true});
  fs.writeFileSync(
    path.join(d, 'package.json'),
    JSON.stringify({name: '@astryxdesign/core', version}, null, 2),
  );
}

function writeAgentBlock(dir, rel, version) {
  fs.writeFileSync(
    path.join(dir, rel),
    `# Doc\n\n${generateCompressedIndex(version)}\n`,
  );
}

function writeRegistryFixture(
  dir,
  {base = 'old\n', latest = 'new\n', version = '0.6.0'} = {},
) {
  const sourceTarget = 'components/astryx/examples/Example.tsx';
  const registryPath = 'registry/example-button-basic/Example.tsx';
  const receiptTarget = registryReceiptTarget(
    sourceTarget,
    'example-button-basic',
  );
  const installedReceipt = createRegistryReceipt({
    item: {
      name: 'example-button-basic',
      path: 'examples/button/basic',
      aliases: [],
      kind: 'example',
    },
    sourceVersion: '0.5.0',
    receiptTarget,
    files: [
      {
        id: 'primary',
        target: sourceTarget,
        registryPath,
        content: base,
      },
    ],
  });
  const latestReceipt = createRegistryReceipt({
    item: installedReceipt.item,
    sourceVersion: version,
    receiptTarget,
    files: [
      {
        id: 'primary',
        target: sourceTarget,
        registryPath,
        content: latest,
      },
    ],
  });
  const sourcePath = path.join(dir, 'src', sourceTarget);
  const receiptPath = path.join(dir, 'src', receiptTarget);
  fs.mkdirSync(path.dirname(sourcePath), {recursive: true});
  fs.mkdirSync(path.dirname(receiptPath), {recursive: true});
  fs.writeFileSync(sourcePath, base);
  fs.writeFileSync(receiptPath, serializeRegistryReceipt(installedReceipt));
  vi.stubGlobal(
    'fetch',
    vi.fn(
      async () =>
        new globalThis.Response(
          JSON.stringify({
            name: latestReceipt.item.name,
            type: 'registry:block',
            files: [
              {
                path: registryPath,
                type: 'registry:block',
                target: sourceTarget,
                content: latest,
              },
              {
                path: 'registry/example-button-basic/astryx-receipt.json',
                type: 'registry:file',
                target: receiptTarget,
                content: serializeRegistryReceipt(latestReceipt),
              },
            ],
          }),
          {status: 200},
        ),
    ),
  );
  return {sourcePath};
}

describe('upgrade() — receipts', () => {
  it('returns upgrade.list without touching cwd', async () => {
    const res = await upgrade({list: true});
    expect(res.type).toBe('upgrade.list');
    expect(Array.isArray(res.data)).toBe(true);
    expect(res.data.length).toBeGreaterThan(0);
    // The public list entry is the stripped shape (no `pr`).
    for (const entry of res.data) {
      expect(entry).toHaveProperty('name');
      expect(entry).toHaveProperty('title');
      expect(entry).toHaveProperty('version');
      expect(entry).not.toHaveProperty('pr');
    }
  });

  it('runs registry-only mode without --from', async () => {
    fs.mkdirSync(path.join(tmpDir, 'src'), {recursive: true});

    const res = await upgrade({registry: true, apply: false}, {cwd: tmpDir});

    expect(res).toMatchObject({
      type: 'upgrade.registry',
      data: {applied: false, found: 0, conflicts: 0, failed: 0},
    });
  });

  it('requires installed Astryx packages when receipts exist', async () => {
    writeRegistryFixture(tmpDir);

    await expect(
      upgrade({registry: true, apply: true}, {cwd: tmpDir}),
    ).rejects.toMatchObject({code: ERROR_CODES.ERR_VERSION_DETECT});
  });

  it('rejects combining --list with registry-only mode', async () => {
    await expect(
      upgrade({list: true, registry: true}, {cwd: tmpDir}),
    ).rejects.toMatchObject({code: ERROR_CODES.ERR_INVALID_ARGUMENT});
  });

  it('checks receipts on the up-to-date short circuit', async () => {
    writePkg(tmpDir);
    writeInstalledCore(tmpDir, '0.6.0');
    const {sourcePath} = writeRegistryFixture(tmpDir);

    const res = await upgrade({from: '0.6.0', apply: true}, {cwd: tmpDir});

    expect(res).toMatchObject({
      type: 'upgrade.status',
      data: {
        status: 'up_to_date',
        registryCompositions: {found: 1, updated: 1, conflicts: 0},
      },
    });
    expect(fs.readFileSync(sourcePath, 'utf8')).toBe('new\n');
  });

  it('checks receipts on the no-codemods short circuit', async () => {
    writePkg(tmpDir);
    writeInstalledCore(tmpDir, '99.0.0');
    const {sourcePath} = writeRegistryFixture(tmpDir, {version: '99.0.0'});

    const res = await upgrade({from: '98.0.0', apply: false}, {cwd: tmpDir});

    expect(res).toMatchObject({
      type: 'upgrade.status',
      data: {
        status: 'no_codemods',
        registryCompositions: {found: 1, wouldUpdate: 1},
      },
    });
    expect(fs.readFileSync(sourcePath, 'utf8')).toBe('old\n');
  });

  it('rejects migration flags in registry-only mode', async () => {
    await expect(
      upgrade({registry: true, from: '0.5.0', apply: true}, {cwd: tmpDir}),
    ).rejects.toMatchObject({code: ERROR_CODES.ERR_INVALID_ARGUMENT});
  });

  it('honors cwd: refreshes a stale agent-docs block on the up-to-date path (--apply)', async () => {
    // from == installed → up_to_date short-circuit (returns before the codemod
    // runner), so this exercises detection + agent-docs purely via the cwd
    // option, with NO process.chdir.
    writePkg(tmpDir);
    writeInstalledCore(tmpDir, '0.0.15');
    writeAgentBlock(tmpDir, 'AGENTS.md', '0.0.1');

    const res = await upgrade({from: '0.0.15', apply: true}, {cwd: tmpDir});

    expect(res.type).toBe('upgrade.status');
    expect(res.data.status).toBe('up_to_date');
    expect(res.data.from).toBe('0.0.15');
    expect(res.data.to).toBe('0.0.15');
    expect(res.data.agentDocs.action).toBe('refreshed');
    expect(res.data.agentDocs.refreshed).toBe(true);
    expect(res.data.agentDocs.files).toContain('AGENTS.md');
    // The file at the *cwd* fixture was rewritten to the installed version.
    const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
    expect(content).toMatch(/Astryx v0\.0\.15 ·/);
    expect(content).not.toMatch(/Astryx v0\.0\.1 ·/);
  });

  it('leaves the block of a project at the top of a home settings folder, saying why and not pointing at init', async () => {
    const saved = {
      HOME: process.env.HOME,
      USERPROFILE: process.env.USERPROFILE,
    };
    process.env.HOME = tmpDir;
    process.env.USERPROFILE = tmpDir;
    const warned = [];
    const warn = vi
      .spyOn(console, 'error')
      .mockImplementation((...a) => warned.push(a.join(' ')));
    logger.setSilent(false);
    try {
      const project = path.join(tmpDir, '.dotfiles');
      fs.mkdirSync(project, {recursive: true});
      writePkg(project, {'@astryxdesign/core': '0.0.15'});
      writeInstalledCore(project, '0.0.15');
      writeAgentBlock(project, 'AGENTS.md', '0.0.1');

      const res = await upgrade({from: '0.0.15', apply: true}, {cwd: project});

      expect(res.data.agentDocs.action).toBe('error');
      expect(res.data.agentDocs.refreshed).toBe(false);
      expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toMatch(
        /Astryx v0\.0\.1 ·/,
      );
      const text = warned.join('\n');
      expect(text).toContain(
        `Agent docs not refreshed: ${fs.realpathSync(project)} is the home folder or a settings folder in it, which every project's agents read. To keep agent docs, move the project into a folder of its own; otherwise update or remove the Astryx block there by hand.`,
      );
      expect(text).not.toContain('init --features agents');
    } finally {
      logger.setSilent(true);
      warn.mockRestore();
      for (const [key, value] of Object.entries(saved)) {
        if (value === undefined) delete process.env[key];
        else process.env[key] = value;
      }
    }
  });

  it('with no block, in a project at the top of a home settings folder, says why instead of pointing at init', async () => {
    const saved = {
      HOME: process.env.HOME,
      USERPROFILE: process.env.USERPROFILE,
    };
    process.env.HOME = tmpDir;
    process.env.USERPROFILE = tmpDir;
    const warned = [];
    const warn = vi
      .spyOn(console, 'error')
      .mockImplementation((...a) => warned.push(a.join(' ')));
    logger.setSilent(false);
    try {
      const project = path.join(tmpDir, '.dotfiles');
      fs.mkdirSync(project, {recursive: true});
      writePkg(project, {'@astryxdesign/core': '0.0.15'});
      writeInstalledCore(project, '0.0.15');

      const res = await upgrade({from: '0.0.15'}, {cwd: project});

      expect(res.data.agentDocs.action).toBe('error');
      const text = warned.join('\n');
      expect(text).toContain(
        `Agent docs not installed: ${fs.realpathSync(project)} is the home folder or a settings folder in it, which every project's agents read. To have agent docs, move the project into a folder of its own, or add the Astryx block to its agent file by hand.`,
      );
      expect(text).not.toContain('init --features agents');
    } finally {
      logger.setSilent(true);
      warn.mockRestore();
      for (const [key, value] of Object.entries(saved)) {
        if (value === undefined) delete process.env[key];
        else process.env[key] = value;
      }
    }
  });

  it('a dry run in a project at the top of a home settings folder reports the refusal, not a refresh to apply', async () => {
    const saved = {
      HOME: process.env.HOME,
      USERPROFILE: process.env.USERPROFILE,
    };
    process.env.HOME = tmpDir;
    process.env.USERPROFILE = tmpDir;
    const warned = [];
    const warn = vi
      .spyOn(console, 'error')
      .mockImplementation((...a) => warned.push(a.join(' ')));
    logger.setSilent(false);
    try {
      const project = path.join(tmpDir, '.dotfiles');
      fs.mkdirSync(project, {recursive: true});
      writePkg(project, {'@astryxdesign/core': '0.0.15'});
      writeInstalledCore(project, '0.0.15');
      writeAgentBlock(project, 'AGENTS.md', '0.0.1');

      const res = await upgrade({from: '0.0.15'}, {cwd: project});

      expect(res.data.agentDocs.action).toBe('error');
      expect(res.data.agentDocs.refreshed).toBe(false);
      const text = warned.join('\n');
      expect(text).toContain(
        `Agent docs not refreshed: ${fs.realpathSync(project)} is the home folder or a settings folder in it`,
      );
      expect(text).not.toContain('--apply to refresh');
      expect(text).not.toContain('init --features agents');
    } finally {
      logger.setSilent(true);
      warn.mockRestore();
      for (const [key, value] of Object.entries(saved)) {
        if (value === undefined) delete process.env[key];
        else process.env[key] = value;
      }
    }
  });

  it('refreshes the agent docs of a project in an agent worktree inside a home settings folder', async () => {
    const saved = {
      HOME: process.env.HOME,
      USERPROFILE: process.env.USERPROFILE,
    };
    process.env.HOME = tmpDir;
    process.env.USERPROFILE = tmpDir;
    try {
      const project = path.join(tmpDir, '.codex', 'worktrees', 'a1b2c3', 'web');
      fs.mkdirSync(project, {recursive: true});
      writePkg(project, {'@astryxdesign/core': '0.0.15'});
      writeInstalledCore(project, '0.0.15');
      writeAgentBlock(project, 'AGENTS.md', '0.0.1');

      const res = await upgrade({from: '0.0.15', apply: true}, {cwd: project});

      expect(res.data.agentDocs.action).toBe('refreshed');
      expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toMatch(
        /Astryx v0\.0\.15 ·/,
      );
    } finally {
      for (const [key, value] of Object.entries(saved)) {
        if (value === undefined) delete process.env[key];
        else process.env[key] = value;
      }
    }
  });

  it('refreshes the managed block in an ignored .claude/CLAUDE.md and keeps the text around it (INV31)', async () => {
    writePkg(tmpDir);
    writeInstalledCore(tmpDir, '0.0.15');
    writeAgentBlock(tmpDir, 'AGENTS.md', '0.0.1');
    fs.mkdirSync(path.join(tmpDir, '.claude'));
    writeAgentBlock(tmpDir, '.claude/CLAUDE.md', '0.0.1');
    const claude = path.join(tmpDir, '.claude', 'CLAUDE.md');
    fs.writeFileSync(
      claude,
      `# Team notes\n\n${fs.readFileSync(claude, 'utf-8')}\nMore notes.\n`,
    );
    fs.writeFileSync(path.join(tmpDir, '.gitignore'), '.claude/\n');

    const res = await upgrade({from: '0.0.15', apply: true}, {cwd: tmpDir});

    expect(res.data.agentDocs.action).toBe('refreshed');
    expect(res.data.agentDocs.files).toEqual([
      'AGENTS.md',
      '.claude/CLAUDE.md',
    ]);
    expect(res.data.agentDocs).not.toHaveProperty('protectedFiles');
    const content = fs.readFileSync(claude, 'utf-8');
    expect(content).toMatch(/^# Team notes\n/u);
    expect(content).toMatch(/Astryx v0\.0\.15 ·/u);
    expect(content).toMatch(/More notes\.\n$/u);
  });

  it('refreshes a committed .claude/CLAUDE.md that imports AGENTS.md and keeps a copy beside an ignored root CLAUDE.md', async () => {
    writePkg(tmpDir);
    writeInstalledCore(tmpDir, '0.0.15');
    writeAgentBlock(tmpDir, 'AGENTS.md', '0.0.1');
    writeAgentBlock(tmpDir, 'CLAUDE.md', '0.0.1');
    fs.writeFileSync(path.join(tmpDir, '.gitignore'), '/CLAUDE.md\n');
    fs.mkdirSync(path.join(tmpDir, '.claude'));
    const copy = path.join(tmpDir, '.claude', 'CLAUDE.md');
    fs.writeFileSync(
      copy,
      `@../AGENTS.md\n\n${generateCompressedIndex('0.0.1')}\n`,
    );

    for (let round = 0; round < 2; round++) {
      await upgrade({from: '0.0.15', apply: true}, {cwd: tmpDir});
      const content = fs.readFileSync(copy, 'utf-8');
      expect(content, `round ${round}`).toMatch(/^@\.\.\/AGENTS\.md\n/u);
      expect(content, `round ${round}`).toMatch(/Astryx v0\.0\.15 ·/u);
    }
    const dry = await upgrade({from: '0.0.15'}, {cwd: tmpDir});
    expect(dry.data.agentDocs.status).toBe('current');
  });

  it('reports would-refresh on a dry run without writing (honors cwd)', async () => {
    writePkg(tmpDir);
    writeInstalledCore(tmpDir, '0.0.15');
    writeAgentBlock(tmpDir, 'AGENTS.md', '0.0.1');
    const before = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');

    const res = await upgrade({from: '0.0.15'}, {cwd: tmpDir});

    expect(res.data.status).toBe('up_to_date');
    expect(res.data.agentDocs.action).toBe('would-refresh');
    expect(res.data.agentDocs.refreshed).toBe(false);
    expect(fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')).toBe(
      before,
    );
  });

  it('returns upgrade.run for an applicable range', async () => {
    // Codemod scanning is process.cwd()-relative, so chdir into the fixture.
    writePkg(tmpDir);
    writeInstalledCore(tmpDir, '0.0.15');
    fs.mkdirSync(path.join(tmpDir, 'src'), {recursive: true});
    fs.writeFileSync(path.join(tmpDir, 'src', 'index.ts'), 'const x = 1;\n');
    process.chdir(tmpDir);

    const res = await upgrade(
      {from: '0.0.1', apply: false, path: 'src'},
      {cwd: tmpDir},
    );

    expect(res.type).toBe('upgrade.run');
    expect(res.data.from).toBe('0.0.1');
    expect(res.data.to).toBe('0.0.15');
    expect(typeof res.data.codemods).toBe('number');
    expect(res.data.agentDocs).toBeDefined();
  });

  it('checks receipts on a normal codemod run', async () => {
    writePkg(tmpDir);
    writeInstalledCore(tmpDir, '0.0.15');
    const {sourcePath} = writeRegistryFixture(tmpDir, {
      base: "export const value = 'old';\n",
      latest: "export const value = 'new';\n",
      version: '0.0.15',
    });

    const res = await upgrade(
      {from: '0.0.1', apply: false, path: 'src'},
      {cwd: tmpDir},
    );

    expect(res).toMatchObject({
      type: 'upgrade.run',
      data: {registryCompositions: {found: 1, wouldUpdate: 1}},
    });
    expect(fs.readFileSync(sourcePath, 'utf8')).toBe(
      "export const value = 'old';\n",
    );
  });
});

describe('upgrade() — honors cwd for codemod scanning (no chdir)', () => {
  it('scans the cwd source tree, not process.cwd()', async () => {
    // Fixture lives in tmpDir; process.cwd() stays the repo root (NO chdir).
    // The codemod runner resolves --path against the API cwd, so it must scan
    // tmpDir/src — regression guard for the earlier process.cwd()-relative bug.
    writePkg(tmpDir);
    writeInstalledCore(tmpDir, '0.0.15');
    fs.mkdirSync(path.join(tmpDir, 'src'), {recursive: true});
    fs.writeFileSync(path.join(tmpDir, 'src', 'index.ts'), 'const x = 1;\n');

    // Capture stdout: the runner logs the directory it scans. Enabling the
    // shared logger keeps the runner non-silent so its scan line is emitted.
    const out = [];
    vi.spyOn(console, 'log').mockImplementation((...a) =>
      out.push(a.join(' ')),
    );
    vi.spyOn(process.stdout, 'write').mockImplementation(c => {
      out.push(typeof c === 'string' ? c : c.toString());
      return true;
    });
    logger.setSilent(false);

    const res = await upgrade(
      {from: '0.0.1', apply: false, path: 'src'},
      {cwd: tmpDir},
    );

    const joined = out.join('\n');
    expect(res.type).toBe('upgrade.run');
    // Scanned the cwd tree…
    expect(joined).toContain(path.join(tmpDir, 'src'));
    // …and did NOT report the path missing (which is what the old,
    // process.cwd()-relative resolution produced here).
    expect(joined).not.toMatch(/Source path not found/);
  });
});

describe('upgrade() — errors throw AstryxError', () => {
  it('missing --from → ERR_INVALID_ARGUMENT', async () => {
    writePkg(tmpDir);
    writeInstalledCore(tmpDir, '0.0.15');
    await expect(upgrade({}, {cwd: tmpDir})).rejects.toMatchObject({
      name: 'AstryxError',
      code: ERROR_CODES.ERR_INVALID_ARGUMENT,
    });
    await expect(upgrade({}, {cwd: tmpDir})).rejects.toThrow(
      /Missing required --from/,
    );
  });

  it('invalid --from → ERR_INVALID_VERSION', async () => {
    writePkg(tmpDir);
    writeInstalledCore(tmpDir, '0.0.15');
    await expect(
      upgrade({from: 'not-a-version'}, {cwd: tmpDir}),
    ).rejects.toMatchObject({
      code: ERROR_CODES.ERR_INVALID_VERSION,
    });
  });

  it('no installed core → ERR_VERSION_DETECT (uses the cwd option to look)', async () => {
    // Empty cwd (no node_modules/@astryxdesign/core) — detection must fail here,
    // proving the cwd option routes version detection.
    writePkg(tmpDir);
    const err = await upgrade({from: '0.0.1'}, {cwd: tmpDir}).catch(e => e);
    expect(err).toBeInstanceOf(AstryxError);
    expect(err.code).toBe(ERROR_CODES.ERR_VERSION_DETECT);
  });
});

describe('upgrade() — silent by default (noopLogger)', () => {
  it('prints nothing to stdout when called programmatically', async () => {
    writePkg(tmpDir);
    writeInstalledCore(tmpDir, '0.0.15');
    writeAgentBlock(tmpDir, 'AGENTS.md', '0.0.1');

    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    const outSpy = vi
      .spyOn(process.stdout, 'write')
      .mockImplementation(() => true);

    const res = await upgrade({from: '0.0.15', apply: true}, {cwd: tmpDir});

    // The receipt still comes back…
    expect(res.data.agentDocs.action).toBe('refreshed');
    // …but a scripted caller sees zero human output (default noopLogger).
    expect(logSpy).not.toHaveBeenCalled();
    expect(outSpy).not.toHaveBeenCalled();
    expect(errSpy).not.toHaveBeenCalled();
  });
});