star-sdk-cli 0.1.12 → 0.1.14

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

@@ -231,6 +231,16 @@ Complete working games are in the \`examples/\` directory (also published with t
 - **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**
 
@@ -413,24 +423,22 @@ game(({ ctx, width, height, on, loop, ui, canvas }) => {
   });
 
   // 2. Render HTML to the safe UI overlay
-  //    UI is interactive by default (scroll, buttons work)
-  //    Adding canvas.addEventListener makes UI click-through automatically
   ui.render(\`
     <div class="absolute top-4 left-4 text-white">
-      <button id="start-btn" class="px-4 py-2 bg-blue-500 rounded pointer-events-auto">
+      <button id="start-btn" class="px-4 py-2 bg-blue-500 rounded">
         Click Me
       </button>
     </div>
   \`);
 
-  // 3. Listen for button clicks
+  // 3. Listen for button clicks \u2014 on() auto-enables pointer-events for the target
   on('click', '#start-btn', () => {
     console.log('Button clicked!');
   });
 
   // 4. For canvas games: listen for taps on canvas
-  //    This automatically makes UI click-through (taps pass through to canvas)
-  //    Buttons with pointer-events-auto still work
+  //    Taps pass through the UI overlay to the canvas layer
+  //    Elements targeted by on() are automatically interactive
   canvas.addEventListener('pointerdown', (e) => {
     console.log('Canvas/screen tapped!', e);
   });
@@ -495,7 +503,7 @@ A safe manager for your HTML overlay, stacked on top of the canvas.
   - \`ui.el(selector)\`: Scoped \`querySelector\` for the UI root.
   - \`ui.all(selector)\`: Scoped \`querySelectorAll\` for the UI root.
 
-**Auto-detection:** When you add \`canvas.addEventListener('pointerdown', ...)\`, the SDK automatically makes UI click-through so taps reach the canvas. Buttons with \`pointer-events-auto\` still work.
+**Auto-detection:** When you add \`canvas.addEventListener('pointerdown', ...)\`, the SDK automatically makes UI click-through so taps reach the canvas. Elements targeted by \`on()\` are automatically interactive \u2014 no extra CSS classes needed. Native \`<button>\` and \`<a>\` elements are also always interactive.
 
 ### Cursor Management
 
@@ -723,13 +731,13 @@ game(({ ctx, width, height, loop, ui, on, canvas, toStagePoint }) => {
   // 1. Listen for screen taps - this makes UI click-through automatically
   canvas.addEventListener('pointerdown', handleTap);
 
-  // 2. Listen for button clicks - buttons need pointer-events-auto
+  // 2. Listen for button clicks \u2014 on() auto-enables pointer-events for the selector
   on('click', '#leaderboard-btn', (e) => {
     e.stopPropagation();
     leaderboard.show();
   });
 
-  // 3. Render UI - buttons need pointer-events-auto to intercept clicks
+  // 3. Render UI \u2014 elements targeted by on() are automatically interactive
   let lastState = null;
   let lastScore = -1;
 
@@ -756,7 +764,7 @@ game(({ ctx, width, height, loop, ui, on, canvas, toStagePoint }) => {
         <div class="h-full flex flex-col items-center justify-center text-white">
           <div class="text-3xl mb-4">GAME OVER</div>
           <div class="text-6xl mb-4">\\\${score}</div>
-          <button id="leaderboard-btn" class="px-6 py-3 mb-4 bg-gradient-to-r from-blue-600 to-purple-600 rounded-xl font-bold shadow-lg shadow-blue-500/20 pointer-events-auto">
+          <button id="leaderboard-btn" class="px-6 py-3 mb-4 bg-gradient-to-r from-blue-600 to-purple-600 rounded-xl font-bold shadow-lg shadow-blue-500/20">
             VIEW LEADERBOARD
           </button>
           <div class="text-xl animate-pulse">TAP TO RESTART</div>
@@ -1098,7 +1106,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)
 
 ---
 
@@ -1170,7 +1178,7 @@ const leaderboard = createLeaderboard({ gameId: '<gameId from .starrc>' });
 
 game(({ ui, on }) => {
   ui.render(\`
-    <button id="lb-btn" class="px-6 py-3 bg-gradient-to-r from-blue-600 to-purple-600 rounded-xl font-bold text-white shadow-lg shadow-blue-500/20 pointer-events-auto">
+    <button id="lb-btn" class="px-6 py-3 bg-gradient-to-r from-blue-600 to-purple-600 rounded-xl font-bold text-white shadow-lg shadow-blue-500/20">
       View Leaderboard
     </button>
   \`);
@@ -1237,7 +1245,7 @@ game(({ ctx, width, height, loop, ui, on, canvas }) => {
         <div class="h-full flex flex-col items-center justify-center text-white">
           <div class="text-3xl mb-4">GAME OVER</div>
           <div class="text-6xl mb-4">\\\${score}</div>
-          <button id="lb-btn" class="px-6 py-3 mb-4 bg-gradient-to-r from-blue-600 to-purple-600 rounded-xl font-bold shadow-lg shadow-blue-500/20 pointer-events-auto">
+          <button id="lb-btn" class="px-6 py-3 mb-4 bg-gradient-to-r from-blue-600 to-purple-600 rounded-xl font-bold shadow-lg shadow-blue-500/20">
             VIEW LEADERBOARD
           </button>
           <div class="text-xl animate-pulse">TAP TO RESTART</div>
@@ -1289,6 +1297,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.
@@ -1327,6 +1356,52 @@ function error(message) {
 function info(message) {
   console.log(`${colors.blue}\u2139${colors.reset} ${message}`);
 }
+var STAR_PACKAGES = ["star-sdk", "star-canvas", "star-audio", "star-leaderboard", "star-multiplayer"];
+function resolveStarSdkVersion(deployDir) {
+  const candidates = [
+    path.join(deployDir, "node_modules", "star-sdk", "package.json"),
+    path.join(process.cwd(), "node_modules", "star-sdk", "package.json")
+  ];
+  for (const p of candidates) {
+    try {
+      if (fs.existsSync(p)) {
+        const pkg = JSON.parse(fs.readFileSync(p, "utf-8"));
+        if (pkg.version) return pkg.version;
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+function injectImportMapIfNeeded(html, deployDir) {
+  if (/<script\s[^>]*type\s*=\s*["']importmap["'][^>]*>/i.test(html)) {
+    return html;
+  }
+  const bareImportPattern = /\bfrom\s+['"](?:star-sdk|star-canvas|star-audio|star-leaderboard|star-multiplayer)['"]/;
+  if (!bareImportPattern.test(html)) {
+    return html;
+  }
+  const version = resolveStarSdkVersion(deployDir);
+  const suffix = version ? `@${version}` : "";
+  const imports = {};
+  for (const pkg of STAR_PACKAGES) {
+    imports[pkg] = `https://esm.sh/${pkg}${suffix}`;
+  }
+  const importmapTag = `<script type="importmap">
+${JSON.stringify({ imports }, null, 2)}
+</script>
+`;
+  const moduleScriptMatch = html.match(/<script\s[^>]*type\s*=\s*["']module["'][^>]*>/i);
+  if (moduleScriptMatch && moduleScriptMatch.index !== void 0) {
+    return html.slice(0, moduleScriptMatch.index) + importmapTag + html.slice(moduleScriptMatch.index);
+  }
+  const headMatch = html.match(/<head[^>]*>/i);
+  if (headMatch && headMatch.index !== void 0) {
+    const insertPos = headMatch.index + headMatch[0].length;
+    return html.slice(0, insertPos) + "\n" + importmapTag + html.slice(insertPos);
+  }
+  return html;
+}
 function showHelp() {
   log(`
 ${colors.bright}Star SDK CLI${colors.reset} v${VERSION}
@@ -1524,6 +1599,12 @@ async function deployCommand(dirPath) {
   }
   log(`Deploying ${colors.bright}${config.name}${colors.reset} from ${colors.dim}${deployDir}${colors.reset}`);
   try {
+    const originalHtml = fs.readFileSync(indexPath, "utf-8");
+    const processedHtml = injectImportMapIfNeeded(originalHtml, deployDir);
+    const htmlModified = processedHtml !== originalHtml;
+    if (htmlModified) {
+      info("Injected importmap for bare imports (star-sdk \u2192 esm.sh)");
+    }
     const archiver = (await import("archiver")).default;
     const zipBuffer = await new Promise((resolve2, reject) => {
       const chunks = [];
@@ -1533,9 +1614,10 @@ async function deployCommand(dirPath) {
       archive.on("error", reject);
       archive.glob("**/*", {
         cwd: deployDir,
-        ignore: ["node_modules/**", ".starrc", ".git/**", ".DS_Store"],
+        ignore: ["node_modules/**", ".starrc", ".git/**", ".DS_Store", "index.html"],
         dot: false
       });
+      archive.append(processedHtml, { name: "index.html" });
       archive.finalize();
     });
     log(`  ${colors.dim}Uploading ${(zipBuffer.length / 1024).toFixed(1)} KB...${colors.reset}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "star-sdk-cli",
-  "version": "0.1.12",
-  "description": "CLI tool for Star SDK - register games and manage leaderboards",
+  "version": "0.1.14",
+  "description": "CLI for Star SDK — register games, install AI docs, and deploy to Star hosting",
   "type": "module",
   "bin": {
     "star-sdk": "./dist/cli.mjs"
@@ -33,7 +33,9 @@
     "sdk",
     "cli",
     "games",
-    "leaderboard"
+    "leaderboard",
+    "deploy",
+    "hosting"
   ],
   "dependencies": {
     "archiver": "^7.0.0"