openbroker 1.9.4 → 1.9.5

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to Open Broker will be documented in this file.
 
+## [Unreleased]
+
+### Added
+- Added an allowlisted `openbroker install <package>` command for optional companion packages, initially supporting `monitoring` (`openbroker-monitoring`) and `extended` (`openbroker-extended`). Re-running installs the latest release; `--tag`, `--dry`, and `--list` are supported.
+
 ## [1.9.3] - 2026-06-23
 
 ### Changed

package/README.md

@@ -8,6 +8,18 @@ Hyperliquid trading CLI. Execute orders, manage positions, and run trading strat
 npm install -g openbroker
 ```
 
+### Companion packages
+
+OpenBroker manages optional, allowlisted companion packages through the same CLI:
+
+```bash
+openbroker install --list        # Show supported packages
+openbroker install monitoring    # Local automation dashboard
+openbroker install extended      # Extended Exchange CLI
+```
+
+The command installs globally through npm so each package's executable is available on your `PATH`. Re-run the same command to upgrade to the latest release, or pin a release with `--tag <version>`. Use `--dry` to preview the npm command.
+
 ### Codex: one-command install
 
 Install the Codex skill, persistent CLI, and restricted API-wallet onboarding flow:
@@ -38,6 +50,9 @@ openbroker search --query GOLD              # Find markets
 
 ```bash
 npx openbroker@latest install --codex  # Codex skill + CLI + API-wallet onboarding
+openbroker install --list       # List optional companion packages
+openbroker install monitoring   # Install or upgrade openbroker-monitoring
+openbroker install extended     # Install or upgrade openbroker-extended
 openbroker setup --api-wallet   # Recommended: restricted agent wallet + browser approval
 openbroker setup                # Interactive; API wallet is the default
 ```

package/SKILL.md

@@ -301,7 +301,7 @@ Use `--no-ws` only for debugging or networks that cannot maintain WebSockets. In
 `openbroker-monitoring` is optional but useful for long-running automations, live debugging, and post-run inspection.
 
 ```bash
-npm install openbroker-monitoring
+openbroker install monitoring
 openbroker auto run ./my-automation.ts --id my-auto
 openbroker-monitoring serve --host 127.0.0.1 --port 3001
 ```

package/bin/cli.ts

@@ -11,7 +11,7 @@ const scriptsDir = path.resolve(__dirname, '../scripts');
 
 const commands: Record<string, { script: string; description: string }> = {
   // Setup
-  'install': { script: 'setup/install.ts', description: 'Install OpenBroker for an agent harness' },
+  'install': { script: 'setup/install.ts', description: 'Install companion packages or an agent harness' },
   'setup': { script: 'setup/onboard.ts', description: 'Interactive setup wizard' },
   'onboard': { script: 'setup/onboard.ts', description: 'Interactive setup wizard' },
   'approve-builder': { script: 'setup/approve-builder.ts', description: 'Approve builder fee' },
@@ -69,7 +69,7 @@ Open Broker - Hyperliquid Trading CLI
 Usage: openbroker <command> [options]
 
 Setup:
-  install              Install OpenBroker for Codex or another agent harness
+  install              Install companion packages or OpenBroker for an agent harness
   setup                One-command setup (wallet + config + builder approval)
 
 Info Commands:
@@ -139,6 +139,8 @@ Utility:
 
 Examples:
   npx openbroker@latest install --codex        # Install skill + CLI + API-wallet setup
+  openbroker install monitoring                 # Install or upgrade the automation dashboard
+  openbroker install extended                   # Install or upgrade the Extended Exchange CLI
   openbroker setup --api-wallet                 # Recommended restricted API-wallet setup
   openbroker account                            # View account info
   openbroker buy --coin ETH --size 0.1          # Market buy 0.1 ETH

package/dist/setup/install.js

@@ -5,19 +5,54 @@ import * as path from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
+import { INSTALLABLE_PACKAGES, packageSpec, resolveInstallablePackage, } from './package-catalog.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const packageRoot = path.resolve(__dirname, '../..');
-const args = new Set(process.argv.slice(2));
+const rawArgs = process.argv.slice(2);
+const args = new Set(rawArgs);
+function positionalArgs() {
+    const positionals = [];
+    for (let index = 0; index < rawArgs.length; index++) {
+        const arg = rawArgs[index];
+        if (arg === '--tag') {
+            index++;
+            continue;
+        }
+        if (!arg.startsWith('-'))
+            positionals.push(arg);
+    }
+    return positionals;
+}
+function optionValue(flag) {
+    const index = rawArgs.indexOf(flag);
+    if (index < 0)
+        return null;
+    const value = rawArgs[index + 1];
+    if (!value || value.startsWith('-'))
+        fail(`${flag} requires a value`);
+    return value;
+}
 function printUsage() {
     console.log(`
