star-sdk-cli 0.1.11 → 0.1.13

package/README.md

@@ -0,0 +1,52 @@
+# star-sdk-cli
+
+CLI for [Star SDK](https://www.npmjs.com/package/star-sdk) — register games, deploy to hosting, and install AI coding docs.
+
+## Usage
+
+All commands run via `npx star-sdk` (no global install needed).
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `npx star-sdk init "Game Name"` | Register a game, get a gameId and deploy key |
+| `npx star-sdk deploy [path]` | Deploy your game to Star hosting |
+| `npx star-sdk install [agent]` | Install SDK docs for AI coding tools |
+| `npx star-sdk docs [topic]` | Print API docs (audio, canvas, leaderboard) |
+| `npx star-sdk whoami` | Show current game config |
+
+### Workflow
+
+```bash
+# 1. Register your game
+npx star-sdk init "My Game"
+# Creates .starrc with gameId and deploy key
+
+# 2. Build your game (use the gameId from .starrc)
+# ... write your game code ...
+
+# 3. Deploy
+npx star-sdk deploy
+# => Live at https://buildwithstar.com/games/<id>
+```
+
+### AI Agent Support
+
+Install SDK documentation directly into your AI coding tool:
+
+```bash
+npx star-sdk install          # Claude Code (default)
+npx star-sdk install cursor   # Cursor
+npx star-sdk install codex    # OpenAI Codex
+npx star-sdk install windsurf # Windsurf
+npx star-sdk install aider    # Aider
+```
+
+## Documentation
+
+Full docs at [buildwithstar.com/docs/sdk](https://buildwithstar.com/docs/sdk)
+
+## License
+
+MIT

package/dist/cli.mjs

@@ -89,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.
@@ -207,6 +221,26 @@ 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.
+
+## Deploy
+
+When the game is ready, deploy it with one command:
+
+\`\`\`bash
+npx star-sdk deploy
+\`\`\`
+
+This uploads the game to Star hosting and returns a live URL. Requires \`npx star-sdk init\` to have been run first (which creates the deploy key in \`.starrc\`).
 `;
 var AUDIO_DOCS = `**Installation**
 
@@ -1074,7 +1108,7 @@ game(({ ctx, width, height, loop, ui, on, canvas }) => {
 - Score submission (works for guests and logged-in users)
 - Leaderboard UI (modal with rankings)
 - Weekly/all-time timeframes
-- AI-detected scoring (score/time/moves - higher or lower is better)
+- Configurable sort order (\`'asc'\` for lower-is-better, \`'desc'\` for higher-is-better)
 
 ---
 
@@ -1265,6 +1299,27 @@ const data = await leaderboard.getScores({
 
 ---
 
+**Sort Order:**
+
+By default, leaderboards rank higher scores first (\`'desc'\`). For games where lower is better (reaction time, speedruns, golf), set \`sort: 'asc'\`:
+
+\`\`\`javascript
+const leaderboard = createLeaderboard({ gameId: '<gameId from .starrc>', sort: 'asc' });
+\`\`\`
+
+**IMPORTANT: Do NOT invert scores to fake ascending order.** Use \`sort: 'asc'\` instead.
+
+\`\`\`javascript
+// BAD \u2014 do not do this
+leaderboard.submit(10000 - reactionTimeMs);
+
+// GOOD \u2014 submit the real value with sort: 'asc'
+const leaderboard = createLeaderboard({ gameId, sort: 'asc' });
+leaderboard.submit(reactionTimeMs);
+\`\`\`
+
+---
+
 **Tips:**
 
 1. **Call \`submit()\` before \`show()\`** - Ensures your score appears immediately in the leaderboard.
@@ -1309,6 +1364,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
@@ -1331,6 +1387,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}
@@ -1343,7 +1403,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() {
@@ -1403,7 +1463,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("");
@@ -1415,20 +1476,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") {
@@ -1458,8 +1519,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\./,
@@ -1670,6 +1821,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,7 +1,7 @@
 {
   "name": "star-sdk-cli",
-  "version": "0.1.11",
-  "description": "CLI tool for Star SDK - register games and manage leaderboards",
+  "version": "0.1.13",
+  "description": "CLI for Star SDK — register games, install AI docs, and deploy to Star hosting",
   "type": "module",
   "bin": {
     "star-sdk": "./dist/cli.mjs"
@@ -18,14 +18,30 @@
     "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",
     "cli",
     "games",
-    "leaderboard"
+    "leaderboard",
+    "deploy",
+    "hosting"
   ],
+  "dependencies": {
+    "archiver": "^7.0.0"
+  },
   "devDependencies": {
+    "@types/archiver": "^6.0.0",
     "tsup": "^8.0.0",
     "tsx": "^4.7.0",
     "typescript": "^5.4.5"