openbroker 1.9.4 → 1.9.6

package/scripts/operations/scale.ts

@@ -1,8 +1,10 @@
 #!/usr/bin/env npx tsx
 // Scale In/Out - Place a grid of limit orders
 
+import { fileURLToPath } from 'url';
 import { getClient } from '../core/client.js';
-import { formatUsd, parseArgs, sleep } from '../core/utils.js';
+import type { CancelResponse, OrderResponse } from '../core/types.js';
+import { formatUsd, parseArgs } from '../core/utils.js';
 
 function printUsage() {
   console.log(`
@@ -42,14 +44,49 @@ Examples:
 `);
 }
 
-interface OrderLevel {
+export interface OrderLevel {
   level: number;
   price: number;
   size: number;
   distanceFromMid: number;
 }
 
-function calculateLevels(
+export interface ScaleClient {
+  verbose: boolean;
+  getAllMids(): Promise<Record<string, string>>;
+  bulkOrder(
+    orders: Array<{ coin: string; isBuy: boolean; size: number; price: number; tif?: 'Gtc' | 'Alo'; reduceOnly?: boolean; leverage?: number }>
+  ): Promise<OrderResponse>;
+  bulkCancel(cancels: Array<{ coin: string; oid: number }>): Promise<CancelResponse>;
+}
+
+export interface ScaleOptions {
+  coin: string;
+  side: 'buy' | 'sell';
+  size: number;
+  levels: number;
+  rangePct: number;
+  distribution?: 'linear' | 'exponential' | 'flat';
+  leverage?: number;
+  reduceOnly?: boolean;
+  tif?: 'Gtc' | 'Alo';
+  dryRun?: boolean;
+  verbose?: boolean;
+  rollbackOnPartial?: boolean;
+  client?: ScaleClient;
+  output?: (line: string) => void;
+}
+
+export interface ScaleResult {
+  status: 'dry' | 'complete' | 'partial' | 'failed';
+  levels: OrderLevel[];
+  restingOids: number[];
+  filledOids: number[];
+  errors: string[];
+  rolledBack: boolean;
+}
+
+export function calculateLevels(
   midPrice: number,
   isBuy: boolean,
   totalSize: number,
@@ -100,6 +137,133 @@ function calculateLevels(
   return levels;
 }
 
+export async function runScale(opts: ScaleOptions): Promise<ScaleResult> {
+  const out = opts.output ?? ((line: string) => console.log(line));
+  const distribution = opts.distribution ?? 'linear';
+  const reduceOnly = opts.reduceOnly ?? false;
+  const tif = opts.tif ?? 'Gtc';
+  const rollbackOnPartial = opts.rollbackOnPartial ?? true;
+  const isBuy = opts.side === 'buy';
+
+  if (!opts.coin) throw new Error('coin is required');
+  if (opts.side !== 'buy' && opts.side !== 'sell') throw new Error('side must be buy or sell');
+  if (!Number.isFinite(opts.size) || opts.size <= 0) throw new Error('size must be positive');
+  if (!Number.isInteger(opts.levels) || opts.levels <= 0) throw new Error('levels must be a positive integer');
+  if (!Number.isFinite(opts.rangePct) || opts.rangePct <= 0) throw new Error('rangePct must be positive');
+  if (!['linear', 'exponential', 'flat'].includes(distribution)) throw new Error('distribution must be linear, exponential, or flat');
+
+  const client = opts.client ?? getClient();
+  if (opts.verbose) client.verbose = true;
+
+  out('Open Broker - Scale In/Out');
+  out('==========================\n');
+
+  const mids = await client.getAllMids();
+  const midPrice = parseFloat(mids[opts.coin]);
+  if (!midPrice) throw new Error(`No market data for ${opts.coin}`);
+
+  const levels = calculateLevels(midPrice, isBuy, opts.size, opts.levels, opts.rangePct, distribution);
+  const notional = levels.reduce((sum, l) => sum + l.price * l.size, 0);
+  const avgPrice = notional / opts.size;
+
+  out('Order Plan');
+  out('----------');
+  out(`Coin:           ${opts.coin}`);
+  out(`Side:           ${isBuy ? 'BUY' : 'SELL'}`);
+  out(`Total Size:     ${opts.size}`);
+  out(`Current Mid:    ${formatUsd(midPrice)}`);
+  out(`Levels:         ${opts.levels}`);
+  out(`Range:          ${opts.rangePct}% ${isBuy ? 'below' : 'above'} mid`);
+  out(`Distribution:   ${distribution}`);
+  out(`Time in Force:  ${tif}`);
+  out(`Reduce Only:    ${reduceOnly ? 'Yes' : 'No'}`);
+  out(`Est. Notional:  ${formatUsd(notional)}`);
+  out(`Avg Price:      ${formatUsd(avgPrice)}`);
+
+  out('\nOrder Grid');
+  out('----------');
+  out('Level | Price        | Size       | Distance');
+  out('------|--------------|------------|----------');
+
+  for (const level of levels) {
+    out(
+      `  ${level.level.toString().padStart(2)}  | ` +
+      `${formatUsd(level.price).padStart(12)} | ` +
+      `${level.size.toFixed(6).padStart(10)} | ` +
+      `${level.distanceFromMid.toFixed(2)}%`
+    );
+  }
+
+  if (opts.dryRun) {
+    out('\n🔍 Dry run - orders not placed');
+    return { status: 'dry', levels, restingOids: [], filledOids: [], errors: [], rolledBack: false };
+  }
+
+  out('\nPlacing ladder as a bulk order...\n');
+
+  const response = await client.bulkOrder(
+    levels.map((level) => ({
+      coin: opts.coin,
+      isBuy,
+      size: level.size,
+      price: level.price,
+      tif,
+      reduceOnly,
+      leverage: opts.leverage,
+    }))
+  );
+
+  const restingOids: number[] = [];
+  const filledOids: number[] = [];
+  const errors: string[] = [];
+
+  if (response.status === 'ok' && response.response && typeof response.response === 'object') {
+    response.response.data.statuses.forEach((status, index) => {
+      const level = levels[index];
+      if (status?.resting) {
+        restingOids.push(status.resting.oid);
+        out(`Level ${level.level}: ✅ OID ${status.resting.oid}`);
+      } else if (status?.filled) {
+        filledOids.push(status.filled.oid);
+        out(`Level ${level.level}: ✅ Filled ${status.filled.totalSz} @ ${formatUsd(parseFloat(status.filled.avgPx))}`);
+      } else if (status?.error) {
+        errors.push(`Level ${level.level}: ${status.error}`);
+        out(`Level ${level.level}: ❌ ${status.error}`);
+      } else {
+        errors.push(`Level ${level.level}: Unknown status`);
+        out(`Level ${level.level}: ⚠️ Unknown status`);
+      }
+    });
+  } else {
+    const reason = typeof response.response === 'string' ? response.response : 'Bulk order failed';
+    errors.push(reason);
+    out(`❌ ${reason}`);
+  }
+
+  let rolledBack = false;
+  if (errors.length > 0 && rollbackOnPartial && restingOids.length > 0) {
+    out('\nPartial ladder placement detected; cancelling resting ladder orders...');
+    await client.bulkCancel(restingOids.map((oid) => ({ coin: opts.coin, oid })));
+    rolledBack = true;
+    out(`Cancelled ${restingOids.length} resting order(s).`);
+  }
+
+  out('\n========== Summary ==========');
+  out(`Orders Placed:  ${restingOids.length + filledOids.length}/${opts.levels}`);
+  if (errors.length > 0) out(`Failed:         ${errors.length}`);
+  if (restingOids.length > 0) out(`Resting OIDs:   ${restingOids.join(', ')}`);
+  if (filledOids.length > 0) out(`Filled OIDs:    ${filledOids.join(', ')}`);
+  if (rolledBack) out('Rollback:       Resting orders cancelled');
+
+  const status = errors.length === 0
+    ? 'complete'
+    : restingOids.length + filledOids.length > 0
+      ? 'partial'
+      : 'failed';
+
+  return { status, levels, restingOids, filledOids, errors, rolledBack };
+}
+
 async function main() {
   const args = parseArgs(process.argv.slice(2));
 
@@ -119,17 +283,6 @@ async function main() {
     process.exit(1);
   }
 
-  if (side !== 'buy' && side !== 'sell') {
-    console.error('Error: --side must be "buy" or "sell"');
-    process.exit(1);
-  }
-
-  if (!['linear', 'exponential', 'flat'].includes(distribution)) {
-    console.error('Error: --distribution must be linear, exponential, or flat');
-    process.exit(1);
-  }
-
-  // Map uppercase CLI input to Pascal case for SDK
   const tifMap: Record<string, 'Gtc' | 'Alo'> = {
     'GTC': 'Gtc',
     'ALO': 'Alo'
@@ -141,126 +294,28 @@ async function main() {
     process.exit(1);
   }
 
-  const isBuy = side === 'buy';
-  const client = getClient();
-
-  if (args.verbose) {
-    client.verbose = true;
-  }
-
-  console.log('Open Broker - Scale In/Out');
-  console.log('==========================\n');
-
   try {
-    const mids = await client.getAllMids();
-    const midPrice = parseFloat(mids[coin]);
-    if (!midPrice) {
-      console.error(`Error: No market data for ${coin}`);
-      process.exit(1);
-    }
-
-    const levels = calculateLevels(midPrice, isBuy, totalSize, numLevels, rangePct, distribution);
-    const notional = levels.reduce((sum, l) => sum + l.price * l.size, 0);
-    const avgPrice = notional / totalSize;
-
-    console.log('Order Plan');
-    console.log('----------');
-    console.log(`Coin:           ${coin}`);
-    console.log(`Side:           ${isBuy ? 'BUY' : 'SELL'}`);
-    console.log(`Total Size:     ${totalSize}`);
-    console.log(`Current Mid:    ${formatUsd(midPrice)}`);
-    console.log(`Levels:         ${numLevels}`);
-    console.log(`Range:          ${rangePct}% ${isBuy ? 'below' : 'above'} mid`);
-    console.log(`Distribution:   ${distribution}`);
-    console.log(`Time in Force:  ${tif}`);
-    console.log(`Reduce Only:    ${reduceOnly ? 'Yes' : 'No'}`);
-    console.log(`Est. Notional:  ${formatUsd(notional)}`);
-    console.log(`Avg Price:      ${formatUsd(avgPrice)}`);
-
-    console.log('\nOrder Grid');
-    console.log('----------');
-    console.log('Level | Price        | Size       | Distance');
-    console.log('------|--------------|------------|----------');
-
-    for (const level of levels) {
-      console.log(
-        `  ${level.level.toString().padStart(2)}  | ` +
-        `${formatUsd(level.price).padStart(12)} | ` +
-        `${level.size.toFixed(6).padStart(10)} | ` +
-        `${level.distanceFromMid.toFixed(2)}%`
-      );
-    }
-
-    if (dryRun) {
-      console.log('\n🔍 Dry run - orders not placed');
-      return;
-    }
-
-    console.log('\nPlacing orders...\n');
-
-    const results: { level: number; oid?: number; error?: string }[] = [];
-
-    for (const level of levels) {
-      process.stdout.write(`Level ${level.level}: ${formatUsd(level.price)} x ${level.size.toFixed(6)}... `);
-
-      try {
-        const response = await client.limitOrder(
-          coin,
-          isBuy,
-          level.size,
-          level.price,
-          tif,
-          reduceOnly,
-          leverage
-        );
-
-        if (response.status === 'ok' && response.response && typeof response.response === 'object') {
-          const status = response.response.data.statuses[0];
-          if (status?.resting) {
-            console.log(`✅ OID: ${status.resting.oid}`);
-            results.push({ level: level.level, oid: status.resting.oid });
-          } else if (status?.filled) {
-            console.log(`✅ Filled immediately @ ${formatUsd(parseFloat(status.filled.avgPx))}`);
-            results.push({ level: level.level, oid: status.filled.oid });
-          } else if (status?.error) {
-            console.log(`❌ ${status.error}`);
-            results.push({ level: level.level, error: status.error });
-          } else {
-            console.log(`⚠️ Unknown status`);
-            results.push({ level: level.level, error: 'Unknown status' });
-          }
-        } else {
-          const error = typeof response.response === 'string' ? response.response : 'Failed';
-          console.log(`❌ ${error}`);
-          results.push({ level: level.level, error });
-        }
-      } catch (err) {
-        const error = err instanceof Error ? err.message : String(err);
-        console.log(`❌ ${error}`);
-        results.push({ level: level.level, error });
-      }
-
-      // Small delay between orders
-      await sleep(100);
-    }
-
-    // Summary
-    const successful = results.filter(r => r.oid).length;
-    const failed = results.filter(r => r.error).length;
-
-    console.log('\n========== Summary ==========');
-    console.log(`Orders Placed:  ${successful}/${numLevels}`);
-    if (failed > 0) {
-      console.log(`Failed:         ${failed}`);
-    }
-    if (successful > 0) {
-      console.log(`Order IDs:      ${results.filter(r => r.oid).map(r => r.oid).join(', ')}`);
-    }
-
+    const result = await runScale({
+      coin,
+      side: side as 'buy' | 'sell',
+      size: totalSize,
+      levels: numLevels,
+      rangePct,
+      distribution,
+      leverage,
+      reduceOnly,
+      tif,
+      dryRun,
+      verbose: args.verbose as boolean,
+    });
+    if (result.status === 'failed') process.exit(1);
   } catch (error) {
-    console.error('Error:', error);
+    console.error('Error:', error instanceof Error ? error.message : error);
     process.exit(1);
   }
 }
 
-main();
+// Only run when invoked as a script — not when imported as a module.
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main();
+}

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}`;
+}