@puzzmo/cli 1.0.32 → 1.0.34

package/src/agents/gemini.ts

@@ -0,0 +1,74 @@
+import { runStreamJsonCli } from "./stream-json-cli.js"
+import type { Agent, AgentEvent } from "./types.js"
+
+/** Gemini adapter — wraps the local `gemini` CLI in subprocess + stream-json
+ *  mode. Auth delegates to the user's `gemini` CLI login (Google account /
+ *  Code Assist) or falls back to GEMINI_API_KEY. */
+export const geminiAgent: Agent = {
+  name: "gemini",
+  run: (input) =>
+    runStreamJsonCli(
+      {
+        cmd: "gemini",
+        buildArgs: (prompt) => ["-p", prompt, "--output-format", "stream-json"],
+        parseLine: parseGeminiLine,
+      },
+      input,
+    ),
+}
+
+/** Map one stream-json line from gemini to an AgentEvent (or null to skip).
+ *  Event union per `@google/gemini-cli-core`'s `JsonStreamEvent`:
+ *  init / message / tool_use / tool_result / error / result. */
+const parseGeminiLine = (line: string): AgentEvent | null => {
+  let obj: any
+  try {
+    obj = JSON.parse(line)
+  } catch {
+    return { type: "system", text: line }
+  }
+
+  if (obj.type === "init") return { type: "system", text: "Session started" }
+
+  if (obj.type === "message") {
+    // Streaming deltas flow inline; complete `content` chunks get a trailing newline
+    // so consecutive messages don't glue together in the rendered output.
+    if (typeof obj.delta === "string") {
+      return obj.role === "thinking" ? { type: "thinking", text: obj.delta } : { type: "text", text: obj.delta }
+    }
+    const text = obj.content ?? ""
+    if (!text) return null
+    const withNL = text.endsWith("\n") ? text : text + "\n"
+    return obj.role === "thinking" ? { type: "thinking", text: withNL } : { type: "text", text: withNL }
+  }
+
+  if (obj.type === "tool_use") {
+    const name = obj.tool_name ?? "tool"
+    return { type: "tool_use", name, summary: summarizeToolInput(name, obj.parameters ?? {}) }
+  }
+
+  if (obj.type === "tool_result") {
+    const ok = obj.status === "success" || obj.status === "ok"
+    const summary = String(obj.output ?? obj.error ?? "").slice(0, 200)
+    return { type: "tool_result", ok, summary }
+  }
+
+  if (obj.type === "error") return { type: "error", message: obj.message ?? "" }
+
+  if (obj.type === "result") {
+    const ok = obj.status === "success" || obj.status === "ok"
+    const cost = typeof obj.stats?.cost_usd === "number" ? obj.stats.cost_usd : undefined
+    return { type: "result", ok, costUSD: cost }
+  }
+
+  return null
+}
+
+const summarizeToolInput = (name: string, input: any): string => {
+  if (!input || typeof input !== "object") return ""
+  if (typeof input.command === "string") return input.command.slice(0, 200)
+  if (typeof input.file_path === "string") return input.file_path
+  if (typeof input.path === "string") return input.path
+  if (typeof input.pattern === "string") return input.pattern
+  return name
+}

package/src/agents/index.ts

@@ -0,0 +1,20 @@
+import { claudeAgent } from "./claude.js"
+import { codexAgent } from "./codex.js"
+import { copilotAgent } from "./copilot.js"
+import { geminiAgent } from "./gemini.js"
+import { opencodeAgent } from "./opencode.js"
+import type { Agent } from "./types.js"
+
+export type { Agent, AgentEvent, RunInput } from "./types.js"
+
+export const AGENTS: Record<string, Agent> = {
+  claude: claudeAgent,
+  codex: codexAgent,
+  copilot: copilotAgent,
+  gemini: geminiAgent,
+  opencode: opencodeAgent,
+}
+
+export const getAgent = (name: string): Agent | undefined => AGENTS[name]
+
+export const agentNames = (): string[] => Object.keys(AGENTS)

package/src/agents/opencode.ts

