@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.3-canary.02f5fe4

package/api/discover/_adapter.test.mjs

@@ -1,16 +1,36 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Tests for how the discover adapter calls discover sources: order,
- * failure isolation, timeouts, and the saved copy. Sources are plain functions
- * on a stand-in project, and the saved copies go to a temp directory.
+ * @file Tests for how the discover adapter reads the official list and calls
+ * discover sources: order, failure isolation, timeouts, and the saved copy,
+ * plus what the official list adds to the installed list and the add command.
+ * Sources are plain functions on a stand-in project, and the saved copies go
+ * to a temp directory.
  */
 
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import {callSources} from './_adapter.mjs';
+import {
+  addCommand,
+  callSources,
+  OFFICIAL_LIST_FILE,
+  officialDeclarations,
+  officialList,
+  withDeclaredOfficial,
+} from './_adapter.mjs';
+import {parseDiscoverCatalog} from '../../authoring/discover/parse.mjs';
+import {
+  _resetHostedRun,
+  activateHostedRun,
+} from '../../foundation/runtime/package-root.mjs';
+
+/** No official packages, so a test sees only its own sources after it. */
+const NO_OFFICIAL = {packages: []};
+
+/** How the official list reports itself among the sources. */
+const OFFICIAL_STATE = ['Astryx', '@astryxdesign/cli', 'fresh'];
 
 /**
  * @param {string} name
@@ -43,11 +63,28 @@ function pkg(name, extra = {}) {
 }
 
 /**
- * @param {{config?: object, integrations?: object[]}} parts
+ * @param {{config?: object, integrations?: object[], cwd?: string}} parts
  * @returns {any}
  */
-function project({config = {}, integrations = []}) {
-  return {config, loadedIntegrations: integrations, cwd: '/virtual/project'};
+function project({config = {}, integrations = [], cwd = '/virtual/project'}) {
+  return {config, loadedIntegrations: integrations, cwd};
+}
+
+/**
+ * An official package as officialList() returns it.
+ * @param {string} name
+ * @param {object} [extra]
+ */
+function official(name, extra = {}) {
+  return {
+    ...pkg(name, {latest: '0.7.1'}),
+    versions: [
+      {version: '0.7.1', publishedAt: null, prerelease: false, status: 'ok'},
+    ],
+    contributions: [{kind: 'theme', name: name.split('-').pop()}],
+    pin: '0.7.1',
+    ...extra,
+  };
 }
 
 let cacheDir;
@@ -82,13 +119,14 @@ describe('callSources', () => {
         ],
       }),
       {},
