@hiyve/cli 1.0.17 → 1.0.18

package/README.md

@@ -27,7 +27,7 @@ Authenticate with Hiyve and configure npm for @hiyve packages.
 npx @hiyve/cli login
 
 # Non-interactive (CI/CD)
-npx @hiyve/cli login --key sk_live_your_secret_key_here
+npx @hiyve/cli login --key pk_live_your_api_key_here
 ```
 
 ### `logout`
@@ -67,9 +67,11 @@ Templates: `basic`, `ai`, `full`
 
 ## Getting Your API Key
 
-1. Log in to the [Hiyve Developer Console](https://api.hiyve.dev)
+1. Log in to the [Hiyve Developer Console](https://console.hiyve.dev)
 2. Navigate to **API Keys** in the sidebar
-3. Copy your secret key (starts with `sk_test_` or `sk_live_`)
+3. Copy your **API key** (starts with `pk_test_` or `pk_live_`). The client
+   secret (`sk_*`) is for minting room tokens server-side and is **not** used
+   for registry login — the CLI rejects it.
 
 ## What Does Login Do?
 
@@ -78,8 +80,8 @@ The `login` command:
 1. Validates your API key with the Hiyve registry
 2. Adds two lines to your `~/.npmrc` file:
    ```
-   @hiyve:registry=https://api.hiyve.dev/registry/
-   //api.hiyve.dev/registry/:_authToken=sk_live_...
+   @hiyve:registry=https://registry.muziemedia.com/
+   //registry.muziemedia.com/:_authToken=pk_live_...
    ```
 
 This tells npm to fetch `@hiyve/*` packages from the private Hiyve registry instead of the public npm registry.
@@ -89,8 +91,8 @@ This tells npm to fetch `@hiyve/*` packages from the private Hiyve registry inst
 For automated deployments, add registry credentials as environment variables in your CI/CD pipeline. Your project `.npmrc` should use variable expansion:
 
 ```ini
-@hiyve:registry=https://api.hiyve.dev/registry/
-//api.hiyve.dev/registry/:_authToken=${HIYVE_API_KEY}
+@hiyve:registry=https://registry.muziemedia.com/
+//registry.muziemedia.com/:_authToken=${HIYVE_API_KEY}
 ```
 
 Set `HIYVE_API_KEY` in your CI environment (GitHub Actions secrets, AWS SSM, etc.). npm natively expands `${ENV_VAR}` in `.npmrc` files — no custom tooling needed.
@@ -99,7 +101,7 @@ Set `HIYVE_API_KEY` in your CI environment (GitHub Actions secrets, AWS SSM, etc
 
 ### "Invalid API key" error
 
-- Make sure your key starts with `sk_test_` or `sk_live_`
+- Make sure your key starts with `pk_test_` or `pk_live_` (not `sk_` — that is the client secret)
 - Verify your account is active in the developer console
 
 ### "Connection failed" error

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hiyve/cli",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "description": "Hiyve SDK CLI - Configure npm for private @hiyve packages",
   "type": "module",
   "bin": {
@@ -13,8 +13,7 @@
   ],
   "scripts": {
     "test": "vitest run --pool=forks --poolOptions.forks.singleFork",
-    "test:watch": "vitest",
-    "deploy": "./deploy.sh"
+    "test:watch": "vitest"
   },
   "keywords": [
     "hiyve",

package/src/commands/list.js

@@ -6,9 +6,9 @@
 
 import chalk from 'chalk';
 import ora from 'ora';
-import { getApiUrl } from '../config.js';
+import { fetchPackageCatalogue } from '../utils/registryApi.js';
 import { getCurrentConfig } from '../utils/npmrc.js';
-import { printDevHint, printDevModeBanner, fetchWithTimeout } from '../utils/output.js';
+import { printDevHint, printDevModeBanner } from '../utils/output.js';
 
 /**
  * List available packages
@@ -32,22 +32,16 @@ export async function list() {
   const spinner = ora('Fetching packages...').start();
 
   try {
-    const response = await fetchWithTimeout(`${getApiUrl()}packages`, {
-      headers: {
-        Authorization: `Bearer ${config.apiKey}`,
-      },
-    });
+    const data = await fetchPackageCatalogue(config.apiKey);
 
-    if (!response.ok) {
+    if (!data.ok) {
       spinner.fail('Failed to fetch packages');
-      const error = await response.json().catch(() => ({ error: 'Unknown error' }));
       console.log('');
-      console.log(chalk.red(`  ${error.error || 'Failed to fetch packages'}`));
+      console.log(chalk.red(`  ${data.error}`));
       printDevHint('list');
       process.exit(1);
     }
 
-    const data = await response.json();
     spinner.succeed(`Found ${data.total} packages`);
     console.log('');
 
@@ -55,7 +49,7 @@ export async function list() {
     if (data.sdk?.length > 0) {
       console.log(chalk.white.bold('SDK Packages:'));
       for (const pkg of data.sdk) {
-        console.log(chalk.cyan(`  ${pkg.name}`));
+        console.log(chalk.cyan(`  ${pkg.name}`) + (pkg.version ? chalk.gray(`  ${pkg.version}`) : ''));
       }
       console.log('');
     }
@@ -64,7 +58,7 @@ export async function list() {
     if (data.components?.length > 0) {
       console.log(chalk.white.bold('Component Packages:'));
       for (const pkg of data.components) {
-        console.log(chalk.cyan(`  ${pkg.name}`));
+        console.log(chalk.cyan(`  ${pkg.name}`) + (pkg.version ? chalk.gray(`  ${pkg.version}`) : ''));
       }
       console.log('');
     }

package/src/commands/login.js

@@ -8,8 +8,9 @@ import prompts from 'prompts';
 import chalk from 'chalk';
 import ora from 'ora';
 import { configureNpmrc } from '../utils/npmrc.js';
-import { getApiUrl, getRegistryUrl } from '../config.js';
-import { printDevHint, printDevModeBanner, fetchWithTimeout } from '../utils/output.js';
+import { getRegistryUrl } from '../config.js';
+import { verifyApiKey, fetchPackageCatalogue } from '../utils/registryApi.js';
+import { printDevHint, printDevModeBanner } from '../utils/output.js';
 
 /**
  * Login to Hiyve and configure npm
@@ -77,31 +78,18 @@ export async function login(options) {
   const spinner = ora('Verifying API key...').start();
 
   try {
-    const response = await fetchWithTimeout(`${getApiUrl()}verify`, {
-      headers: {
-        Authorization: `Bearer ${apiKey}`,
-      },
-    });
+    const result = await verifyApiKey(apiKey);
 
-    if (!response.ok) {
-      const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+    if (!result.ok) {
       spinner.fail('API key verification failed');
       console.log('');
-      console.log(chalk.red(`  ${error.error || 'Invalid API key'}`));
+      console.log(chalk.red(`  ${result.error}`));
       printDevHint('login');
       process.exit(1);
     }
 
-    const data = await response.json();
     spinner.succeed('API key verified');
-
-    // Server returns a masked key — always mask client-side as a safety net
-    if (data.apiKey) {
-      const display = data.apiKey.length > 12
-        ? `${data.apiKey.slice(0, 8)}...${data.apiKey.slice(-4)}`
-        : data.apiKey;
-      console.log(chalk.gray(`  Account: ${display}`));
-    }
+    console.log(chalk.gray(`  Account: ${result.apiKey}`));
   } catch (err) {
     if (err.name === 'AbortError') {
       spinner.fail('Request timed out');
@@ -137,13 +125,9 @@ export async function login(options) {
 
   // Fetch available packages from registry
   try {
-    const packagesResponse = await fetchWithTimeout(`${getApiUrl()}packages`, {
-      headers: { Authorization: `Bearer ${apiKey}` },
-    });
-
-    if (packagesResponse.ok) {
-      const packages = await packagesResponse.json();
+    const packages = await fetchPackageCatalogue(apiKey);
 
+    if (packages.ok) {
       console.log(`You can now install ${packages.total} Hiyve packages:`);
       console.log('');
 

package/src/commands/whoami.js

@@ -7,7 +7,7 @@
 import chalk from 'chalk';
 import ora from 'ora';
 import { getCurrentConfig } from '../utils/npmrc.js';
-import { getApiUrl } from '../config.js';
+import { verifyApiKey } from '../utils/registryApi.js';
 
 /**
  * Show current authentication status
@@ -39,19 +39,10 @@ export async function whoami() {
     const spinner = ora('Verifying with server...').start();
 
     try {
-      const response = await fetch(`${getApiUrl()}verify`, {
-        headers: {
-          Authorization: `Bearer ${config.apiKey}`,
-        },
-      });
+      const result = await verifyApiKey(config.apiKey);
 
-      if (response.ok) {
-        const data = await response.json();
+      if (result.ok) {
         spinner.succeed('API key is valid');
-
-        if (data.email) {
-          console.log(`  Email:     ${chalk.cyan(data.email)}`);
-        }
       } else {
         spinner.warn('API key may be invalid or expired');
         console.log('');

package/src/config.js

@@ -1,35 +1,20 @@
 /**
  * Hiyve CLI Configuration
  *
- * Two URLs matter:
- *   - API URL: where the CLI talks to (verify, list, packages). Switches with --dev.
- *   - Registry URL: what goes into ~/.npmrc for npm to fetch tarballs. Always prod.
- */
-
-// The CLI's own API — key verification and the package catalogue, served by
-// hiyve-cloud at /registry/{verify,packages}.
-const PROD_API_URL = 'https://cloud.hiyve.io/registry/';
-// No separate development cloud exists — kept so --dev stays a valid flag,
-// but it reaches the SAME live host (2026-08-24).
-const DEV_API_URL = 'https://cloud.hiyve.io/registry/';
-
-/**
- * Where npm actually fetches tarballs. DELIBERATELY NOT the API URL.
+ * One host: registry.muziemedia.com, the Verdaccio registry `changeset
+ * publish` writes to. It is both where npm fetches tarballs (what `login`
+ * puts in ~/.npmrc) and where the CLI verifies keys and lists packages,
+ * through standard npm endpoints — see utils/registryApi.js.
  *
- * This used to return getApiUrl(), on the assumption that "tarballs are
- * served through the same API". They are not: the cloud's /registry proxy
- * serves a stale catalogue whose `dist.tarball` URLs still name
- * api.muziemedia.com — a host with no DNS record — so a packument fetch
- * succeeded and the download that followed failed with ENOTFOUND. npm does
- * not rewrite tarball hosts for a non-npmjs registry, so the URL in the
- * metadata is the URL it uses.
- *
- * registry.muziemedia.com is the Verdaccio registry `changeset publish`
- * actually publishes to. Verified 2026-08-24 with a customer pk_ key: it
- * authenticates API keys natively (the proxy is not needed for auth),
- * serves current versions, its tarball URLs point at itself, and the
- * download returns a valid package.
+ * The CLI used to talk to a separate API at cloud.hiyve.io/registry/
+ * ({verify,packages}). That is the retired S3-backed registry: a frozen
+ * catalogue (it still lists packages that no longer exist and reports
+ * versions five majors behind) whose tarball URLs once named
+ * api.muziemedia.com — a host with no DNS record. Nothing here should point
+ * at it again. `--dev` remains a valid flag but there is only one registry,
+ * so it changes nothing (there has been no separate dev host since 2026-08-24).
  */