@@ -0,0 +1,154 @@
+import { createOpencodeClient, createOpencodeServer } from "@opencode-ai/sdk"
+
+import type { Agent, AgentEvent, RunInput } from "./types.js"
+
+/** OpenCode adapter — spawns a local opencode server, opens an SSE stream
+ *  against it, creates a session, and sends a prompt. Auth lives in the
+ *  user's `opencode` CLI config / `client.auth.set()`. */
+export const opencodeAgent: Agent = {
+  name: "opencode",
+  run(input) {
+    return runOpencode(input)
+  },
+}
+
+const runOpencode = async function* (input: RunInput): AsyncIterable<AgentEvent> {
+  const cwd = input.cwd ?? process.cwd()
+
+  let server
+  try {
+    server = await createOpencodeServer({ signal: input.signal, config: { project: cwd } as any })
+  } catch (e: any) {
+    yield { type: "error", message: `Opencode server failed to start: ${e.message}` }
+    return
+  }
+
+  const client = createOpencodeClient({ baseUrl: server.url as `${string}://${string}` })
+
+  // Buffered event queue + waiter, so the SSE consumer pushes and the generator yields.
+  const events: AgentEvent[] = []
+  let waiting: (() => void) | null = null
+  const wake = () => {
+    waiting?.()
+    waiting = null
+  }
+  const push = (e: AgentEvent) => {
+    events.push(e)
+    wake()
+  }
+
+  let done = false
+  let sessionID: string | null = null
+
+  // Start SSE before sending a prompt so we don't lose early events.
+  const sseTask = (async () => {
+    try {
+      const sub = await client.event.subscribe()
+      for await (const event of sub.stream as AsyncIterable<any>) {
+        if (event.type === "session.idle" && event.properties?.sessionID && event.properties.sessionID === sessionID) {
+          push({ type: "result", ok: true })
+          done = true
+          wake()
+          return
+        }
+        const mapped = mapOpencodeEvent(event, sessionID)
+        for (const m of mapped) push(m)
+      }
+    } catch (e: any) {
+      push({ type: "error", message: `SSE stream error: ${e.message}` })
+      done = true
+      wake()
+    }
+  })()
+
+  // Create the session, then fire the prompt. We use promptAsync so we don't block
+  // on completion — the SSE stream's session.idle event is our signal to stop.
+  let session
+  try {
+    const created = await client.session.create({ body: { title: "puzzmo-cli" }, query: { directory: cwd } })
+    session = created.data
+    if (!session?.id) throw new Error("session.create returned no id")
+    sessionID = session.id
+  } catch (e: any) {
+    push({ type: "error", message: `Session creation failed: ${e.message}` })
+    done = true
+    wake()
+  }
+
+  if (sessionID) {
+    client.session
+      .promptAsync({
+        path: { id: sessionID },
+        body: { parts: [{ type: "text", text: input.prompt }] as any },
+        query: { directory: cwd },
+      })
+      .catch((e: Error) => {
+        push({ type: "error", message: `Prompt failed: ${e.message}` })
+        done = true
+        wake()
+      })
+  }
+
+  if (input.signal)
+    input.signal.addEventListener("abort", () => {
+      done = true
+      wake()
+    })
+
+  try {
+    while (true) {
+      if (events.length > 0) {
+        yield events.shift()!
+        continue
+      }
+      if (done) return
+      await new Promise<void>((r) => (waiting = r))
+    }
+  } finally {
+    server.close()
+    await sseTask.catch(() => {})
+  }
+}
+
+const mapOpencodeEvent = (event: any, sessionID: string | null): AgentEvent[] => {
+  if (event.type === "message.part.updated") {
+    const part = event.properties?.part
+    const delta = event.properties?.delta as string | undefined
+    if (!part) return []
+    // Deltas flow inline; complete-snapshot text gets a trailing newline so consecutive messages don't run together.
+    if (part.type === "text") {
+      if (delta != null) return [{ type: "text", text: delta }]
+      const text = part.text ?? ""
+      if (!text) return []
+      return [{ type: "text", text: text.endsWith("\n") ? text : text + "\n" }]
+    }
+    if (part.type === "reasoning") {
+      if (delta != null) return [{ type: "thinking", text: delta }]
+      const text = part.text ?? ""
+      if (!text) return []
+      return [{ type: "thinking", text: text.endsWith("\n") ? text : text + "\n" }]
+    }
+    if (part.type === "tool") {
+      const state = part.state?.status ?? part.state
+      if (state === "completed" || state === "error")
+        return [{ type: "tool_result", ok: state === "completed", summary: summarizeToolPart(part) }]
+      return [{ type: "tool_use", name: part.tool ?? "tool", summary: summarizeToolPart(part) }]
+    }
+    return []
+  }
+  if (event.type === "file.edited") return [{ type: "tool_result", ok: true, summary: `Edited ${event.properties?.file ?? ""}` }]
+  if (event.type === "command.executed") return [{ type: "tool_use", name: "Bash", summary: event.properties?.arguments ?? "" }]
+  if (event.type === "session.error" && (!sessionID || event.properties?.sessionID === sessionID))
+    return [{ type: "error", message: event.properties?.error?.message ?? "session error" }]
+  return []
+}
+
+const summarizeToolPart = (part: any): string => {
+  const input = part.state?.input ?? part.input
+  if (!input || typeof input !== "object") return part.tool ?? ""
+  if (typeof input.command === "string") return input.command.slice(0, 200)
+  if (typeof input.file_path === "string") return input.file_path
+  if (typeof input.path === "string") return input.path
+  if (typeof input.pattern === "string") return input.pattern
+  return part.tool ?? ""
+}

