@puzzmo/cli 1.0.40 → 1.0.42

package/src/index.ts

@@ -1,76 +1,93 @@
 #!/usr/bin/env node
 
+import { defineCommand, runMain } from "citty"
+
 import { agentTest } from "./commands/agent-test.js"
+import { gameCreate } from "./commands/game/create.js"
 import { login } from "./commands/login.js"
+import { migrate } from "./commands/migrate.js"
 import { upload } from "./commands/upload.js"
 import { validate } from "./commands/validate.js"
-import { gameCreate } from "./commands/game/create.js"
-import { migrate } from "./commands/migrate.js"
+import { defaultSource } from "./util/config.js"
+
+const loginCommand = defineCommand({
+  meta: {
+    name: "login",
+    description: "Save a CLI auth token. Multiple tokens can be stored, one per --source server.",
+  },
+  args: {
+    token: { type: "positional", description: "The pzt- token from dev.puzzmo.com", required: true },
+    source: { type: "string", description: "Server this token belongs to", default: defaultSource },
+  },
+  run: ({ args }) => login(args.token, args.source),
+})
 
-const [command, ...args] = process.argv.slice(2)
+const uploadCommand = defineCommand({
+  meta: {
+    name: "upload",
+    description: "Discover puzzmo.json files and upload each game's build and sync the puzzmo.json.",
+  },
+  args: {
+    dir: { type: "positional", description: "Directory to scan", required: false, default: "." },
+    verbose: { type: "boolean", description: "Print request URLs and full error bodies", alias: "v" },
+  },
+  run: ({ args }) => upload(args.dir, { verbose: args.verbose }),
+})
 
-const printUsage = () => {
-  console.log(`Usage:
-  puzzmo login <token>            Save a CLI auth token
-  puzzmo game create [token]      Create a new Puzzmo game project
+const validateCommand = defineCommand({
+  meta: { name: "validate", description: "Validate every puzzmo.json under [dir]" },
+  args: {
+    dir: { type: "positional", description: "Directory to scan", required: false, default: "." },
+  },
+  run: ({ args }) => validate(args.dir),
+})
 
-  puzzmo upload [dir] [-v]        Discover puzzmo.json files in [dir] (default: .) and upload each game's build. -v/--verbose prints request URLs and full error bodies. If a game does not exist on your account and stdin is a TTY, you'll be asked whether to create it (using your saved CLI token).
-  puzzmo validate [dir]           Discover and validate every puzzmo.json under [dir] (default: .)
-  puzzmo migrate                  List and select migration skills from dev.puzzmo.com`)
-}
+const migrateCommand = defineCommand({
+  meta: { name: "migrate", description: "List and select migration skills from dev.puzzmo.com" },
+  run: () => migrate(),
+})
 
-const run = async () => {
-  switch (command) {
-    case "login": {
-      const token = args[0]
-      if (!token) {
-        console.error("Usage: puzzmo login <token>")
-        process.exit(1)
-      }
-      login(token)
-      break
-    }
-    case "upload": {
-      const verbose = args.includes("--verbose") || args.includes("-v")
-      const dir = args.find((a) => !a.startsWith("-")) ?? "."
-      await upload(dir, { verbose })
-      break
-    }
-    case "game": {
-      const [subcommand, ...subArgs] = args
-      if (subcommand === "create") {
-        await gameCreate(subArgs)
-      } else {
-        console.error(
-          "Usage: puzzmo game create [--strategy <import|blank|prompt>] [--prompt <text>] [--name <name>] [--url <url>] [--agent <agent>] [--token <token>] [--pm <npm|yarn|pnpm>]",
-        )
-        process.exit(1)
-      }
-      break
-    }
-    case "validate": {
-      validate(args[0] || ".")
-      break
-    }
-    case "migrate": {
-      await migrate()
-      break
-    }
-    case "agent-test": {
-      await agentTest()
-      break
-    }
-    default:
-      printUsage()
-      break
-  }
-}
+const gameCreateCommand = defineCommand({
+  meta: { name: "create", description: "Scaffold a new Puzzmo game project" },
+  args: {
+    strategy: { type: "enum", options: ["import", "blank", "prompt"], description: "How to seed the new game" },
+    prompt: { type: "string", description: "Game description (used with --strategy prompt)" },
+    name: { type: "string", description: "Game display name" },
+    url: { type: "string", description: "Source URL (used with --strategy import)" },
+    agent: { type: "string", description: "LLM agent id to drive scaffolding" },
+    token: { type: "string", description: "Save this token before creating the game" },
+    pm: { type: "enum", options: ["npm", "yarn", "pnpm"], description: "Package manager to use" },
+  },
+  run: ({ args }) =>
+    gameCreate({
+      strategy: args.strategy,
+      prompt: args.prompt,
+      name: args.name,
+      url: args.url,
+      agent: args.agent,
+      accessToken: args.token,
+      pm: args.pm,
+    }),
+})
 