+
 const REGISTRY_URL_VALUE = 'https://registry.muziemedia.com/';
 
 let _devMode = false;
@@ -42,16 +27,17 @@ export function setDevMode(enabled) {
 }
 
 /**
- * Get the API URL for CLI operations (verify, list, packages).
- * Switches between dev and prod based on --dev flag.
+ * Base URL for the CLI's own calls (verify, list). This IS the registry —
+ * kept as a separate function because index.js exports it and because the
+ * two roles were once different hosts. Ignores --dev: one registry.
  */
 export function getApiUrl() {
-  return _devMode ? DEV_API_URL : PROD_API_URL;
+  return REGISTRY_URL_VALUE;
 }
 
 /**
  * Get the registry URL for ~/.npmrc (where npm fetches tarballs).
- * Independent of the API URL, and of --dev: there is one registry.
+ * Ignores --dev: there is one registry.
  */
 export function getRegistryUrl() {
   return REGISTRY_URL_VALUE;
@@ -65,7 +51,6 @@ export function isDevMode() {
 }
 
 // Backwards-compatible named export
-// The npm registry, NOT the CLI API (they are different hosts — see above).
 export const REGISTRY_URL = REGISTRY_URL_VALUE;
 
 export default {

package/src/config.test.js

@@ -11,23 +11,29 @@ describe('config', () => {
     expect(config.REGISTRY_URL).toBe('https://registry.muziemedia.com/');
   });
 
-  it('getApiUrl returns prod URL by default', () => {
+  it('getApiUrl is the registry — there is no separate CLI API host', () => {
     setDevMode(false);
-    expect(getApiUrl()).toBe('https://cloud.hiyve.io/registry/');
+    expect(getApiUrl()).toBe('https://registry.muziemedia.com/');
   });
 
-  it('getApiUrl returns dev URL when dev mode is enabled', () => {
+  it('getApiUrl ignores dev mode', () => {
     setDevMode(true);
-    expect(getApiUrl()).toBe('https://cloud.hiyve.io/registry/');
+    expect(getApiUrl()).toBe('https://registry.muziemedia.com/');
     setDevMode(false);
   });
 
-  it('getRegistryUrl is the npm registry, NOT the API host', () => {
-    // These are different services: the API serves /verify and /packages
-    // from hiyve-cloud; npm fetches tarballs from Verdaccio. Conflating them
-    // shipped a registry whose tarball URLs pointed at a dead host.
+  it('never points at the retired S3-backed registry', () => {
+    // cloud.hiyve.io/registry/ still answers but serves a frozen catalogue
+    // (@hiyve/core 2.0.22 there vs 7.0.0 live) and once advertised tarballs
+    // on a host with no DNS record. The CLI must verify keys and list
+    // packages against the registry npm actually installs from.
+    expect(getApiUrl()).not.toContain('cloud.hiyve.io');
+    expect(getRegistryUrl()).not.toContain('cloud.hiyve.io');
+  });
+
+  it('getRegistryUrl and getApiUrl are the same host', () => {
     expect(getRegistryUrl()).toBe('https://registry.muziemedia.com/');
-    expect(getRegistryUrl()).not.toBe(getApiUrl());
+    expect(getRegistryUrl()).toBe(getApiUrl());
   });
 
   it('getRegistryUrl does NOT switch with dev mode — there is one registry', () => {

package/src/utils/registryApi.js

@@ -0,0 +1,145 @@
+/**
+ * The CLI's view of the npm registry.
+ *
+ * Every command used to call a bespoke API at cloud.hiyve.io/registry/
+ * ({verify,packages}). That is the retired S3-backed registry: its catalogue
+ * is frozen (it still lists @hiyve/auth, which no longer exists, and reports
+ * @hiyve/core at 2.0.22 against 7.0.0 live) and it is not where npm installs
+ * from. registry.muziemedia.com — the Verdaccio registry `changeset publish`
+ * writes to and the host `login` puts in ~/.npmrc — is the only source of
+ * truth, and it exposes everything the CLI needs through standard npm
+ * endpoints. Verified 2026-09-01:
+ *
+ *   GET /@hiyve/<pkg>              200 with a valid key, 401 without or with
+ *                                  a bad one. Packuments and tarballs are
+ *                                  both gated.
+ *   GET /-/whoami                  200 `{username}` for a valid key — but
+ *                                  ALSO 200 `{}` for a bad key or none, so
+ *                                  it cannot be the validity check.
+ *   GET /-/v1/search?text=@hiyve   200, the live catalogue; unauthenticated.
+ */
+
+import { getApiUrl } from '../config.js';
+import { fetchWithTimeout } from './output.js';
+
+/**
+ * A packument that always exists and is small. Fetching it with the key is
+ * the validity check: the response code is the registry's own verdict on
+ * whether this key can install @hiyve packages.
+ */
+const PROBE_PACKAGE = '@hiyve/cli';
+
+/** Verdaccio's search cap is per request; the catalogue is ~70 packages. */
+const SEARCH_PAGE_SIZE = 250;
+
+/**
+ * The packages the getting-started guide installs first. Listed as "SDK";
+ * everything else on the registry is listed as a component package. This
+ * is presentation only — it does not gate anything.
+ */
+const FOUNDATION_PACKAGES = new Set([
+  '@hiyve/core',
+  '@hiyve/react',
+  '@hiyve/react-ui',
+  '@hiyve/react-room',
+  '@hiyve/rtc-client',
+  '@hiyve/rtc-client-rn',
+  '@hiyve/utilities',
+  '@hiyve/admin',
+  '@hiyve/cloud',
+  '@hiyve/identity-client',
+  '@hiyve/cli',
+]);
+
+/**
+ * Mask an API key for display: `pk_live_...abcd`.
+ * @param {string} apiKey
+ * @returns {string}
+ */
+export function maskApiKey(apiKey) {
+  if (typeof apiKey !== 'string') return '';
+  return apiKey.length > 12 ? `${apiKey.slice(0, 8)}...${apiKey.slice(-4)}` : apiKey;
+}
+
+/**
+ * Verify an API key against the registry.
+ *
+ * @param {string} apiKey
+ * @returns {Promise<{ ok: true, apiKey: string } | { ok: false, status: number, error: string }>}
+ *   `apiKey` in the success shape is already masked.
+ * @throws on network failure / timeout (AbortError) — callers own that message.
+ */
+export async function verifyApiKey(apiKey) {
+  const response = await fetchWithTimeout(`${getApiUrl()}${PROBE_PACKAGE}`, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+
+  if (response.ok) {
+    return { ok: true, apiKey: maskApiKey(apiKey) };
+  }
+
+  const body = await response.json().catch(() => ({}));
+  const error =
+    body.error ||
+    (response.status === 401 || response.status === 403
+      ? 'Invalid API key'
+      : `Registry returned HTTP ${response.status}`);
+  return { ok: false, status: response.status, error };
+}
+
+/**
+ * Turn Verdaccio's search response into the catalogue the commands print.
+ * Exported for tests; `fetchPackageCatalogue` is the one commands call.
+ *
+ * @param {{ objects?: Array<{ package?: { name?: string, version?: string, 'dist-tags'?: { latest?: string } } }> }} searchResult
+ * @returns {{ total: number, sdk: Array<{name: string, version: string}>, components: Array<{name: string, version: string}> }}
+ */
+export function catalogueFromSearch(searchResult) {
+  const seen = new Set();
+  const packages = [];
+  for (const entry of searchResult?.objects ?? []) {
+    const name = entry?.package?.name;
+    if (typeof name !== 'string' || !name.startsWith('@hiyve/') || seen.has(name)) continue;
+    seen.add(name);
+    // Verdaccio's search objects carry the current version as
+    // `dist-tags.latest`, not `version` (that is the npmjs.com shape).
+    const pkg = entry.package;
+    const version = pkg.version ?? pkg['dist-tags']?.latest ?? '';
+    packages.push({ name, version });
+  }
+  packages.sort((a, b) => a.name.localeCompare(b.name));
+
+  return {
+    total: packages.length,
+    sdk: packages.filter((p) => FOUNDATION_PACKAGES.has(p.name)),
+    components: packages.filter((p) => !FOUNDATION_PACKAGES.has(p.name)),
+  };
+}
+
+/**
+ * List the @hiyve packages the registry currently serves.
+ *
+ * @param {string} apiKey
+ * @returns {Promise<{ ok: true, total: number, sdk: Array<{name: string, version: string}>, components: Array<{name: string, version: string}> } | { ok: false, status: number, error: string }>}
+ * @throws on network failure / timeout (AbortError)
+ */
+export async function fetchPackageCatalogue(apiKey) {
+  const url = `${getApiUrl()}-/v1/search?text=${encodeURIComponent('@hiyve')}&size=${SEARCH_PAGE_SIZE}`;
+  const response = await fetchWithTimeout(url, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+
+  if (!response.ok) {
+    const body = await response.json().catch(() => ({}));
+    return {
+      ok: false,
+      status: response.status,
+      error: body.error || `Registry returned HTTP ${response.status}`,
+    };
+  }
+
+  const searchResult = await response.json().catch(() => ({}));
+  return { ok: true, ...catalogueFromSearch(searchResult) };
+}
+
+export default { maskApiKey, verifyApiKey, catalogueFromSearch, fetchPackageCatalogue };

package/src/utils/registryApi.test.js

@@ -0,0 +1,169 @@
+/**
+ * The CLI verifies keys and lists packages against the ONE registry npm
+ * installs from, through standard npm endpoints. These tests pin the
+ * behaviours that the live registry forced (verified 2026-09-01):
+ *
+ *  - /-/whoami answers 200 `{}` for a bad key, so validity is decided by a
+ *    gated packument fetch (200 vs 401), never by whoami.
+ *  - the catalogue comes from /-/v1/search, restricted to the @hiyve scope,
+ *    de-duplicated, sorted, and split into SDK vs component packages.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+  maskApiKey,
+  verifyApiKey,
+  catalogueFromSearch,
+  fetchPackageCatalogue,
+} from './registryApi.js';
+
+const REGISTRY = 'https://registry.muziemedia.com/';
+const KEY = 'pk_live_0123456789abcdef0123456789abcdef01234567';
+
+function jsonResponse(status, body) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: () => Promise.resolve(body),
+  };
+}
+
+let fetchMock;
+beforeEach(() => {
+  fetchMock = vi.fn();
+  vi.stubGlobal('fetch', fetchMock);
+});
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('maskApiKey', () => {
+  it('keeps the prefix and last four characters only', () => {
+    expect(maskApiKey(KEY)).toBe('pk_live_...4567');
+  });
+  it('leaves a short value alone and tolerates non-strings', () => {
+    expect(maskApiKey('pk_short')).toBe('pk_short');
+    expect(maskApiKey(undefined)).toBe('');
+  });
+});
+
+describe('verifyApiKey', () => {
+  it('probes a gated packument on the registry with the key as a bearer token', async () => {
+    fetchMock.mockResolvedValue(jsonResponse(200, { name: '@hiyve/cli' }));
+    await verifyApiKey(KEY);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe(`${REGISTRY}@hiyve/cli`);
+    expect(init.headers.Authorization).toBe(`Bearer ${KEY}`);
+    expect(url).not.toContain('cloud.hiyve.io');
+    expect(url).not.toContain('/verify');
+  });
+
+  it('reports a masked key on success, never the raw one', async () => {
+    fetchMock.mockResolvedValue(jsonResponse(200, {}));
+    const result = await verifyApiKey(KEY);
+    expect(result).toEqual({ ok: true, apiKey: 'pk_live_...4567' });
+    expect(JSON.stringify(result)).not.toContain(KEY);
+  });
+
+  it('treats 401 as an invalid key', async () => {
+    fetchMock.mockResolvedValue(jsonResponse(401, {}));
+    const result = await verifyApiKey(KEY);
+    expect(result.ok).toBe(false);
+    expect(result.status).toBe(401);
+    expect(result.error).toBe('Invalid API key');
+  });
+
+  it('surfaces the registry error message when it sends one', async () => {
+    fetchMock.mockResolvedValue(jsonResponse(403, { error: 'key revoked' }));
+    const result = await verifyApiKey(KEY);
+    expect(result).toEqual({ ok: false, status: 403, error: 'key revoked' });
+  });
+
+  it('does not misreport an outage as a bad key', async () => {
+    fetchMock.mockResolvedValue({ ok: false, status: 502, json: () => Promise.reject(new Error('html')) });
+    const result = await verifyApiKey(KEY);
+    expect(result.ok).toBe(false);
+    expect(result.error).toBe('Registry returned HTTP 502');
+    expect(result.error).not.toMatch(/invalid/i);
+  });
+
+  it('lets network failures propagate for the caller to phrase', async () => {
+    const abort = Object.assign(new Error('aborted'), { name: 'AbortError' });
+    fetchMock.mockRejectedValue(abort);
+    await expect(verifyApiKey(KEY)).rejects.toBe(abort);
+  });
+});
+
+describe('catalogueFromSearch', () => {
+  const search = {
+    objects: [
+      { package: { name: '@hiyve/react-ui', version: '22.0.0' } },
+      { package: { name: '@hiyve/core', version: '7.0.0' } },
+      { package: { name: 'react', version: '19.0.0' } },          // not ours
+      { package: { name: '@hiyve/core', version: '7.0.0' } },     // duplicate
+      { package: { name: '@hiyve/whiteboard', version: '3.1.0' } },
+      { package: {} },                                            // malformed
+      {},
+    ],
+  };
+
+  it('keeps only @hiyve packages, de-duplicated and sorted', () => {
+    const cat = catalogueFromSearch(search);
+    const names = [...cat.sdk, ...cat.components].map((p) => p.name).sort();
+    expect(names).toEqual(['@hiyve/core', '@hiyve/react-ui', '@hiyve/whiteboard']);
+    expect(cat.total).toBe(3);
+  });
+
+  it('splits foundation packages from component packages', () => {
+    const cat = catalogueFromSearch(search);
+    expect(cat.sdk.map((p) => p.name)).toEqual(['@hiyve/core', '@hiyve/react-ui']);
+    expect(cat.components.map((p) => p.name)).toEqual(['@hiyve/whiteboard']);
+  });
+
+  it('carries the live version through', () => {
+    const cat = catalogueFromSearch(search);
+    expect(cat.sdk.find((p) => p.name === '@hiyve/core').version).toBe('7.0.0');
+  });
+
+  it("reads the version from Verdaccio's dist-tags.latest (its search has no `version`)", () => {
+    const cat = catalogueFromSearch({
+      objects: [{ package: { name: '@hiyve/admin', 'dist-tags': { latest: '2.3.0' } } }],
+    });
+    expect(cat.sdk).toEqual([{ name: '@hiyve/admin', version: '2.3.0' }]);
+  });
+
+  it('is empty, not broken, for a missing or empty result', () => {
+    expect(catalogueFromSearch(undefined)).toEqual({ total: 0, sdk: [], components: [] });
+    expect(catalogueFromSearch({})).toEqual({ total: 0, sdk: [], components: [] });
+  });
+});
+
+describe('fetchPackageCatalogue', () => {
+  it('searches the @hiyve scope on the registry, not the retired catalogue', async () => {
+    fetchMock.mockResolvedValue(jsonResponse(200, { objects: [] }));
+    await fetchPackageCatalogue(KEY);
+    const [url] = fetchMock.mock.calls[0];
+    expect(url.startsWith(`${REGISTRY}-/v1/search?`)).toBe(true);
+    expect(url).toContain('text=%40hiyve');
+    expect(url).not.toContain('cloud.hiyve.io');
+    expect(url).not.toContain('/packages');
+  });
+
+  it('returns the catalogue shape the commands print', async () => {
+    fetchMock.mockResolvedValue(
+      jsonResponse(200, { objects: [{ package: { name: '@hiyve/rtc-client', version: '2.5.0' } }] }),
+    );
+    const result = await fetchPackageCatalogue(KEY);
+    expect(result).toEqual({
+      ok: true,
+      total: 1,
+      sdk: [{ name: '@hiyve/rtc-client', version: '2.5.0' }],
+      components: [],
+    });
+  });
+
+  it('reports a failed search without throwing', async () => {
+    fetchMock.mockResolvedValue(jsonResponse(500, {}));
+    const result = await fetchPackageCatalogue(KEY);
+    expect(result).toEqual({ ok: false, status: 500, error: 'Registry returned HTTP 500' });
+  });
+});