star-sdk-cli 0.1.10 → 0.1.12

package/dist/cli.mjs

@@ -23,6 +23,23 @@ import Star from 'star-sdk';
 
 **CRITICAL:** Always use \`import Star from 'star-sdk'\` - not destructured imports.
 
+## Setup (Required for Leaderboards)
+
+Before writing any leaderboard code, register your game by running this command in the terminal:
+
+\`\`\`bash
+npx star-sdk init "Your Game Name"
+\`\`\`
+
+This creates a \`.starrc\` file containing your gameId. Open \`.starrc\`, copy the \`gameId\` value, and pass it to \`Star.init()\`:
+
+\`\`\`javascript
+import Star from 'star-sdk';
+Star.init({ gameId: '<paste gameId from .starrc>' });
+\`\`\`
+
+**The gameId is a unique token issued by the Star API. Do not make one up \u2014 it will not work. You must run \`npx star-sdk init\` first and use the gameId it gives you.**
+
 ## API Overview
 
 | API | Use When | Docs |
@@ -35,7 +52,7 @@ import Star from 'star-sdk';
 
 \`\`\`javascript
 import Star from 'star-sdk';
-Star.init({ gameId: 'YOUR_GAME_ID' }); // from .starrc
+Star.init({ gameId: '<gameId from .starrc>' }); // run: npx star-sdk init
 
 Star.game(ctx => {
   const { canvas, width, height, ctx: c } = ctx;
@@ -72,6 +89,20 @@ function gameOver(finalScore) {
 }
 \`\`\`
 
+### Lower-is-Better Games (Time, Moves, Golf)
+
+For games where lower scores win, set \`sort: 'asc'\` in \`Star.init()\`:
+
+\`\`\`javascript
+Star.init({ gameId: '<gameId from .starrc>', leaderboard: { sort: 'asc' } });
+
+// Submit the raw value \u2014 do NOT invert the score
+Star.leaderboard.submit(reactionTimeMs);
+Star.leaderboard.show();
+\`\`\`
+
+**Do NOT** invert scores to fake ascending order (e.g., \`10000 - score\`). Use \`sort: 'asc'\` instead.
+
 ### Audio (It Just Works)
 
 Star.audio handles mobile audio unlocking automatically. Just call \`play()\` - no special handling needed.
@@ -109,7 +140,7 @@ Only these 17 presets exist:
 
 \`\`\`javascript
 import Star from 'star-sdk';
-Star.init({ gameId: 'YOUR_GAME_ID' }); // from .starrc
+Star.init({ gameId: '<gameId from .starrc>' }); // run: npx star-sdk init
 
 Star.game(ctx => {
   const { canvas, width, height, ctx: c } = ctx;
@@ -190,6 +221,16 @@ Star.game(ctx => {
 \`\`\`
 
 For detailed API documentation, see the linked files above.
+
+## Examples
+
+Complete working games are in the \`examples/\` directory (also published with the npm package):
+
+- **click-frenzy** \u2014 5-second click speed game with leaderboard
+- **dodge** \u2014 Avoid falling obstacles, keyboard and touch controls
+- **reaction-time** \u2014 Test your reflexes over 5 rounds, DOM-based (no canvas)
+
+Each example is a single HTML file, no build step \u2014 imports from esm.sh.
 `;
 var AUDIO_DOCS = `**Installation**
 
@@ -665,7 +706,7 @@ game(({ ctx, width, height, loop, toStagePoint, canvas }) => {
 import { game } from 'star-canvas';
 import { createLeaderboard } from 'star-leaderboard';
 
-const leaderboard = createLeaderboard({ gameId: 'YOUR_GAME_ID' });
+const leaderboard = createLeaderboard({ gameId: '<gameId from .starrc>' });
 
 game(({ ctx, width, height, loop, ui, on, canvas, toStagePoint }) => {
   let score = 0;
@@ -1006,6 +1047,16 @@ var LEADERBOARD_DOCS = `**Installation**
 yarn add star-leaderboard
 \`\`\`
 
+**Setup (do this first):**
+
+Register your game by running this in the terminal:
+
+\`\`\`bash
+npx star-sdk init "Game Name"
+\`\`\`
+
+This creates a \`.starrc\` file. Open it, copy the \`gameId\` value, and use it below. The gameId is a server-issued token \u2014 do not invent one. It must come from \`npx star-sdk init\`.
+
 ### Star Leaderboard SDK
 
 **Simple leaderboards for Star games.** Submit scores, show rankings, share results. Never crashes your game.
@@ -1013,7 +1064,7 @@ yarn add star-leaderboard
 **Import:**
 \`\`\`javascript
 import { createLeaderboard } from 'star-leaderboard';
-const leaderboard = createLeaderboard({ gameId: 'YOUR_GAME_ID' });
+const leaderboard = createLeaderboard({ gameId: '<gameId from .starrc>' });
 \`\`\`
 
 **CRITICAL:** Import in JavaScript - don't add \`<script>\` tags.
@@ -1026,7 +1077,7 @@ const leaderboard = createLeaderboard({ gameId: 'YOUR_GAME_ID' });
 import { createLeaderboard } from 'star-leaderboard';
 import { game } from 'star-canvas';
 
-const leaderboard = createLeaderboard({ gameId: 'YOUR_GAME_ID' });
+const leaderboard = createLeaderboard({ gameId: '<gameId from .starrc>' });
 
 game(({ ctx, width, height, loop, ui, on, canvas }) => {
   let score = 0;
@@ -1082,7 +1133,7 @@ leaderboard.showLeaderboard()   // Same as show()
 \`\`\`javascript
 import { createLeaderboard } from 'star-leaderboard';
 
-const leaderboard = createLeaderboard({ gameId: 'YOUR_GAME_ID' });
+const leaderboard = createLeaderboard({ gameId: '<gameId from .starrc>' });
 
 function gameOver(finalScore) {
   // Fire and forget - simplest approach
@@ -1096,7 +1147,7 @@ function gameOver(finalScore) {
 \`\`\`javascript
 import { createLeaderboard } from 'star-leaderboard';
 
-const leaderboard = createLeaderboard({ gameId: 'YOUR_GAME_ID' });
+const leaderboard = createLeaderboard({ gameId: '<gameId from .starrc>' });
 
 async function gameOver(finalScore) {
   const { success, rank } = await leaderboard.submit(finalScore);
@@ -1115,7 +1166,7 @@ async function gameOver(finalScore) {
 import { createLeaderboard } from 'star-leaderboard';
 import { game } from 'star-canvas';
 
-const leaderboard = createLeaderboard({ gameId: 'YOUR_GAME_ID' });
+const leaderboard = createLeaderboard({ gameId: '<gameId from .starrc>' });
 
 game(({ ui, on }) => {
   ui.render(\`
@@ -1136,7 +1187,7 @@ game(({ ui, on }) => {
 \`\`\`javascript
 import { createLeaderboard } from 'star-leaderboard';
 
-const leaderboard = createLeaderboard({ gameId: 'YOUR_GAME_ID' });
+const leaderboard = createLeaderboard({ gameId: '<gameId from .starrc>' });
 
 async function showCustomLeaderboard() {
   const { scores, you, config } = await leaderboard.getScores({
@@ -1161,7 +1212,7 @@ async function showCustomLeaderboard() {
 import { createLeaderboard } from 'star-leaderboard';
 import { game } from 'star-canvas';
 
-const leaderboard = createLeaderboard({ gameId: 'YOUR_GAME_ID' });
+const leaderboard = createLeaderboard({ gameId: '<gameId from .starrc>' });
 
 game(({ ctx, width, height, loop, ui, on, canvas }) => {
   let score = 0;
@@ -1214,11 +1265,7 @@ game(({ ctx, width, height, loop, ui, on, canvas }) => {
 
 **Configuration:**
 
-Always pass your gameId (from \`.starrc\`, created by \`npx star-sdk init\`):
-\`\`\`javascript
-import { createLeaderboard } from 'star-leaderboard';
-const leaderboard = createLeaderboard({ gameId: 'YOUR_GAME_ID' });
-\`\`\`
+Your gameId comes from \`.starrc\` (created by \`npx star-sdk init\`). See Setup at the top.
 
 ---
 
@@ -1286,6 +1333,7 @@ ${colors.bright}Star SDK CLI${colors.reset} v${VERSION}
 
 ${colors.dim}Commands:${colors.reset}
   ${colors.cyan}init <name>${colors.reset}        Register a new game
+  ${colors.cyan}deploy [path]${colors.reset}      Deploy game to Star hosting
   ${colors.cyan}install [agent]${colors.reset}    Install Star SDK docs for AI coding agents
   ${colors.cyan}docs [topic]${colors.reset}       Print API documentation (default: all docs)
   ${colors.cyan}whoami${colors.reset}             Show current configuration
@@ -1308,6 +1356,10 @@ ${colors.dim}Examples:${colors.reset}
   ${colors.dim}# Register a new game${colors.reset}
   npx star-sdk init "My Awesome Game"
 
+  ${colors.dim}# Deploy to Star hosting${colors.reset}
+  npx star-sdk deploy              ${colors.dim}# Deploy current directory${colors.reset}
+  npx star-sdk deploy ./dist       ${colors.dim}# Deploy specific directory${colors.reset}
+
   ${colors.dim}# Install for different AI agents${colors.reset}
   npx star-sdk install           ${colors.dim}# Claude Code (default)${colors.reset}
   npx star-sdk install codex     ${colors.dim}# OpenAI Codex${colors.reset}
@@ -1320,7 +1372,7 @@ ${colors.dim}Examples:${colors.reset}
   npx star-sdk docs audio        ${colors.dim}# Just audio API${colors.reset}
   npx star-sdk docs skill        ${colors.dim}# Just main skill file${colors.reset}
 
-${colors.dim}Learn more:${colors.reset} https://buildwithstar.com/docs
+${colors.dim}Learn more:${colors.reset} https://buildwithstar.com/docs/sdk
 `);
 }
 function showVersion() {
@@ -1380,7 +1432,8 @@ async function initCommand(name, email) {
       gameId: data.gameId,
       name: data.name,
       email: email?.trim(),
-      dashboardUrl: data.dashboardUrl
+      dashboardUrl: data.dashboardUrl,
+      deployKey: data.deployKey
     };
     saveConfig(config);
     log("");
@@ -1392,20 +1445,20 @@ async function initCommand(name, email) {
     log(`${colors.dim}Config saved to${colors.reset} ${colors.bright}.starrc${colors.reset}`);
     log("");
     log(`${colors.dim}Next steps:${colors.reset}`);
-    log(`  1. Install the leaderboard package: ${colors.cyan}yarn add star-leaderboard${colors.reset}`);
-    log(`  2. Submit scores and show the leaderboard`);
+    log(`  1. Add the SDK: ${colors.cyan}npm install star-sdk${colors.reset}`);
+    log(`  2. Build your game, then deploy: ${colors.cyan}npx star-sdk deploy${colors.reset}`);
     log("");
     log(`${colors.dim}Example:${colors.reset}`);
-    log(`  ${colors.cyan}import { createLeaderboard } from 'star-leaderboard';${colors.reset}`);
-    log(`  ${colors.cyan}const leaderboard = createLeaderboard({ gameId: '${data.gameId}' });${colors.reset}`);
-    log(`  ${colors.cyan}leaderboard.submit(1500);${colors.reset}`);
-    log(`  ${colors.cyan}leaderboard.show();${colors.reset}`);
+    log(`  ${colors.cyan}import Star from 'star-sdk';${colors.reset}`);
+    log(`  ${colors.cyan}Star.init({ gameId: '${data.gameId}' });${colors.reset}`);
+    log(`  ${colors.cyan}Star.leaderboard.submit(1500);${colors.reset}`);
+    log(`  ${colors.cyan}Star.leaderboard.show();${colors.reset}`);
     log("");
     log(`${colors.dim}Using an AI coding agent?${colors.reset}`);
-    log(`  ${colors.cyan}npx star-sdk install${colors.reset}        ${colors.dim}Claude Code, Codex, Cursor, Windsurf, Aider${colors.reset}`);
+    log(`  ${colors.cyan}npx star-sdk install${colors.reset}        ${colors.dim}Claude Code, Codex, Cursor, Aider${colors.reset}`);
     log("");
     log(`${colors.dim}Documentation:${colors.reset}`);
-    log(`  ${colors.cyan}https://buildwithstar.com/docs${colors.reset}`);
+    log(`  ${colors.cyan}https://buildwithstar.com/docs/sdk/sdk${colors.reset}`);
     log("");
   } catch (err) {
     if (err.code === "ECONNREFUSED" || err.code === "ENOTFOUND") {
@@ -1435,8 +1488,98 @@ function whoamiCommand() {
   if (config.dashboardUrl) {
     log(`  ${colors.dim}Dashboard:${colors.reset}  ${colors.cyan}${config.dashboardUrl}${colors.reset}`);
   }
+  if (config.deployUrl) {
+    log(`  ${colors.dim}Live URL:${colors.reset}   ${colors.cyan}${config.deployUrl}${colors.reset}`);
+  }
+  if (config.deployKey) {
+    log(`  ${colors.dim}Deploy key:${colors.reset} ${colors.dim}${config.deployKey.slice(0, 8)}...${colors.reset}`);
+  }
   log("");
 }
+async function deployCommand(dirPath) {
+  const config = loadConfig();
+  if (!config) {
+    error('No .starrc found. Run "npx star-sdk init <name>" first.');
+    process.exit(1);
+  }
+  if (!config.deployKey) {
+    error('No deploy key found. Re-run "npx star-sdk init <name>" to get one.');
+    process.exit(1);
+  }
+  const deployDir = dirPath ? path.resolve(dirPath) : process.cwd();
+  if (!fs.existsSync(deployDir)) {
+    error(`Directory not found: ${deployDir}`);
+    process.exit(1);
+  }
+  if (!fs.statSync(deployDir).isDirectory()) {
+    error(`Not a directory: ${deployDir}`);
+    process.exit(1);
+  }
+  const indexPath = path.join(deployDir, "index.html");
+  if (!fs.existsSync(indexPath)) {
+    error(`No index.html found in ${deployDir}`);
+    log("");
+    log("Your game needs an index.html file to deploy.");
+    process.exit(1);
+  }
+  log(`Deploying ${colors.bright}${config.name}${colors.reset} from ${colors.dim}${deployDir}${colors.reset}`);
+  try {
+    const archiver = (await import("archiver")).default;
+    const zipBuffer = await new Promise((resolve2, reject) => {
+      const chunks = [];
+      const archive = archiver("zip", { zlib: { level: 9 } });
+      archive.on("data", (chunk) => chunks.push(chunk));
+      archive.on("end", () => resolve2(Buffer.concat(chunks)));
+      archive.on("error", reject);
+      archive.glob("**/*", {
+        cwd: deployDir,
+        ignore: ["node_modules/**", ".starrc", ".git/**", ".DS_Store"],
+        dot: false
+      });
+      archive.finalize();
+    });
+    log(`  ${colors.dim}Uploading ${(zipBuffer.length / 1024).toFixed(1)} KB...${colors.reset}`);
+    const response = await fetch(`${API_BASE}/api/sdk/games/${config.gameId}/deploy`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/zip",
+        "x-deploy-key": config.deployKey
+      },
+      body: zipBuffer
+    });
+    if (!response.ok) {
+      const data2 = await response.json().catch(() => ({}));
+      if (response.status === 403) {
+        error(data2.error || 'Invalid deploy key. Re-run "npx star-sdk init" to get a new one.');
+      } else if (response.status === 404) {
+        error("Game not found. It may have been deleted.");
+      } else if (response.status === 413) {
+        error(data2.error || "Upload too large (50MB limit).");
+      } else if (response.status === 429) {
+        error(data2.error || "Rate limit exceeded. Try again later.");
+      } else {
+        error(data2.error || `Deploy failed (HTTP ${response.status})`);
+      }
+      process.exit(1);
+    }
+    const data = await response.json();
+    config.deployUrl = data.url;
+    saveConfig(config);
+    log("");
+    success("Deployed successfully!");
+    log("");
+    log(`  ${colors.dim}URL:${colors.reset}    ${colors.cyan}${data.url}${colors.reset}`);
+    log(`  ${colors.dim}Files:${colors.reset}  ${data.files} files, ${data.assets} assets`);
+    log("");
+  } catch (err) {
+    if (err.code === "ECONNREFUSED" || err.code === "ENOTFOUND") {
+      error("Could not connect to Star API. Check your internet connection.");
+    } else {
+      error(err.message || "Deploy failed");
+    }
+    process.exit(1);
+  }
+}
 function transformForStdout(content) {
   return content.replace(/\[(\w+)\.md\]\(\.\/\1\.md\)/g, "$1 (`npx star-sdk docs $1`)").replace(/see (\w+)\.md/g, "run `npx star-sdk docs $1`").replace(
     /For detailed API documentation, see the linked files above\./,
@@ -1647,6 +1790,9 @@ async function main() {
     case "init":
       await initCommand(positional[0], email);
       break;
+    case "deploy":
+      await deployCommand(positional[0]);
+      break;
     case "install": {
       const agent = positional[0] || "claude";
       const scope = flags.project ? "project" : "global";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "star-sdk-cli",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "CLI tool for Star SDK - register games and manage leaderboards",
   "type": "module",
   "bin": {
@@ -18,6 +18,16 @@
     "build": "tsup",
     "dev": "tsx src/cli.ts"
   },
+  "license": "MIT",
+  "homepage": "https://buildwithstar.com/docs/sdk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/buildwithstar/star-sdk",
+    "directory": "packages/star-sdk-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/buildwithstar/star-sdk/issues"
+  },
   "keywords": [
     "star",
     "sdk",
@@ -25,7 +35,11 @@
     "games",
     "leaderboard"
   ],
+  "dependencies": {
+    "archiver": "^7.0.0"
+  },
   "devDependencies": {
+    "@types/archiver": "^6.0.0",
     "tsup": "^8.0.0",
     "tsx": "^4.7.0",
     "typescript": "^5.4.5"