rentline-sandbox 0.1.2

package/dist/setup-JPLRGUPW.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+import {
+  DEFAULT_API_URL,
+  loadConfig,
+  saveConfig
+} from "./chunk-Q5AKRRZ2.js";
+import {
+  createClient
+} from "./chunk-X3OZHOPM.js";
+
+// src/setup.ts
+import { createInterface } from "readline";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync } from "fs";
+import { homedir, platform } from "os";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname(__filename);
+function parseSetupArgs(args) {
+  const opts = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--key" || a === "-k") opts.key = args[++i];
+    else if (a === "--url" || a === "-u") opts.url = args[++i];
+    else if (a === "--name") opts.name = args[++i];
+    else if (a === "--client" || a === "-c") opts.client = args[++i];
+    else if (a === "--scope") opts.scope = args[++i];
+    else if (a === "--yes" || a === "-y") opts.yes = true;
+  }
+  return opts;
+}
+async function runSetup(opts) {
+  console.log("\nRentline Sandbox \u2014 MCP Setup\n");
+  const rl = opts.yes ? null : createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q, fallback = "") => {
+    if (opts.yes || !rl) return Promise.resolve(fallback);
+    return new Promise((resolve) => {
+      rl.question(q, (ans) => resolve(ans.trim() || fallback));
+    });
+  };
+  let apiKey = opts.key;
+  if (!apiKey) {
+    const existing2 = loadConfig();
+    if (existing2?.api_key && opts.yes) {
+      apiKey = existing2.api_key;
+    } else {
+      apiKey = await ask(
+        `Enter your sandbox API key${existing2?.api_key ? " (press Enter to keep existing)" : ""}: `,
+        existing2?.api_key ?? ""
+      );
+    }
+  }
+  if (!apiKey) {
+    console.error("API key is required. Get one from your sandbox-api admin.");
+    process.exit(1);
+  }
+  const existing = loadConfig();
+  const apiUrl = opts.url ?? await ask(
+    `Sandbox API URL [${existing?.api_url ?? DEFAULT_API_URL}]: `,
+    existing?.api_url ?? DEFAULT_API_URL
+  );
+  const displayName = opts.name ?? await ask(
+    `Your default display name [${existing?.display_name ?? "Player"}]: `,
+    existing?.display_name ?? "Player"
+  );
+  process.stdout.write("Verifying connectivity\u2026 ");
+  try {
+    const c = createClient({ apiUrl, apiKey });
+    const h = await c.health();
+    console.log(`OK (${h.service})`);
+  } catch (e) {
+    console.log("FAILED");
+    console.error(`Cannot reach ${apiUrl}: ${e}`);
+    if (!opts.yes) {
+      const cont = await ask("Save config anyway? [y/N]: ", "n");
+      if (cont.toLowerCase() !== "y") {
+        rl?.close();
+        process.exit(1);
+      }
+    }
+  }
+  saveConfig({ api_key: apiKey, api_url: apiUrl, display_name: displayName, created_at: (/* @__PURE__ */ new Date()).toISOString() });
+  console.log("Credentials saved.\n");
+  let clientName = opts.client ?? detectClient();
+  if (!clientName) {
+    console.log("Which MCP client do you use?");
+    const clients = ["claude-code", "claude-desktop", "cursor", "windsurf", "opencode", "zed", "cline", "other"];
+    clients.forEach((c, i) => console.log(`  ${i + 1}. ${c}`));
+    const choice = await ask("Enter number or name: ", "other");
+    const idx = parseInt(choice);
+    clientName = isNaN(idx) ? choice : clients[idx - 1] ?? "other";
+  }
+  await installForClient(clientName, opts.scope ?? "user", apiKey, apiUrl, displayName);
+  rl?.close();
+  console.log("\nSetup complete. Restart your AI client to load the Rentline Sandbox MCP server.\n");
+}
+function detectClient() {
+  const env = process.env;
+  if (env.CLAUDE_CODE || env.ANTHROPIC_CLAUDE_CODE) return "claude-code";
+  if (env.CURSOR_TRACE_ID || env.CURSOR_SESSION_ID) return "cursor";
+  if (env.WINDSURF_SESSION) return "windsurf";
+  if (env.OPENCODE_PROJECT || env.OPENCODE_SESSION) return "opencode";
+  return void 0;
+}
+var MCP_SERVER_ENTRY = {
+  command: "npx",
+  args: ["-y", "rentline-sandbox"],
+  env: {}
+};
+function mcpEntry(apiKey, apiUrl) {
+  return {
+    ...MCP_SERVER_ENTRY,
+    env: {
+      SANDBOX_API_KEY: apiKey,
+      SANDBOX_API_URL: apiUrl
+    }
+  };
+}
+async function installForClient(clientName, scope, apiKey, apiUrl, displayName) {
+  const entry = mcpEntry(apiKey, apiUrl);
+  switch (clientName) {
+    case "claude-code": {
+      const { execSync } = await import("child_process");
+      const envFlags = Object.entries(entry.env ?? {}).map(([k, v]) => `-e ${k}=${v}`).join(" ");
+      const cmd = `claude mcp add rentline-sandbox --scope ${scope} ${envFlags} -- npx -y rentline-sandbox`;
+      try {
+        execSync(cmd, { stdio: "pipe" });
+        console.log(`Installed via claude CLI (scope=${scope})`);
+      } catch {
+        const file = join(homedir(), ".claude.json");
+        patchMcpJson(file, "rentline-sandbox", entry, "mcpServers");
+        console.log(`Patched ${file}`);
+      }
+      const skillSrc = join(__dirname, "../SKILL.md");
+      if (existsSync(skillSrc)) {
+        const targets = [
+          join(homedir(), ".claude", "skills", "rentline-sandbox"),
+          join(homedir(), ".agents", "skills", "rentline-sandbox")
+        ];
+        for (const dir of targets) {
+          mkdirSync(dir, { recursive: true });
+          copyFileSync(skillSrc, join(dir, "SKILL.md"));
+          console.log(`SKILL.md \u2192 ${dir}`);
+        }
+      }
+      break;
+    }
+    case "claude-desktop": {
+      const file = platform() === "win32" ? join(process.env.APPDATA ?? homedir(), "Claude", "claude_desktop_config.json") : join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+      patchMcpJson(file, "rentline-sandbox", entry, "mcpServers");
+      console.log(`Patched ${file}`);
+      break;
+    }
+    case "cursor": {
+      const file = scope === "project" ? join(process.cwd(), ".cursor", "mcp.json") : join(homedir(), ".cursor", "mcp.json");
+      patchMcpJson(file, "rentline-sandbox", entry, "mcpServers");
+      console.log(`Patched ${file}`);
+      break;
+    }
+    case "windsurf": {
+      const file = join(process.cwd(), ".windsurf", "mcp.json");
+      patchMcpJson(file, "rentline-sandbox", entry, "mcpServers");
+      console.log(`Patched ${file}`);
+      break;
+    }
+    case "opencode": {
+      const file = scope === "project" ? join(process.cwd(), "opencode.json") : join(homedir(), ".config", "opencode", "config.json");
+      patchMcpJson(file, "rentline-sandbox", entry, "mcp");
+      console.log(`Patched ${file}`);
+      const skillSrc = join(__dirname, "../SKILL.md");
+      if (existsSync(skillSrc)) {
+        const targets = [
+          join(homedir(), ".config", "opencode", "skills", "rentline-sandbox"),
+          join(homedir(), ".claude", "skills", "rentline-sandbox"),
+          join(homedir(), ".agents", "skills", "rentline-sandbox")
+        ];
+        for (const dir of targets) {
+          mkdirSync(dir, { recursive: true });
+          copyFileSync(skillSrc, join(dir, "SKILL.md"));
+          console.log(`SKILL.md \u2192 ${dir}`);
+        }
+      }
+      break;
+    }
+    case "zed":
+    case "cline":
+    case "warp":
+    case "other":
+    default: {
+      console.log(`
+Add the following to your MCP client config:
+`);
+      console.log(JSON.stringify({ "rentline-sandbox": entry }, null, 2));
+      break;
+    }
+  }
+}
+function patchMcpJson(filePath, serverName, entry, key) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  let config = {};
+  if (existsSync(filePath)) {
+    try {
+      config = JSON.parse(readFileSync(filePath, "utf-8"));
+    } catch {
+    }
+  }
+  const servers = config[key] ?? {};
+  servers[serverName] = entry;
+  config[key] = servers;
+  writeFileSync(filePath, JSON.stringify(config, null, 2));
+}
+export {
+  parseSetupArgs,
+  runSetup
+};