package/src/agents/stream-json-cli.ts

@@ -0,0 +1,86 @@
+import { spawn, type ChildProcess } from "node:child_process"
+
+import type { AgentEvent, RunInput } from "./types.js"
+
+/** Shared driver for any CLI that emits NDJSON over stdout when given a prompt
+ *  in print/headless mode. Used by both the claude and gemini adapters. */
+export type StreamJsonCliConfig = {
+  cmd: string
+  buildArgs: (prompt: string) => string[]
+  /** Map one parsed JSON line to an AgentEvent (or null to drop). */
+  parseLine: (line: string) => AgentEvent | null
+  /** Optional env mutator. Receives a copy of process.env. */
+  env?: (base: NodeJS.ProcessEnv) => NodeJS.ProcessEnv
+}
+
+export const runStreamJsonCli = async function* (config: StreamJsonCliConfig, input: RunInput): AsyncIterable<AgentEvent> {
+  const args = config.buildArgs(input.prompt)
+  const env = config.env ? config.env({ ...process.env }) : { ...process.env }
+
+  let proc: ChildProcess
+  try {
+    proc = spawn(config.cmd, args, {
+      cwd: input.cwd ?? process.cwd(),
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+    })
+  } catch (e: any) {
+    yield { type: "error", message: `Failed to spawn ${config.cmd}: ${e.message}` }
+    return
+  }
+
+  if (input.signal) input.signal.addEventListener("abort", () => proc.kill())
+
+  // Bridge node streams + child events into an async generator.
+  const queue: AgentEvent[] = []
+  let done = false
+  let resolveWaiting: (() => void) | null = null
+  let buf = ""
+  let sawResult = false
+
+  const push = (e: AgentEvent) => {
+    if (e.type === "result") sawResult = true
+    queue.push(e)
+    resolveWaiting?.()
+    resolveWaiting = null
+  }
+
+  const flushLine = (line: string) => {
+    if (!line.trim()) return
+    const event = config.parseLine(line)
+    if (event) push(event)
+  }
+
+  proc.stdout?.on("data", (chunk: Buffer) => {
+    buf += chunk.toString("utf8")
+    const lines = buf.split("\n")
+    buf = lines.pop() ?? ""
+    for (const line of lines) flushLine(line)
+  })
+
+  proc.stderr?.on("data", (chunk: Buffer) => {
+    const text = chunk.toString("utf8").trim()
+    if (text) push({ type: "error", message: text })
+  })
+
+  proc.on("close", (code) => {
+    if (buf.trim()) flushLine(buf)
+    if (code !== 0 && !sawResult) push({ type: "result", ok: false })
+    done = true
+    resolveWaiting?.()
+    resolveWaiting = null
+  })
+
+  proc.on("error", (err) => {
+    push({ type: "error", message: err.message })
+    done = true
+    resolveWaiting?.()
+    resolveWaiting = null
+  })
+
+  while (true) {
+    if (queue.length > 0) yield queue.shift()!
+    else if (done) return
+    else await new Promise<void>((r) => (resolveWaiting = r))
+  }
+}