-run().catch((err) => {
-  console.error(err.message || err)
-  if (err && err.cause) {
-    const cause = err.cause
-    console.error(`Caused by: ${cause instanceof Error ? cause.message : cause}`)
-  }
-  process.exit(1)
+const gameCommand = defineCommand({
+  meta: { name: "game", description: "Game project commands" },
+  subCommands: { create: gameCreateCommand },
 })
+
+const main = defineCommand({
+  meta: { name: "puzzmo", description: "Puzzmo CLI" },
+  subCommands: {
+    login: loginCommand,
+    upload: uploadCommand,
+    validate: validateCommand,
+    migrate: migrateCommand,
+    game: gameCommand,
+    "agent-test": defineCommand({
+      meta: { name: "agent-test", description: "Run the agent test harness", hidden: true },
+      run: () => agentTest(),
+    }),
+  },
+})
+
+runMain(main)

package/src/util/api.ts

@@ -1,8 +1,6 @@
 import fs from "node:fs"
 import path from "node:path"
 
-import { getAPIURL } from "./config.js"
-
 /** The schema for a puzzmo.json file - mirrors PuzzmoFile from @puzzmo-com/shared/hostAPI */
 export type PuzzmoFile = {
   game: {
@@ -132,6 +130,7 @@ const formatBytes = (bytes: number): string => {
 
 /** Multi-step upload: init -> batched file uploads -> complete */
 export const uploadFiles = async (
+  apiURL: string,
   token: string,
   gameSlug: string,
   sha: string,
@@ -142,7 +141,6 @@ export const uploadFiles = async (
   options: UploadFilesOptions = {},
 ): Promise<CompleteResponse> => {
   const { verbose = false, description, repoURL } = options
-  const apiURL = getAPIURL()
   if (verbose) console.log(`  API URL: ${apiURL}`)
 
   // Step 1: Init session (includes puzzmo.json metadata)

package/src/util/config.ts

@@ -5,33 +5,137 @@ import path from "node:path"
 const configDir = path.join(os.homedir(), ".puzzmo")
 const configPath = path.join(configDir, "config.json")
 
-type Config = {
-  token?: string
-  apiURL?: string
+export const defaultSource = "https://api.puzzmo.com"
+
+export type TokenEntry = {
+  /** Server identifier (e.g. "api.puzzmo.com" or "localhost:8911") */
+  source: string
+  /** The pzt- prefixed JWT issued by that server */
+  token: string
 }
 
-/** Reads the CLI config from ~/.puzzmo/config.json */
+type Config = { tokens: TokenEntry[] }
+
+/** Reads ~/.puzzmo/config.json. Returns an empty token list if the file doesn't exist. */
 export const readConfig = (): Config => {
   try {
-    const raw = fs.readFileSync(configPath, "utf-8")
-    return JSON.parse(raw)
+    const parsed = JSON.parse(fs.readFileSync(configPath, "utf-8")) as Partial<Config>
+    return { tokens: parsed.tokens ?? [] }
   } catch {
-    return {}
+    return { tokens: [] }
   }
 }
 
-/** Writes the CLI config to ~/.puzzmo/config.json */
-export const writeConfig = (config: Config) => {
+const writeConfig = (config: Config) => {
   fs.mkdirSync(configDir, { recursive: true })
   fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n")
 }
 
-/** Returns the auth token from config or PUZZMO_TOKEN env var */
-export const getToken = (): string | undefined => {
-  return process.env.PUZZMO_TOKEN || readConfig().token
+/** Saves a token for `source`, replacing any existing entry for that same source */
+export const addToken = (source: string, token: string) => {
+  const normalized = normalizeSource(source)
+  const { tokens } = readConfig()
+  const remaining = tokens.filter((t) => normalizeSource(t.source) !== normalized)
+  remaining.push({ source: normalized, token })
+  writeConfig({ tokens: remaining })
+}
+
+/** Removes any saved token for `source`. Returns true if something was removed. */
+export const removeToken = (source: string): boolean => {
+  const normalized = normalizeSource(source)
+  const { tokens } = readConfig()
+  const remaining = tokens.filter((t) => normalizeSource(t.source) !== normalized)
+  if (remaining.length === tokens.length) return false
+  writeConfig({ tokens: remaining })
+  return true
 }
 
-/** Returns the API base URL */
-export const getAPIURL = (): string => {
-  return process.env.PUZZMO_API_URL || readConfig().apiURL || "https://api.puzzmo.com"
+/** Returns saved tokens. PUZZMO_TOKEN env var (with optional PUZZMO_API_URL) overrides everything. */
+export const getTokens = (): TokenEntry[] => {
+  const envToken = process.env.PUZZMO_TOKEN
+  if (envToken) {
+    const source = normalizeSource(process.env.PUZZMO_API_URL ?? defaultSource)
+    return [{ source, token: envToken }]
+  }
+  return readConfig().tokens
+}
+
+/** Best-guess token for clients that don't care which server it points at (e.g. .mcp.json scaffolding) */
+export const getDefaultToken = (): string | undefined => getTokens()[0]?.token
+
+type TokenPayload = { teamID?: string; createdByID?: string; iat?: number }
+
+/** Decodes a `pzt-<jwt>` token (without verifying) and returns its payload, or null on failure */
+export const decodeTokenPayload = (token: string): TokenPayload | null => {
+  try {
+    const stripped = token.startsWith("pzt-") ? token.slice(4) : token
+    const parts = stripped.split(".")
+    if (parts.length < 2) return null
+    const payload = parts[1].replace(/-/g, "+").replace(/_/g, "/")
+    const padded = payload + "=".repeat((4 - (payload.length % 4)) % 4)
+    return JSON.parse(Buffer.from(padded, "base64").toString("utf-8")) as TokenPayload
+  } catch {
+    return null
+  }
+}
+
+/** Strips protocol and trailing slashes so two spellings of the same server compare equal */
+export const normalizeSource = (source: string): string =>
+  source
+    .trim()
+    .replace(/^https?:\/\//, "")
+    .replace(/\/+$/, "")
+
+/** Re-attaches a protocol to a normalized source. Localhost defaults to http, everything else to https. */
+export const sourceToURL = (source: string): string => {
+  const trimmed = source.trim().replace(/\/+$/, "")
+  if (/^https?:\/\//.test(trimmed)) return trimmed
+  const normalized = normalizeSource(trimmed)
+  if (isLocalhost(normalized)) return `http://${normalized}`
+  return `https://${normalized}`
+}
+
+const isLocalhost = (source: string): boolean => {
+  const n = normalizeSource(source)
+  return n.startsWith("localhost") || n.startsWith("127.0.0.1") || n.startsWith("0.0.0.0")
+}
+
+const isPuzzmoCom = (source: string): boolean => /(^|\.)puzzmo\.com(:|\/|$)/.test(normalizeSource(source))
+
+/** Sorts saved tokens by upload preference: localhost > *.puzzmo.com > anything else */
+export const sortByServerPriority = (tokens: TokenEntry[]): TokenEntry[] => {
+  const priority = (t: TokenEntry) => (isLocalhost(t.source) ? 0 : isPuzzmoCom(t.source) ? 1 : 2)
+  return [...tokens].sort((a, b) => priority(a) - priority(b))
+}
+
+/** Returns saved tokens whose JWT teamID matches the given teamID */
+export const findTokensForTeam = (teamID: string): TokenEntry[] => getTokens().filter((t) => decodeTokenPayload(t.token)?.teamID === teamID)
+
+/** True if a quick fetch to `${source}/graphql` returns any HTTP response within `timeoutMs` */
+export const isServerReachable = async (source: string, timeoutMs = 1500): Promise<boolean> => {
+  const url = `${sourceToURL(source)}/graphql`
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    await fetch(url, { method: "GET", signal: controller.signal })
+    return true
+  } catch {
+    return false
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Picks the (source, token) pair to use for `teamID`. Prefers localhost when reachable,
+ * then *.puzzmo.com, then any other matching source. Returns null if no token matches.
+ */
+export const resolveServerForTeam = async (teamID: string): Promise<TokenEntry | null> => {
+  const matches = sortByServerPriority(findTokensForTeam(teamID))
+  if (matches.length === 0) return null
+  for (const candidate of matches) {
+    if (isLocalhost(candidate.source) && !(await isServerReachable(candidate.source))) continue
+    return candidate
+  }
+  return null
 }

package/src/util/createGame.ts

@@ -1,5 +1,3 @@
-import { getAPIURL } from "./config.js"
-
 const createUserGameMutation = `
   mutation cliCreateUserGameMutation($teamAccessToken: String!, $input: CreateUserGameInput!) {
     createUserGame(teamAccessToken: $teamAccessToken, input: $input) {
@@ -22,6 +20,8 @@ type CreateUserGameResponse = {
 }
 
 export type CreateUserGameOptions = {
+  /** Base URL of the API server to call (e.g. "https://api.puzzmo.com") */
+  apiURL: string
   /** A teamAccessToken (the same token saved by `puzzmo login`). The mutation uses it to identify the team. */
   teamAccessToken: string
   displayName: string
@@ -31,7 +31,7 @@ export type CreatedGame = { id: string; slug: string; displayName: string; newAc
 
 /** Calls the createUserGame mutation using a teamAccessToken for auth. */
 export const createUserGame = async (options: CreateUserGameOptions): Promise<CreatedGame> => {
-  const url = `${getAPIURL()}/graphql`
+  const url = `${options.apiURL}/graphql`
 
   const response = await fetch(url, {
     method: "POST",

package/templates/minesweeper/vite.config.ts

@@ -2,6 +2,7 @@ import { defineConfig } from "vite"
 import { puzzmoSimulator, appBundlePlugin } from "@puzzmo/sdk/vite"
 
 export default defineConfig({
+  base: "./",
   plugins: [puzzmoSimulator({ fixturesGlob: "/fixtures/puzzles/**/*.json" }), appBundlePlugin()],
   build: {
     outDir: "dist",