-OpenBroker Harness Installer
-============================
+OpenBroker Installer
+====================
 
 Usage:
+  openbroker install <package> [--tag <version>] [--dry]
+  openbroker install --list
   openbroker install --codex [options]
   npx openbroker@latest install --codex [options]
 
+Companion packages:
+  monitoring    Install the local automation dashboard
+  extended      Install the Extended Exchange CLI
+
+Package options:
+  --tag <tag>   Install a release tag or exact version (default: latest)
+  --dry         Print the npm command without installing
+  --list        List supported companion packages
+
 Harnesses:
   --codex       Install the OpenBroker skill for Codex
 
@@ -74,6 +109,55 @@ function installGlobalCli() {
         fail('global CLI installation failed. Fix the npm permission error, then rerun with --skip-cli.');
     }
 }
+function printInstallablePackages() {
+    console.log('Installable OpenBroker packages:\n');
+    for (const entry of INSTALLABLE_PACKAGES) {
+        console.log(`  ${entry.key.padEnd(12)} ${entry.packageName.padEnd(26)} ${entry.description}`);
+    }
+    console.log('\nInstall or upgrade with: openbroker install <package>');
+}
+function installCompanionPackage(target) {
+    const entry = resolveInstallablePackage(target);
+    if (!entry) {
+        printInstallablePackages();
+        fail(`unknown installable package: ${target}`);
+    }
+    const allowedFlags = new Set(['--tag', '--dry']);
+    const unsupported = rawArgs.filter((arg, index) => (arg.startsWith('-')
+        && !allowedFlags.has(arg)
+        && rawArgs[index - 1] !== '--tag'));
+    if (unsupported.length > 0)
+        fail(`unsupported package option: ${unsupported[0]}`);
+    const tag = optionValue('--tag') ?? 'latest';
+    let spec;
+    try {
+        spec = packageSpec(entry, tag);
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+    }
+    const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const npmArgs = ['install', '--global', spec];
+    console.log(`OpenBroker — Install ${entry.key}`);
+    console.log('================================\n');
+    console.log(`Package: ${spec}`);
+    console.log(`Command: ${npmCommand} ${npmArgs.join(' ')}`);
+    if (args.has('--dry')) {
+        console.log('\nDry run only; nothing was installed.');
+        return;
+    }
+    const result = spawnSync(npmCommand, npmArgs, { stdio: 'inherit' });
+    if (result.error)
+        fail(`could not start npm: ${result.error.message}`);
+    if (result.status !== 0) {
+        fail(`installation failed for ${entry.packageName}; resolve the npm error and retry`);
+    }
+    console.log(`\n✅ ${entry.packageName} installed successfully.`);
+    console.log(`Available command: ${entry.command}`);
+    console.log('\nNext steps:');
+    for (const step of entry.nextSteps)
+        console.log(`  ${step}`);
+}
 function runApiWalletSetup() {
     const onboardPath = path.join(packageRoot, 'scripts', 'setup', 'onboard.ts');
     console.log('\nStarting restricted API-wallet onboarding...\n');
@@ -94,6 +178,19 @@ function main() {
         printUsage();
         return;
     }
+    if (args.has('--list')) {
+        printInstallablePackages();
+        return;
+    }
+    const positionals = positionalArgs();
+    if (positionals.length > 0) {
+        if (positionals.length > 1)
+            fail(`expected one package name, received: ${positionals.join(' ')}`);
+        if (args.has('--codex'))
+            fail('choose either a companion package or the --codex harness installer');
+        installCompanionPackage(positionals[0]);
+        return;
+    }
     if (!args.has('--codex')) {
         printUsage();
         fail('choose a supported harness flag such as --codex');

package/dist/setup/package-catalog.d.ts

@@ -0,0 +1,12 @@
+export interface InstallablePackage {
+    key: string;
+    aliases: string[];
+    packageName: string;
+    command: string;
+    description: string;
+    nextSteps: string[];
+}
+export declare const INSTALLABLE_PACKAGES: InstallablePackage[];
+export declare function resolveInstallablePackage(input: string): InstallablePackage | null;
+export declare function packageSpec(entry: InstallablePackage, tag?: string): string;
+//# sourceMappingURL=package-catalog.d.ts.map

package/dist/setup/package-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-catalog.d.ts","sourceRoot":"","sources":["../../scripts/setup/package-catalog.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,eAAO,MAAM,oBAAoB,EAAE,kBAAkB,EAuBpD,CAAC;AAEF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAOlF;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,kBAAkB,EAAE,GAAG,SAAW,GAAG,MAAM,CAK7E"}

package/dist/setup/package-catalog.js

@@ -0,0 +1,36 @@
+export const INSTALLABLE_PACKAGES = [
+    {
+        key: 'monitoring',
+        aliases: ['openbroker-monitoring'],
+        packageName: 'openbroker-monitoring',
+        command: 'openbroker-monitoring',
+        description: 'Local automation dashboard and optional audit observer',
+        nextSteps: [
+            'openbroker-monitoring serve --host 127.0.0.1 --port 3001',
+            'Open http://127.0.0.1:3001',
+        ],
+    },
+    {
+        key: 'extended',
+        aliases: ['openbroker-extended'],
+        packageName: 'openbroker-extended',
+        command: 'openbroker-ex',
+        description: 'Extended Exchange trading CLI and library',
+        nextSteps: [
+            'openbroker-ex --help',
+            'openbroker-ex setup',
+        ],
+    },
+];
+export function resolveInstallablePackage(input) {
+    const normalized = input.trim().toLowerCase();
+    return INSTALLABLE_PACKAGES.find((entry) => (entry.key === normalized
+        || entry.packageName === normalized
+        || entry.aliases.includes(normalized))) ?? null;
+}
+export function packageSpec(entry, tag = 'latest') {
+    if (!/^[a-z0-9][a-z0-9._-]*$/i.test(tag)) {
+        throw new Error(`invalid package tag or version: ${tag}`);
+    }
+    return `${entry.packageName}@${tag}`;
+}

package/dist/setup/package-catalog.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=package-catalog.test.d.ts.map

package/dist/setup/package-catalog.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-catalog.test.d.ts","sourceRoot":"","sources":["../../scripts/setup/package-catalog.test.ts"],"names":[],"mappings":""}

package/dist/setup/package-catalog.test.js

@@ -0,0 +1,31 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { INSTALLABLE_PACKAGES, packageSpec, resolveInstallablePackage, } from './package-catalog.js';
+const installScript = fileURLToPath(new URL('./install.ts', import.meta.url));
+test('resolves companion packages by short name and npm package name', () => {
+    assert.equal(resolveInstallablePackage('monitoring')?.packageName, 'openbroker-monitoring');
+    assert.equal(resolveInstallablePackage('openbroker-monitoring')?.key, 'monitoring');
+    assert.equal(resolveInstallablePackage('EXTENDED')?.command, 'openbroker-ex');
+    assert.equal(resolveInstallablePackage('unknown'), null);
+});
+test('builds pinned or latest npm package specs without accepting arbitrary specs', () => {
+    const monitoring = INSTALLABLE_PACKAGES.find((entry) => entry.key === 'monitoring');
+    assert.ok(monitoring);
+    assert.equal(packageSpec(monitoring), 'openbroker-monitoring@latest');
+    assert.equal(packageSpec(monitoring, '1.4.2'), 'openbroker-monitoring@1.4.2');
+    assert.throws(() => packageSpec(monitoring, 'npm:unrelated-package'));
+    assert.throws(() => packageSpec(monitoring, '../local-package'));
+});
+test('installer dry run prints the global npm operation without writing', () => {
+    const result = spawnSync(process.execPath, ['--import', 'tsx', installScript, 'monitoring', '--tag', '1.4.2', '--dry'], { encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout, /npm install --global openbroker-monitoring@1\.4\.2/);
+    assert.match(result.stdout, /nothing was installed/i);
+});
+test('installer rejects packages outside the catalog', () => {
+    const result = spawnSync(process.execPath, ['--import', 'tsx', installScript, 'unrelated-package', '--dry'], { encoding: 'utf8' });
+    assert.equal(result.status, 1);
+    assert.match(result.stderr, /unknown installable package/i);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openbroker",
-  "version": "1.9.4",
+  "version": "1.9.5",
   "description": "Hyperliquid trading CLI - execute orders, manage positions, and run trading strategies",
   "type": "module",
   "bin": {
@@ -51,10 +51,11 @@
     "funding-scan": "tsx scripts/info/funding-scan.ts",
     "outcomes": "tsx scripts/info/outcomes.ts",
     "build": "tsc",
-    "prepublishOnly": "npm run build && npm run test:guardrails && npm run test:realtime && npm run test:cli",
+    "prepublishOnly": "npm run build && npm run test:guardrails && npm run test:realtime && npm run test:install && npm run test:cli",
     "test:cli": "node --import tsx bin/cli.ts --help",
     "test:guardrails": "node --import tsx --test scripts/auto/guardrails.test.ts",
-    "test:realtime": "node --import tsx --test scripts/auto/realtime.test.ts"
+    "test:realtime": "node --import tsx --test scripts/auto/realtime.test.ts",
+    "test:install": "node --import tsx --test scripts/setup/package-catalog.test.ts"
   },
   "dependencies": {
     "@nktkas/hyperliquid": "^0.30.3",

package/scripts/setup/install.ts

@@ -6,21 +6,59 @@ import * as path from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
+import {
+  INSTALLABLE_PACKAGES,
+  packageSpec,
+  resolveInstallablePackage,
+} from './package-catalog.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const packageRoot = path.resolve(__dirname, '../..');
-const args = new Set(process.argv.slice(2));
+const rawArgs = process.argv.slice(2);
+const args = new Set(rawArgs);
+
+function positionalArgs(): string[] {
+  const positionals: string[] = [];
+  for (let index = 0; index < rawArgs.length; index++) {
+    const arg = rawArgs[index];
+    if (arg === '--tag') {
+      index++;
+      continue;
+    }
+    if (!arg.startsWith('-')) positionals.push(arg);
+  }
+  return positionals;
+}
+
+function optionValue(flag: string): string | null {
+  const index = rawArgs.indexOf(flag);
+  if (index < 0) return null;
+  const value = rawArgs[index + 1];
+  if (!value || value.startsWith('-')) fail(`${flag} requires a value`);
+  return value;
+}
 
 function printUsage(): void {
   console.log(`
-OpenBroker Harness Installer
-============================
+OpenBroker Installer
+====================
 
 Usage:
+  openbroker install <package> [--tag <version>] [--dry]
+  openbroker install --list
   openbroker install --codex [options]
   npx openbroker@latest install --codex [options]
 
+Companion packages:
+  monitoring    Install the local automation dashboard
+  extended      Install the Extended Exchange CLI
+
+Package options:
+  --tag <tag>   Install a release tag or exact version (default: latest)
+  --dry         Print the npm command without installing
+  --list        List supported companion packages
+
 Harnesses:
   --codex       Install the OpenBroker skill for Codex
 
@@ -93,6 +131,62 @@ function installGlobalCli(): void {
   }
 }
 
+function printInstallablePackages(): void {
+  console.log('Installable OpenBroker packages:\n');
+  for (const entry of INSTALLABLE_PACKAGES) {
+    console.log(`  ${entry.key.padEnd(12)} ${entry.packageName.padEnd(26)} ${entry.description}`);
+  }
+  console.log('\nInstall or upgrade with: openbroker install <package>');
+}
+
+function installCompanionPackage(target: string): void {
+  const entry = resolveInstallablePackage(target);
+  if (!entry) {
+    printInstallablePackages();
+    fail(`unknown installable package: ${target}`);
+  }
+
+  const allowedFlags = new Set(['--tag', '--dry']);
+  const unsupported = rawArgs.filter((arg, index) => (
+    arg.startsWith('-')
+    && !allowedFlags.has(arg)
+    && rawArgs[index - 1] !== '--tag'
+  ));
+  if (unsupported.length > 0) fail(`unsupported package option: ${unsupported[0]}`);
+
+  const tag = optionValue('--tag') ?? 'latest';
+  let spec: string;
+  try {
+    spec = packageSpec(entry, tag);
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+
+  const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const npmArgs = ['install', '--global', spec];
+
+  console.log(`OpenBroker — Install ${entry.key}`);
+  console.log('================================\n');
+  console.log(`Package: ${spec}`);
+  console.log(`Command: ${npmCommand} ${npmArgs.join(' ')}`);
+
+  if (args.has('--dry')) {
+    console.log('\nDry run only; nothing was installed.');
+    return;
+  }
+
+  const result = spawnSync(npmCommand, npmArgs, { stdio: 'inherit' });
+  if (result.error) fail(`could not start npm: ${result.error.message}`);
+  if (result.status !== 0) {
+    fail(`installation failed for ${entry.packageName}; resolve the npm error and retry`);
+  }
+
+  console.log(`\n✅ ${entry.packageName} installed successfully.`);
+  console.log(`Available command: ${entry.command}`);
+  console.log('\nNext steps:');
+  for (const step of entry.nextSteps) console.log(`  ${step}`);
+}
+
 function runApiWalletSetup(): void {
   const onboardPath = path.join(packageRoot, 'scripts', 'setup', 'onboard.ts');
 
@@ -121,6 +215,19 @@ function main(): void {
     return;
   }
 
+  if (args.has('--list')) {
+    printInstallablePackages();
+    return;
+  }
+
+  const positionals = positionalArgs();
+  if (positionals.length > 0) {
+    if (positionals.length > 1) fail(`expected one package name, received: ${positionals.join(' ')}`);
+    if (args.has('--codex')) fail('choose either a companion package or the --codex harness installer');
+    installCompanionPackage(positionals[0]);
+    return;
+  }
+
   if (!args.has('--codex')) {
     printUsage();
     fail('choose a supported harness flag such as --codex');

package/scripts/setup/package-catalog.test.ts

@@ -0,0 +1,50 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import {
+  INSTALLABLE_PACKAGES,
+  packageSpec,
+  resolveInstallablePackage,
+} from './package-catalog.js';
+
+const installScript = fileURLToPath(new URL('./install.ts', import.meta.url));
+
+test('resolves companion packages by short name and npm package name', () => {
+  assert.equal(resolveInstallablePackage('monitoring')?.packageName, 'openbroker-monitoring');
+  assert.equal(resolveInstallablePackage('openbroker-monitoring')?.key, 'monitoring');
+  assert.equal(resolveInstallablePackage('EXTENDED')?.command, 'openbroker-ex');
+  assert.equal(resolveInstallablePackage('unknown'), null);
+});
+
+test('builds pinned or latest npm package specs without accepting arbitrary specs', () => {
+  const monitoring = INSTALLABLE_PACKAGES.find((entry) => entry.key === 'monitoring');
+  assert.ok(monitoring);
+  assert.equal(packageSpec(monitoring), 'openbroker-monitoring@latest');
+  assert.equal(packageSpec(monitoring, '1.4.2'), 'openbroker-monitoring@1.4.2');
+  assert.throws(() => packageSpec(monitoring, 'npm:unrelated-package'));
+  assert.throws(() => packageSpec(monitoring, '../local-package'));
+});
+
+test('installer dry run prints the global npm operation without writing', () => {
+  const result = spawnSync(
+    process.execPath,
+    ['--import', 'tsx', installScript, 'monitoring', '--tag', '1.4.2', '--dry'],
+    { encoding: 'utf8' },
+  );
+
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /npm install --global openbroker-monitoring@1\.4\.2/);
+  assert.match(result.stdout, /nothing was installed/i);
+});
+
+test('installer rejects packages outside the catalog', () => {
+  const result = spawnSync(
+    process.execPath,
+    ['--import', 'tsx', installScript, 'unrelated-package', '--dry'],
+    { encoding: 'utf8' },
+  );
+
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /unknown installable package/i);
+});

package/scripts/setup/package-catalog.ts

@@ -0,0 +1,49 @@
+export interface InstallablePackage {
+  key: string;
+  aliases: string[];
+  packageName: string;
+  command: string;
+  description: string;
+  nextSteps: string[];
+}
+
+export const INSTALLABLE_PACKAGES: InstallablePackage[] = [
+  {
+    key: 'monitoring',
+    aliases: ['openbroker-monitoring'],
+    packageName: 'openbroker-monitoring',
+    command: 'openbroker-monitoring',
+    description: 'Local automation dashboard and optional audit observer',
+    nextSteps: [
+      'openbroker-monitoring serve --host 127.0.0.1 --port 3001',
+      'Open http://127.0.0.1:3001',
+    ],
+  },
+  {
+    key: 'extended',
+    aliases: ['openbroker-extended'],
+    packageName: 'openbroker-extended',
+    command: 'openbroker-ex',
+    description: 'Extended Exchange trading CLI and library',
+    nextSteps: [
+      'openbroker-ex --help',
+      'openbroker-ex setup',
+    ],
+  },
+];
+
+export function resolveInstallablePackage(input: string): InstallablePackage | null {
+  const normalized = input.trim().toLowerCase();
+  return INSTALLABLE_PACKAGES.find((entry) => (
+    entry.key === normalized
+    || entry.packageName === normalized
+    || entry.aliases.includes(normalized)
+  )) ?? null;
+}
+
+export function packageSpec(entry: InstallablePackage, tag = 'latest'): string {
+  if (!/^[a-z0-9][a-z0-9._-]*$/i.test(tag)) {
+    throw new Error(`invalid package tag or version: ${tag}`);
+  }
+  return `${entry.packageName}@${tag}`;
+}