-      {cacheDir},
+      {cacheDir, official: NO_OFFICIAL},
     );
 
     expect(calls).toEqual(['own', 'shared']);
     expect(result.sources.map(s => [s.name, s.from, s.status])).toEqual([
       ['Own', 'astryx.config', 'fresh'],
       ['Shared', '@x/first', 'fresh'],
+      OFFICIAL_STATE,
     ]);
     expect(result.packages.map(p => [p.package, p.latest, p.source])).toEqual([
       ['@a/one', '9.9.9', 'Own'],
@@ -102,7 +140,7 @@ describe('callSources', () => {
     await callSources(
       project({integrations: [{name: '@x/src', __discover: source}]}),
       {package: '@a/one', version: '1.0.0'},
-      {cacheDir},
+      {cacheDir, official: NO_OFFICIAL},
     );
 
     expect(source).toHaveBeenCalledWith({
@@ -134,7 +172,7 @@ describe('callSources', () => {
         ],
       }),
       {},
-      {cacheDir},
+      {cacheDir, official: NO_OFFICIAL},
     );
 
     expect(result.sources.map(s => [s.from, s.status])).toEqual([
@@ -142,6 +180,7 @@ describe('callSources', () => {
       ['@x/bad', 'failed'],
       ['@x/broken', 'failed'],
       ['@x/good', 'fresh'],
+      ['@astryxdesign/cli', 'fresh'],
     ]);
     expect(result.sources[0].error).toContain('offline');
     expect(result.sources[1].error).toContain('schemaVersion 2');
@@ -160,7 +199,7 @@ describe('callSources', () => {
     const result = await callSources(
       project({integrations: [{name: '@x/slow', __discover: slow}]}),
       {},
-      {cacheDir, timeoutMs: 20},
+      {cacheDir, timeoutMs: 20, official: NO_OFFICIAL},
     );
 
     expect(result.sources[0]).toMatchObject({
@@ -177,10 +216,11 @@ describe('callSources', () => {
       return catalog('S', [pkg('@a/one')]);
     };
     const p = project({integrations: [{name: '@x/src', __discover: source}]});
+    const options = {cacheDir, official: NO_OFFICIAL};
 
-    await callSources(p, {}, {cacheDir});
+    await callSources(p, {}, options);
     online = false;
-    const offline = await callSources(p, {}, {cacheDir});
+    const offline = await callSources(p, {}, options);
 
     expect(offline.sources[0]).toMatchObject({
       name: 'S',
@@ -190,10 +230,48 @@ describe('callSources', () => {
     });
     expect(offline.packages.map(x => x.package)).toEqual(['@a/one']);
 
-    const otherRequest = await callSources(p, {package: '@a/one'}, {cacheDir});
+    const otherRequest = await callSources(p, {package: '@a/one'}, options);
     expect(otherRequest.sources[0].status).toBe('failed');
   });
 
+  it("keeps a host's saved copies per host, so one tool never answers with another's", async () => {
+    let online = true;
+    const source = async () => {
+      if (!online) throw new Error('offline');
+      return catalog('Acme catalog', [pkg('@acme/one')]);
+    };
+    const options = {cacheDir, official: NO_OFFICIAL};
+    try {
+      activateHostedRun({
+        discoverSources: [source],
+        startingRoot: '/tools/acme',
+      });
+      await callSources(undefined, {}, options);
+      online = false;
+      const sameHost = await callSources(undefined, {}, options);
+      expect(sameHost.sources[0]).toMatchObject({
+        name: 'Acme catalog',
+        from: 'the host',
+        status: 'saved',
+      });
+
+      _resetHostedRun();
+      activateHostedRun({
+        discoverSources: [source],
+        startingRoot: '/tools/other',
+      });
+      const otherHost = await callSources(undefined, {}, options);
+      expect(otherHost.sources[0]).toMatchObject({
+        from: 'the host',
+        status: 'failed',
+        error: 'offline',
+      });
+      expect(otherHost.packages).toEqual([]);
+    } finally {
+      _resetHostedRun();
+    }
+  });
+
   it('keeps the saved copy in the cache directory, not in the project', async () => {
     await callSources(
       project({
@@ -202,14 +280,560 @@ describe('callSources', () => {
         ],
       }),
       {},
-      {cacheDir},
+      {cacheDir, official: NO_OFFICIAL},
     );
 
     expect(fs.readdirSync(path.join(cacheDir, 'discover'))).toHaveLength(1);
     expect(fs.existsSync('/virtual/project')).toBe(false);
   });
 
-  it('returns nothing when there is no project', async () => {
-    expect(await callSources(undefined)).toEqual({sources: [], packages: []});
+  it('returns only the official list when there is no project', async () => {
+    const result = await callSources(
+      undefined,
+      {},
+      {official: {packages: [official('@astryxdesign/theme-gothic')]}},
+    );
+    expect(result.sources.map(s => [s.name, s.from, s.status])).toEqual([
+      OFFICIAL_STATE,
+    ]);
+    expect(result.packages.map(p => [p.package, p.source])).toEqual([
+      ['@astryxdesign/theme-gothic', 'Astryx'],
+    ]);
+  });
+
+  it('reads the official list last, so another source keeps its entry', async () => {
+    const own = async () =>
+      catalog('Own', [
+        pkg('@a/two'),
+        pkg('@astryxdesign/theme-matcha', {latest: '0.6.8'}),
+      ]);
+    const result = await callSources(
+      project({config: {discover: own}}),
+      {},
+      {
+        cacheDir,
+        official: {
+          packages: [
+            official('@astryxdesign/theme-gothic'),
+            official('@astryxdesign/theme-matcha'),
+          ],
+        },
+      },
+    );
+
+    expect(result.sources.map(s => [s.name, s.from, s.status])).toEqual([
+      ['Own', 'astryx.config', 'fresh'],
+      OFFICIAL_STATE,
+    ]);
+    // The add command's pin stays with the list; a catalog entry never
+    // carries it.
+    for (const entry of result.packages)
+      expect(entry).not.toHaveProperty('pin');
+    // Source order: discover puts official packages first only where it
+    // shows them.
+    expect(
+      result.packages.map(p => [p.package, p.latest, p.source, !!p.official]),
+    ).toEqual([
+      ['@a/two', '1.0.0', 'Own', false],
+      ['@astryxdesign/theme-matcha', '0.6.8', 'Own', false],
+      ['@astryxdesign/theme-gothic', '0.7.1', 'Astryx', true],
+    ]);
+  });
+
+  it('keeps a source’s package for an official integration it publishes under another name', async () => {
+    const own = async () =>
+      catalog('Own', [
+        pkg('@acme/gothic-fork', {
+          integration: '@astryxdesign/theme-gothic',
+          contributions: [{kind: 'theme', name: 'gothic'}],
+        }),
+        pkg('@acme/stone-mirror', {aliases: ['@astryxdesign/theme-stone']}),
+      ]);
+    const result = await callSources(
+      project({config: {discover: own}}),
+      {},
+      {
+        cacheDir,
+        official: {
+          packages: [
+            official('@astryxdesign/theme-gothic'),
+            official('@astryxdesign/theme-stone'),
+            official('@astryxdesign/theme-matcha'),
+          ],
+        },
+      },
+    );
+    expect(result.packages.map(p => [p.package, p.source])).toEqual([
+      ['@acme/gothic-fork', 'Own'],
+      ['@acme/stone-mirror', 'Own'],
+      ['@astryxdesign/theme-matcha', 'Astryx'],
+    ]);
+  });
+
+  it('answers a package request with only that official package', async () => {
+    const result = await callSources(
+      project({}),
+      {package: '@astryxdesign/theme-matcha'},
+      {
+        cacheDir,
+        official: {
+          packages: [
+            official('@astryxdesign/theme-gothic'),
+            official('@astryxdesign/theme-matcha'),
+          ],
+        },
+      },
+    );
+    expect(result.packages.map(p => p.package)).toEqual([
+      '@astryxdesign/theme-matcha',
+    ]);
+  });
+
+  it('reports an official list it could not read like a failed source', async () => {
+    const result = await callSources(
+      project({}),
+      {},
+      {cacheDir, official: {packages: [], error: 'the list is missing'}},
+    );
+    expect(result.sources.slice(-1)).toEqual([
+      {
+        name: 'Astryx',
+        from: '@astryxdesign/cli',
+        status: 'failed',
+        error: 'the list is missing',
+      },
+    ]);
+    expect(result.packages).toEqual([]);
+  });
+});
+
+/**
+ * A stand-in project folder whose installed Core is `version`.
+ * @param {string} dir
+ * @param {string} version
+ */
+function withCore(dir, version) {
+  const at = path.join(dir, 'node_modules', '@astryxdesign', 'core');
+  fs.mkdirSync(at, {recursive: true});
+  fs.writeFileSync(
+    path.join(at, 'package.json'),
+    JSON.stringify({name: '@astryxdesign/core', version}),
+  );
+  return project({cwd: dir});
+}
+
+/** The version an entry lists, with its latest. */
+const versionsOf = (
+  /** @type {{latest: string | null, versions: {version: string, prerelease: boolean}[]} | undefined} */ entry,
+) =>
+  entry && {
+    latest: entry.latest,
+    versions: entry.versions.map(v => [v.version, v.prerelease]),
+  };
+
+/** @param {{package: string}[]} packages @param {string} name */
+const find = (packages, name) => packages.find(p => p.package === name);
+
+const NEUTRAL = '@astryxdesign/theme-neutral';
+
+/** The canary-only package names in the committed list. */
+function canaryOnlyNames() {
+  return JSON.parse(fs.readFileSync(OFFICIAL_LIST_FILE, 'utf8'))
+    .packages.filter((/** @type {{canaryOnly?: boolean}} */ p) => p.canaryOnly)
+    .map((/** @type {{package: string}} */ p) => p.package);
+}
+
+describe('officialList', () => {
+  it('gives every official package the release CLI’s version when the project has no Core', () => {
+    const {packages, error} = officialList({version: '0.7.1'});
+    expect(error).toBeUndefined();
+    expect(packages.length).toBeGreaterThan(0);
+    for (const entry of packages) {
+      expect(entry.package.startsWith('@astryxdesign/')).toBe(true);
+      expect(versionsOf(entry)).toEqual({
+        latest: '0.7.1',
+        versions: [['0.7.1', false]],
+      });
+      expect(entry.contributions.length).toBeGreaterThan(0);
+    }
+    expect(packages.map(p => p.package)).toContain(NEUTRAL);
+    for (const name of canaryOnlyNames()) {
+      expect(find(packages, name)).toBeUndefined();
+    }
+  });
+
+  it('lists the latest release and the project’s Core version, and pins the Core version', () => {
+    for (const [core, latest, versions] of [
+      [
+        '0.6.8',
+        '0.7.1',
+        [
+          ['0.7.1', false],
+          ['0.6.8', false],
+        ],
+      ],
+      [
+        '0.8.0',
+        '0.8.0',
+        [
+          ['0.8.0', false],
+          ['0.7.1', false],
+        ],
+      ],
+      ['0.7.1', '0.7.1', [['0.7.1', false]]],
+      [
+        '0.7.1-canary.def5678',
+        '0.7.1',
+        [
+          ['0.7.1', false],
+          ['0.7.1-canary.def5678', true],
+        ],
+      ],
+      [
+        '0.7.2-canary.def5678',
+        '0.7.1',
+        [
+          ['0.7.2-canary.def5678', true],
+          ['0.7.1', false],
+        ],
+      ],
+    ]) {
+      const dir = fs.mkdtempSync(path.join(cacheDir, 'core-'));
+      const entry = find(
+        officialList({version: '0.7.1', project: withCore(dir, core)}).packages,
+        NEUTRAL,
+      );
+      expect(versionsOf(entry), core).toEqual({latest, versions});
+      expect(entry.pin, core).toBe(core);
+    }
+  });
+
+  it('pins the Core version or range a fresh clone declares, and nothing for another spec', () => {
+    const p = project({cwd: path.join(cacheDir, 'src')});
+    for (const [spec, pin, versions] of [
+      [
+        '0.6.8',
+        '0.6.8',
+        [
+          ['0.7.1', false],
+          ['0.6.8', false],
+        ],
+      ],
+      [
+        '=0.6.8',
+        '0.6.8',
+        [
+          ['0.7.1', false],
+          ['0.6.8', false],
+        ],
+      ],
+      ['^0.6.8', '^0.6.8', [['0.7.1', false]]],
+      ['>=0.6.8 <0.8.0', '>=0.6.8 <0.8.0', [['0.7.1', false]]],
+      ['0.6.x || ^0.7.0', '0.6.x || ^0.7.0', [['0.7.1', false]]],
+      // A space after an operator: node-semver reads both as >=0.6.8 <0.7.0.
+      ['~ 0.6.8', '~0.6.8', [['0.7.1', false]]],
+      ['>= 0.6.8 < 0.7.0', '>=0.6.8 <0.7.0', [['0.7.1', false]]],
+      ['workspace:*', '0.7.1', [['0.7.1', false]]],
+      ['file:../core', '0.7.1', [['0.7.1', false]]],
+      ['latest', '0.7.1', [['0.7.1', false]]],
+    ]) {
+      fs.writeFileSync(
+        path.join(cacheDir, 'package.json'),
+        JSON.stringify({devDependencies: {'@astryxdesign/core': spec}}),
+      );
+      const entry = find(
+        officialList({version: '0.7.1', project: p}).packages,
+        NEUTRAL,
+      );
+      expect(versionsOf(entry), spec).toEqual({latest: '0.7.1', versions});
+      expect(entry.pin, spec).toBe(pin);
+    }
+  });
+
+  it('on a canary CLI with no Core, pins only the canary-only packages', () => {
+    const canary = officialList({
+      version: '0.7.2-canary.abc1234',
+      project: project({cwd: cacheDir}),
+    }).packages;
+    expect(versionsOf(find(canary, NEUTRAL))).toEqual({
+      latest: null,
+      versions: [],
+    });
+    expect(find(canary, NEUTRAL).pin).toBeUndefined();
+    const names = canaryOnlyNames();
+    expect(names.length).toBeGreaterThan(0);
+    for (const name of names) {
+      expect(versionsOf(find(canary, name)), name).toEqual({
+        latest: null,
+        versions: [['0.7.2-canary.abc1234', true]],
+      });
+      expect(find(canary, name).pin, name).toBe('0.7.2-canary.abc1234');
+    }
+  });
+
+  it('lists the canary-only packages beside a canary Core, never beside a released one', () => {
+    const released = officialList({
+      version: '0.7.2-canary.abc1234',
+      project: withCore(cacheDir, '0.7.1'),
+    }).packages;
+    expect(versionsOf(find(released, NEUTRAL))).toEqual({
+      latest: '0.7.1',
+      versions: [['0.7.1', false]],
+    });
+    for (const name of canaryOnlyNames()) {
+      expect(find(released, name), name).toBeUndefined();
+    }
+
+    fs.writeFileSync(
+      path.join(cacheDir, 'package.json'),
+      JSON.stringify({dependencies: {'@astryxdesign/core': '^0.7.0'}}),
+    );
+    const declared = officialList({
+      version: '0.7.2-canary.abc1234',
+      project: project({cwd: cacheDir}),
+    }).packages;
+    for (const name of canaryOnlyNames()) {
+      expect(find(declared, name), name).toBeUndefined();
+    }
+
+    const beside = officialList({
+      version: '0.7.2-canary.abc1234',
+      project: withCore(cacheDir, '0.7.2-canary.def5678'),
+    }).packages;
+    for (const name of canaryOnlyNames()) {
+      expect(versionsOf(find(beside, name)), name).toEqual({
+        latest: null,
+        versions: [['0.7.2-canary.def5678', true]],
+      });
+    }
+  });
+
+  it('reads back as a valid discover catalog on a release and a canary CLI', () => {
+    for (const version of ['0.7.1', '0.7.2-canary.abc1234']) {
+      const packages = officialList({version}).packages.map(
+        ({pin: _pin, ...entry}) => entry,
+      );
+      const parsed = parseDiscoverCatalog(
+        catalog('Astryx', packages),
+        'the official list',
+      );
+      expect(parsed.packages).toEqual(packages);
+    }
+  });
+
+  it('reports a list it cannot read instead of throwing', () => {
+    const result = officialList({
+      file: path.join(cacheDir, 'missing.json'),
+      version: '0.7.1',
+    });
+    expect(result.packages).toEqual([]);
+    expect(result.error).toContain('the official list could not be read');
+  });
+
+  it('pins what each entry names, quoting a range, and the pin is a version it lists', () => {
+    for (const [cli, core, declared] of [
+      ['0.7.1', '0.6.8', undefined],
+      ['0.7.1', '0.8.0', undefined],
+      ['0.7.1', undefined, '^0.6.8'],
+      ['0.7.1', undefined, '>=0.6.8 <0.8.0'],
+      ['0.7.2-canary.abc1234', undefined, undefined],
+      ['0.7.2-canary.abc1234', '0.7.2-canary.def5678', undefined],
+    ]) {
+      const dir = fs.mkdtempSync(path.join(cacheDir, 'pin-'));
+      if (declared) {
+        fs.writeFileSync(
+          path.join(dir, 'package.json'),
+          JSON.stringify({dependencies: {'@astryxdesign/core': declared}}),
+        );
+      }
+      const p = core ? withCore(dir, core) : project({cwd: dir});
+      const {packages} = officialList({version: cli, project: p});
+      const add = addCommand(p, {official: packages});
+      for (const entry of packages) {
+        const label = `${cli} ${core ?? declared} ${entry.package}`;
+        const command = add(entry.package);
+        if (entry.pin == null) {
+          expect(command.endsWith(` ${entry.package}`), label).toBe(true);
+        } else if (entry.versions.some(v => v.version === entry.pin)) {
+          expect(
+            command.endsWith(` ${entry.package}@${entry.pin}`),
+            label,
+          ).toBe(true);
+        } else {
+          // Only a declared range is pinned without being a listed version.
+          expect(entry.pin, label).toBe(declared);
+          expect(
+            command.endsWith(` "${entry.package}@${declared}"`),
+            label,
+          ).toBe(true);
+        }
+      }
+    }
+  });
+});
+
+describe('officialDeclarations', () => {
+  const list = [
+    official('@astryxdesign/theme-gothic'),
+    official('@astryxdesign/theme-matcha'),
+    official('@astryxdesign/theme-stone'),
+  ];
+
+  it('reads the project’s own package.json from a subfolder, aliases included, and keeps peers apart', () => {
+    fs.writeFileSync(
+      path.join(cacheDir, 'package.json'),
+      JSON.stringify({
+        dependencies: {
+          'my-gothic': 'npm:@astryxdesign/theme-gothic@0.7.0',
+          react: '19.0.0',
+        },
+        devDependencies: {'@astryxdesign/theme-matcha': '0.7.0'},
+        peerDependencies: {'@astryxdesign/theme-stone': '>=0.7.0'},
+      }),
+    );
+    const declared = officialDeclarations(
+      project({cwd: path.join(cacheDir, 'src', 'components')}),
+      list,
+    );
+    expect([...declared.dependency]).toEqual([
+      ['@astryxdesign/theme-gothic', 'my-gothic'],
+      ['@astryxdesign/theme-matcha', '@astryxdesign/theme-matcha'],
+    ]);
+    expect([...declared.any].sort()).toEqual([
+      '@astryxdesign/theme-gothic',
+      '@astryxdesign/theme-matcha',
+      '@astryxdesign/theme-stone',
+    ]);
+  });
+});
+
+describe('withDeclaredOfficial', () => {
+  /** @param {string} dir @param {string} name @param {string} version */
+  function install(dir, name, version) {
+    const at = path.join(dir, 'node_modules', ...name.split('/'));
+    fs.mkdirSync(at, {recursive: true});
+    fs.writeFileSync(
+      path.join(at, 'package.json'),
+      JSON.stringify({name, version}),
+    );
+  }
+
+  /** @param {object[]} packages */
+  const result = packages => ({sources: [], packages});
+  /** @param {Array<[string, string]>} entries */
+  const declares = entries => ({
+    dependency: new Map(entries),
+    any: new Set(entries.map(([name]) => name)),
+  });
+  const gothic = {
+    ...official('@astryxdesign/theme-gothic', {description: 'Dark.'}),
+    source: 'Astryx',
+    official: true,
+  };
+
+  it('counts a declared official package as installed, first, with its installed version', () => {
+    install(cacheDir, '@astryxdesign/theme-gothic', '0.7.0');
+    const installed = withDeclaredOfficial(
+      project({cwd: cacheDir}),
+      [{name: '@acme/ui', category: '@acme/ui', components: []}],
+      result([gothic]),
+      declares([['@astryxdesign/theme-gothic', '@astryxdesign/theme-gothic']]),
+      [gothic],
+    );
+    expect(installed).toEqual([
+      {
+        name: '@astryxdesign/theme-gothic',
+        category: '@astryxdesign/theme-gothic',
+        version: '0.7.0',
+        description: 'Dark.',
+        components: [],
+        themes: ['gothic'],
+        declaredOfficial: true,
+      },
+      {name: '@acme/ui', category: '@acme/ui', components: []},
+    ]);
+  });
+
+  it('reads the version of a package installed under an npm alias', () => {
+    install(cacheDir, 'my-gothic', '0.6.8');
+    const [entry] = withDeclaredOfficial(
+      project({cwd: cacheDir}),
+      [],
+      result([gothic]),
+      declares([['@astryxdesign/theme-gothic', 'my-gothic']]),
+      [gothic],
+    );
+    expect(entry).toMatchObject({
+      name: '@astryxdesign/theme-gothic',
+      version: '0.6.8',
+    });
+  });
+
+  it('leaves a declared official package alone when another source supplied its entry', () => {
+    const fromOwn = {...gothic, source: 'Own', official: undefined};
+    expect(
+      withDeclaredOfficial(
+        project({cwd: cacheDir}),
+        [],
+        result([fromOwn]),
+        declares([
+          ['@astryxdesign/theme-gothic', '@astryxdesign/theme-gothic'],
+        ]),
+        [gothic],
+      ),
+    ).toEqual([]);
+  });
+
+  it('leaves out an official integration that failed to load, even when declared', () => {
+    expect(
+      withDeclaredOfficial(
+        project({
+          cwd: cacheDir,
+          integrations: [
+            {name: '@astryxdesign/theme-gothic', __loadError: 'x'},
+          ],
+        }),
+        [],
+        result([gothic]),
+        declares([
+          ['@astryxdesign/theme-gothic', '@astryxdesign/theme-gothic'],
+        ]),
+        [gothic],
+      ),
+    ).toEqual([]);
+  });
+});
+
+describe('addCommand with the official list', () => {
+  const list = [
+    official('@astryxdesign/theme-gothic', {pin: '0.6.8'}),
+    official('@astryxdesign/theme-matcha', {pin: '^0.6.8'}),
+    official('@astryxdesign/theme-stone', {pin: undefined}),
+    official('@astryxdesign/charts', {pin: '0.7.2-canary.abc1234'}),
+  ];
+  const add = () => addCommand(project({cwd: cacheDir}), {official: list});
+
+  it('pins what an official entry names, quoting a range', () => {
+    const command = add();
+    expect(command('@astryxdesign/theme-gothic')).toMatch(
+      / @astryxdesign\/theme-gothic@0\.6\.8$/,
+    );
+    expect(command('@astryxdesign/theme-matcha')).toMatch(
+      / "@astryxdesign\/theme-matcha@\^0\.6\.8"$/,
+    );
+    expect(command('@astryxdesign/theme-stone')).toMatch(
+      / @astryxdesign\/theme-stone$/,
+    );
+    expect(command('@astryxdesign/charts')).toMatch(
+      / @astryxdesign\/charts@0\.7\.2-canary\.abc1234$/,
+    );
+  });
+
+  it('adds a version that was asked for, and leaves other packages alone', () => {
+    const command = add();
+    expect(command('@acme/ui')).toMatch(/ @acme\/ui$/);
+    expect(command('@astryxdesign/theme-matcha', '0.7.1')).toMatch(
+      / @astryxdesign\/theme-matcha@0\.7\.1$/,
+    );
   });
 });