package/dist/trade-5BAZ6QFQ.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import {
+  getApiKey,
+  getApiUrl,
+  requireConfig
+} from "./chunk-Q5AKRRZ2.js";
+import {
+  createClient
+} from "./chunk-X3OZHOPM.js";
+
+// src/commands/trade.ts
+function client(cmd) {
+  const opts = cmd.optsWithGlobals();
+  const cfg = requireConfig();
+  return createClient({ apiUrl: getApiUrl(opts.url), apiKey: getApiKey(opts.apiKey) ?? cfg.api_key });
+}
+function registerTrade(program) {
+  const trade = program.command("trade").description("Buy and sell property tokens");
+  trade.command("buy <game-id>").description("Buy fractional property tokens (cash purchase, no mortgage)").requiredOption("--property <id>", "Property ID from the game pool").requiredOption("--tokens <n>", "Number of tokens to buy (fractions allowed)").action(async (gameId, opts, cmd) => {
+    const res = await client(cmd).trade(gameId, {
+      property_id: opts.property,
+      direction: "buy",
+      tokens: parseFloat(opts.tokens)
+    });
+    console.log(`BUY  ${res.tokens} tokens @ $${res.price_per_token_usd?.toFixed(2)}`);
+    console.log(`Cost: $${res.amount_usdc?.toFixed(2)}`);
+    console.log(`Transaction: ${res.transaction_id}`);
+  });
+  trade.command("sell <game-id>").description("Sell fractional property tokens back to the pool").requiredOption("--property <id>", "Property ID").requiredOption("--tokens <n>", "Number of tokens to sell").action(async (gameId, opts, cmd) => {
+    const res = await client(cmd).trade(gameId, {
+      property_id: opts.property,
+      direction: "sell",
+      tokens: parseFloat(opts.tokens)
+    });
+    console.log(`SELL ${res.tokens} tokens @ $${res.price_per_token_usd?.toFixed(2)}`);
+    console.log(`Proceeds: $${res.amount_usdc?.toFixed(2)}`);
+    console.log(`Transaction: ${res.transaction_id}`);
+  });
+  program.command("portfolio <game-id> <player-id>").description("Show holdings, P&L, NAV, and leverage for a player").action(async (gameId, playerId, cmd) => {
+    const p = await client(cmd).getPortfolio(gameId, playerId);
+    console.log(`
+Portfolio: ${p.display_name}`);
+    console.log(`${"\u2500".repeat(70)}`);
+    console.log(`Cash balance:    $${p.usdc_balance.toLocaleString("en-US", { maximumFractionDigits: 2 })}`);
+    console.log(`Total debt:     -$${p.total_debt.toLocaleString("en-US", { maximumFractionDigits: 2 })}`);
+    console.log(`Gross assets:    $${p.gross_asset_value.toLocaleString("en-US", { maximumFractionDigits: 2 })}`);
+    console.log(`NAV:             $${p.nav.toLocaleString("en-US", { maximumFractionDigits: 2 })}`);
+    console.log(`Leverage ratio:  ${(p.leverage_ratio * 100).toFixed(1)}%`);
+    if (p.holdings.length) {
+      console.log(`
+Holdings:`);
+      console.log(`${"Property".padEnd(30)}${"Tokens".padStart(10)}${"Value".padStart(14)}${"P&L".padStart(12)}${"Yield".padStart(10)}`);
+      console.log("\u2500".repeat(76));
+      for (const h of p.holdings) {
+        const pnlSign = h.unrealized_pnl_usd >= 0 ? "+" : "";
+        console.log(
+          `${(h.property_name ?? h.property_id).slice(0, 28).padEnd(30)}${h.tokens_held.toFixed(2).padStart(10)}$${h.current_value_usd.toFixed(2).padStart(13)}${pnlSign}$${h.unrealized_pnl_usd.toFixed(2).padStart(11)}$${h.total_rent_received_usd.toFixed(2).padStart(9)}`
+        );
+      }
+    } else {
+      console.log("\nNo holdings yet.");
+    }
+  });
+}
+export {
+  registerTrade
+};