package/src/agents/types.ts

@@ -0,0 +1,22 @@
+/** Normalized event union emitted by every agent adapter. Keep this small —
+ *  adapters fold their richer native event shapes into one of these. */
+export type AgentEvent =
+  | { type: "text"; text: string } // assistant text (delta or full chunk)
+  | { type: "tool_use"; name: string; summary: string } // tool starting
+  | { type: "tool_result"; ok: boolean; summary: string } // tool finished
+  | { type: "thinking"; text: string }
+  | { type: "system"; text: string }
+  | { type: "result"; ok: boolean; costUSD?: number }
+  | { type: "error"; message: string }
+
+export type RunInput = {
+  prompt: string
+  cwd?: string
+  signal?: AbortSignal
+}
+
+export interface Agent {
+  readonly name: string
+  /** Yield events as the agent runs. Should complete (or throw) when the run finishes. */
+  run(input: RunInput): AsyncIterable<AgentEvent>
+}

package/src/commands/agent-test.ts

@@ -0,0 +1,81 @@
+import fs from "node:fs"
+
+import * as p from "@clack/prompts"
+
+import { agentNames, getAgent } from "../agents/index.js"
+
+const dim = (s: string) => `\x1b[2m${s}\x1b[0m`
+const yellow = (s: string) => `\x1b[33m${s}\x1b[0m`
+const red = (s: string) => `\x1b[31m${s}\x1b[0m`
+const green = (s: string) => `\x1b[32m${s}\x1b[0m`
+
+/** Undocumented: send "say hello world" to a chosen agent through the meta-library
+ *  and stream events to stdout. Use this to verify each adapter end-to-end. */
+export const agentTest = async () => {
+  p.intro("Agent SDK Test")
+
+  const choice = await p.select({
+    message: "Which agent?",
+    options: agentNames().map((name) => ({ value: name, label: name })),
+    initialValue: "claude",
+  })
+  if (p.isCancel(choice)) process.exit(0)
+  const agent = getAgent(String(choice))
+  if (!agent) {
+    p.log.error(`Unknown agent: ${choice}`)
+    process.exit(1)
+  }
+
+  const prompt = "say hello world"
+  const cwd = process.cwd()
+  const debugPath = "/tmp/puzzmo-agent-test.log"
+  fs.writeFileSync(debugPath, "")
+  const log = (msg: string) => fs.appendFileSync(debugPath, `[${new Date().toISOString()}] ${msg}\n`)
+
+  log(`agent=${agent.name} cwd=${cwd}`)
+  log(`prompt=${JSON.stringify(prompt)}`)
+
+  process.stderr.write(`\n${dim("[agent]")} ${agent.name}\n`)
+  process.stderr.write(`${dim("[cwd]")}   ${cwd}\n`)
+  process.stderr.write(`${dim("[log]")}   ${debugPath}\n`)
+  process.stderr.write(`${dim("---- events below (Ctrl+C to abort) ----")}\n\n`)
+
+  const controller = new AbortController()
+  const onSig = () => {
+    process.stderr.write(`\n${dim("[interrupt]")}\n`)
+    controller.abort()
+  }
+  process.on("SIGINT", onSig)
+
+  const start = Date.now()
+  let count = 0
+  try {
+    for await (const event of agent.run({ prompt, cwd, signal: controller.signal })) {
+      count++
+      const elapsed = ((Date.now() - start) / 1000).toFixed(3)
+      log(`+${elapsed}s ${event.type} ${JSON.stringify(event).slice(0, 400)}`)
+      printEvent(event)
+    }
+  } catch (e: any) {
+    process.stderr.write(`\n${red("[run threw]")} ${e.message ?? e}\n`)
+    log(`THROW ${e.message ?? e}`)
+    process.exit(1)
+  } finally {
+    process.off("SIGINT", onSig)
+  }
+
+  const elapsed = ((Date.now() - start) / 1000).toFixed(3)
+  process.stderr.write(`\n${dim(`[+${elapsed}s done]`)} events=${count}\n`)
+  log(`done events=${count} elapsed=${elapsed}s`)
+}
+
+const printEvent = (e: { type: string } & Record<string, any>) => {
+  if (e.type === "text") process.stdout.write(e.text)
+  else if (e.type === "thinking") process.stdout.write(dim(e.text))
+  else if (e.type === "tool_use") process.stdout.write(`\n${yellow(`[${e.name}]`)} ${dim(e.summary ?? "")}\n`)
+  else if (e.type === "tool_result") process.stdout.write(`${e.ok ? green("  ✓") : red("  ✗")} ${dim(e.summary ?? "")}\n`)
+  else if (e.type === "system") process.stdout.write(dim(`\n[${e.text}]\n`))
+  else if (e.type === "result")
+    process.stdout.write(`\n${e.ok ? green("== Done") : red("== Failed")}${e.costUSD ? ` ($${e.costUSD.toFixed(4)})` : ""}\n`)
+  else if (e.type === "error") process.stdout.write(red(`\n[error] ${e.message}\n`))
+}

package/src/commands/game/create.ts

@@ -3,6 +3,7 @@ import path from "node:path"
 import { createRequire } from "node:module"
 import * as p from "@clack/prompts"
 
+import { agentNames } from "../../agents/index.js"
 import { detectAgent } from "../../wizard/agent-detect.js"
 import { downloadPage } from "../../download/page-downloader.js"
 import { runCommand, gitCommit } from "../../util/exec.js"
@@ -260,10 +261,11 @@ export const gameCreate = async (args: string[]) => {
     gameDir = setupRepoGame(tmpDir, slug, repo.repoRoot, parentFolder)
   }
 
-  // Step 7: Detect agent and run skills pipeline
-  const agents = detectAgent()
+  // Step 7: Detect agent and run skills pipeline. Only offer CLIs we have an adapter for.
+  const supported = new Set(agentNames())
+  const agents = detectAgent().filter((a) => supported.has(a.id))
   const agentChoices = [
-    ...agents.map((a) => ({ value: a.binary, label: `${a.displayName} (${a.path})` })),
+    ...agents.map((a) => ({ value: a.id, label: `${a.displayName} (${a.path})` })),
     { value: "none", label: "None - I'll run the steps manually" },
   ]
 
@@ -274,7 +276,7 @@ export const gameCreate = async (args: string[]) => {
     selectedAgent = (await p.select({ message: "Which LLM agent do you use?", options: agentChoices })) as string
     if (p.isCancel(selectedAgent)) process.exit(0)
   } else {
-    p.log.info("No LLM agents detected (checked: claude, codex)")
+    p.log.info(`No supported LLM agents detected (checked: ${agentNames().join(", ")})`)
     selectedAgent = "none"
   }
 

package/src/commands/upload.ts

@@ -7,45 +7,13 @@ import { uploadFiles } from "../util/api.js"
 import { getAPIURL, getToken } from "../util/config.js"
 import { validatePuzzmoJson } from "../util/validatePuzzmoFile.js"
 