package/llms.txt

@@ -0,0 +1,78 @@
+# Rentline Sandbox
+
+Turn-based real estate investment simulation. Players compete over tokenised properties using
+simulated tUSDC with mortgages, Fed rate cycles, macro events, property condition grades,
+PACE liens, and investor tiers.
+
+## MCP server
+
+Command: sandbox-mcp
+Transport: stdio JSON-RPC (Model Context Protocol)
+
+Required env vars:
+- SANDBOX_API_URL — API base URL (e.g. https://sandbox-api.rentline.xyz)
+- SANDBOX_API_KEY — sb_ user key or admin key
+
+## 35 tools
+
+### Game management
+- list_games — list open game rooms (lobby/trading)
+- get_game — full game state: players, properties, turn, Fed rate, settings
+- create_game — create a game with full mortgage/Fed/grade config + optional bots
+- create_game_from_preset — one-call presets: quick, standard, leveraged, distressed, long_run
+- join_game — join via invite code
+- mark_ready — toggle ready state; game advances when all humans ready
+- advance_turn — host: run all 7 engine phases
+- get_feed — turn event stream (Fed, macro, rent, price moves, debt service, turn summary)
+- add_bot — add LLM bot to lobby (strategies: aggressive, conservative, balanced, momentum, income, value_add)
+- remove_bot — remove bot from lobby
+- start_autonomous — enable auto-advance (advances on all-ready or turn deadline)
+- stop_autonomous — pause auto-advance
+- set_delegate — opt in to agent delegation when idle
+- spectate — public game snapshot (no auth required)
+
+### Market & Intel
+- list_properties — active property pool with grades
+- get_market_summary — live cap rates, price delta this turn, grade, vacancy, mechanics lien status
+- get_fed_history — FOMC decision log with bps moves and mortgage rate impact
+- get_player_actions — human-readable transaction timeline for a player
+
+### Trading
+- buy_tokens — all-cash token purchase at current market price
+- sell_tokens — sell tokens (proceeds pay mechanics lien → first lien → HELOC/PACE before cash credited)
+
+### Debt
+- originate_mortgage — leveraged buy (tier-adjusted LTV and rate applied automatically)
+- refi_mortgage — rate-and-term or cash-out refi
+- heloc_draw — draw from home equity line of credit
+- heloc_repay — repay HELOC balance
+- prepay_principal — partial/full principal prepayment (works for first_lien, heloc, pace, mechanics_lien)
+- improve_property — cash-funded grade upgrade (cost = steps × 8% × price, price bumps 5%/step)
+- originate_pace_lien — financed grade upgrade, no down payment (rate = base + 1.5%)
+- get_debt — all active mortgages: balances, LTV, arrears, type
+
+### Portfolio
+- get_portfolio — NAV, holdings with grade/yield/turns_held, investor tier, leverage ratio
+- get_leaderboard — game or global leaderboard ranked by NAV with tier names
+
+## Turn phases (in order)
+1. fed_meeting — hike/cut/hold; FED_WARNING fires 1 turn before; ARMs reprice immediately
+2. macro_events — rate macros take effect (1-turn warning system); active macros tick down
+3. rent_collect — proportional to tokens; grade multipliers applied; vacancy blocks
+4. random_events — vacancy, lease renewal, capex, appreciation/depreciation (all grade-adjusted)
+5. market_move — applies price drift; optional live AVM blend
+6. debt_service — collect monthly payments; forced sale after 1 grace turn
+7. distribute — credits rent to balances; emits TURN_SUMMARY event
+
+## Property grades
+A (excellent) → B (good) → C (average) → D (below avg) → F (distressed)
+Grade affects: rent multiplier, appreciation probability/range, capex risk, vacancy probability.
+Upgrade via improve_property (cash) or originate_pace_lien (financed).
+
+## Investor tiers (live from NAV, auto-applied to mortgage terms)
+Retail (<$100k) → Accredited ($100k) → Professional ($500k) → Institutional ($2.5M) → Developer ($25M)
+Higher tiers: +5% LTV and -25bps rate per tier step.
+
+## Docs
+https://sandbox.rentline.xyz
+https://sandbox-api.rentline.xyz/docs

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "rentline-sandbox",
+  "version": "0.1.2",
+  "description": "CLI and MCP server for the Rentline Sandbox real estate investment simulation game",
+  "type": "module",
+  "bin": {
+    "sandbox": "dist/index.js",
+    "sandbox-mcp": "dist/server.js"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./server": "./dist/server.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "SKILL.md",
+    "llms.txt",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.0",
+    "commander": "^13.0.0",
+    "dotenv": "^16.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Brandyn Hamilton",
+  "homepage": "https://sandbox.rentline.xyz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BrandynHamilton/rentline-sandbox.git",
+    "directory": "sandbox-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/BrandynHamilton/rentline-sandbox/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "rentline",
+    "sandbox",
+    "real-estate",
+    "simulation",
+    "mcp",
+    "cli",
+    "model-context-protocol",
+    "ai-agent",
+    "game"
+  ]
+}