-/** Collects all files in a directory recursively */
-const collectFiles = (dir: string): string[] => {
-  const entries = fs.readdirSync(dir, { withFileTypes: true })
-  const files: string[] = []
-  for (const entry of entries) {
-    const full = path.join(dir, entry.name)
-    if (entry.isDirectory()) files.push(...collectFiles(full))
-    else files.push(full)
-  }
-  return files
-}
-
-/** Tries to get the shortest unique git SHA, returns null if not in a git repo */
-const getGitSHA = (): string | null => {
-  try {
-    return execSync("git rev-parse --short HEAD", { encoding: "utf-8" }).trim()
-  } catch {
-    return null
-  }
-}
-
-/** Hashes all file contents to produce a deterministic SHA */
-const hashFiles = (filePaths: string[]): string => {
-  const hash = crypto.createHash("sha256")
-  for (const fp of filePaths.sort()) {
-    hash.update(fs.readFileSync(fp))
-  }
-  return hash.digest("hex").slice(0, 12)
-}
-
-/** Formats a byte count as a human-readable string */
-const formatBytes = (bytes: number): string => {
-  if (bytes < 1024) return `${bytes} B`
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
-  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+type UploadOptions = {
+  verbose?: boolean
 }
 
 /** Uploads game build artifacts to Puzzmo */
-export const upload = async (dir: string) => {
+export const upload = async (dir: string, options: UploadOptions = {}) => {
+  const { verbose = false } = options
   const token = getToken()
   if (!token) {
     console.error("Not logged in. Run `puzzmo login <token>` or set PUZZMO_TOKEN.")
@@ -111,10 +79,56 @@ export const upload = async (dir: string) => {
   if (apiURL !== defaultURL) console.log(`Uploading to ${apiURL}...`)
   else console.log("Uploading...")
 
-  const result = await uploadFiles(token, gameSlug, sha, files, distDir, puzzmoFile, (batch, totalBatches, uploaded) => {
-    console.log(`  Batch ${batch}/${totalBatches} done (${uploaded} file(s) uploaded)`)
-  })
+  const result = await uploadFiles(
+    token,
+    gameSlug,
+    sha,
+    files,
+    distDir,
+    puzzmoFile,
+    (batch, totalBatches, uploaded) => {
+      console.log(`  Batch ${batch}/${totalBatches} done (${uploaded} file(s) uploaded)`)
+    },
+    { verbose },
+  )
 
   console.log(`\nDone - ${result.versionID}`)
   console.log(`Assets: ${result.assetsBase}`)
 }
+
+/** Collects all files in a directory recursively */
+const collectFiles = (dir: string): string[] => {
+  const entries = fs.readdirSync(dir, { withFileTypes: true })
+  const files: string[] = []
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) files.push(...collectFiles(full))
+    else files.push(full)
+  }
+  return files
+}
+
+/** Tries to get the shortest unique git SHA, returns null if not in a git repo */
+const getGitSHA = (): string | null => {
+  try {
+    return execSync("git rev-parse --short HEAD", { encoding: "utf-8" }).trim()
+  } catch {
+    return null
+  }
+}
+
+/** Hashes all file contents to produce a deterministic SHA */
+const hashFiles = (filePaths: string[]): string => {
+  const hash = crypto.createHash("sha256")
+  for (const fp of filePaths.sort()) {
+    hash.update(fs.readFileSync(fp))
+  }
+  return hash.digest("hex").slice(0, 12)
+}
+
+/** Formats a byte count as a human-readable string */
+const formatBytes = (bytes: number): string => {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { agentTest } from "./commands/agent-test.js"
 import { login } from "./commands/login.js"
 import { upload } from "./commands/upload.js"
 import { validate } from "./commands/validate.js"
@@ -13,7 +14,7 @@ const printUsage = () => {
   puzzmo login <token>            Save a CLI auth token
   puzzmo game create [token]      Create a new Puzzmo game project
 
-  puzzmo upload <dir>             Upload game build from <dir> (slug from puzzmo.json)
+  puzzmo upload <dir> [-v]        Upload game build from <dir> (slug from puzzmo.json). -v/--verbose prints request URLs and full error bodies.
   puzzmo validate [dir]           Validate puzzmo.json in a directory (default: .)
   puzzmo migrate                  List and select migration skills from dev.puzzmo.com`)
 }
@@ -30,12 +31,13 @@ const run = async () => {
       break
     }
     case "upload": {
-      const dir = args[0]
+      const verbose = args.includes("--verbose") || args.includes("-v")
+      const dir = args.find((a) => !a.startsWith("-"))
       if (!dir) {
-        console.error("Usage: puzzmo upload <dir>")
+        console.error("Usage: puzzmo upload <dir> [-v|--verbose]")
         process.exit(1)
       }
-      await upload(dir)
+      await upload(dir, { verbose })
       break
     }
     case "game": {
@@ -56,6 +58,10 @@ const run = async () => {
       await migrate()
       break
     }
+    case "agent-test": {
+      await agentTest()
+      break
+    }
     default:
       printUsage()
       break