lecodes-cli 0.19.0 → 0.19.2

package/src/api.ts

@@ -0,0 +1,302 @@
+import { CliError } from "./util"
+
+/* Thin client over the backend HTTP API. All project/account calls go through `${apiUrl}/api/...`;
+ * blob downloads hit `${apiUrl}<src>` (the public /uploads/* route). Mirrors the contract the
+ * frontend uses (see packages/frontend/src/api). */
+
+export type ProjectAsset = {
+  id: number
+  name: string
+  type: "folder" | "file" | "text" | "shader" | "scene"
+  parentId: number | null
+  meta?: Record<string, unknown> | null
+  text?: string | null
+  file?: { src: string, previewSrc?: string | null, size?: number } | null
+  shaders?: { platform: string, src: string }[]
+}
+
+export type Project = {
+  uuid: string
+  name: string
+  role: "owner" | "developer" | "viewer"
+  assets: ProjectAsset[]
+}
+
+export type CommitsResponse = { dirty: boolean, headId: number | null }
+
+export type SyncFileInput = {
+  path: string
+  assetId?: number
+  type: "text" | "shader" | "scene" | "resource"
+  text?: string | null
+  blobFileId?: number | null
+}
+export type SyncFolderInput = { path: string }
+export type SyncResponse = {
+  created: boolean
+  headId: number
+  seq?: number
+  nodes: { id: number, path: string, type: string, versionId: number | null }[]
+  /** Set when the push requested `publish` — whether the deploy (compile → live) succeeded. */
+  published?: boolean
+  /** A human-readable reason when `publish` was requested but the deploy failed (push still landed). */
+  publishError?: string
+}
+
+const errorMessage = (body: unknown, status: number): string => {
+  if (typeof body === "string" && body) return body
+  if (body && typeof body === "object") {
+    const b = body as Record<string, unknown>
+    if (typeof b.error === "string") return b.error
+    if (b.error && typeof b.error === "object") {
+      const first = Object.values(b.error)[0] as unknown
+      if (typeof first === "string") return first
+      if (first && typeof first === "object" && typeof (first as { message?: unknown }).message === "string") {
+        return (first as { message: string }).message
+      }
+    }
+    if (typeof b.message === "string") return b.message
+  }
+  return `Request failed with status ${status}`
+}
+
+type RequestOptions = { method?: string, body?: unknown, token?: string }
+
+export const apiRequest = async <T = unknown>(apiUrl: string, path: string, opts: RequestOptions = {}): Promise<T> => {
+  const headers: Record<string, string> = {}
+  const isForm = opts.body instanceof FormData
+  if (opts.token) headers["Authorization"] = "Bearer " + opts.token
+  if (opts.body !== undefined && !isForm) headers["Content-Type"] = "application/json"
+
+  let resp: Response
+  try {
+    resp = await fetch(`${apiUrl}/api${path}`, {
+      method: opts.method ?? (opts.body !== undefined ? "POST" : "GET"),
+      headers,
+      body: opts.body === undefined ? undefined : isForm ? (opts.body as FormData) : JSON.stringify(opts.body),
+    })
+  } catch (e) {
+    throw new CliError(`Cannot reach ${apiUrl} — is the server URL correct and online?`)
+  }
+
+  const contentType = resp.headers.get("content-type") ?? ""
+  const parsed: unknown = contentType.startsWith("application/json") ? await resp.json()
+    : contentType.startsWith("text/") ? await resp.text()
+    : null
+
+  if (resp.status >= 400) throw new CliError(errorMessage(parsed, resp.status), resp.status)
+  return parsed as T
+}
+
+export const login = (apiUrl: string, login: string, password: string) =>
+  apiRequest<{ accessToken: string, refreshToken: string }>(apiUrl, "/account/login", { body: { login, password } })
+
+export const createAccessToken = (apiUrl: string, jwt: string, name: string) =>
+  apiRequest<{ id: number, name: string, prefix: string, token: string }>(apiUrl, "/account/tokens", { token: jwt, body: { name } })
+
+export const getAccount = (apiUrl: string, token: string) =>
+  apiRequest<{ id: number, name: string, email: string }>(apiUrl, "/account", { token })
+
+export const getProject = (apiUrl: string, token: string, uuid: string) =>
+  apiRequest<Project>(apiUrl, `/projects/${uuid}`, { token })
+
+/** Create a new (empty) project on the server. Returns its uuid. */
+export const createProject = (apiUrl: string, token: string, name: string, teamUuid?: string) =>
+  apiRequest<{ uuid: string }>(apiUrl, "/projects", { token, body: { name, teamUuid } })
+
+export const getCommits = (apiUrl: string, token: string, uuid: string) =>
+  apiRequest<CommitsResponse>(apiUrl, `/projects/${uuid}/commits`, { token })
+
+export const getTypes = (apiUrl: string) =>
+  apiRequest<Record<string, string>>(apiUrl, "/types")
+
+export const uploadBlob = (apiUrl: string, token: string, uuid: string, name: string, bytes: Uint8Array) => {
+  const form = new FormData()
+  // Cast is type-only (TS 5.7 typed-array generics vs the Blob signature); Blob accepts a Uint8Array.
+  form.append("file", new Blob([bytes as unknown as ArrayBuffer]), name)
+  return apiRequest<{ id: number, src: string, size: number }>(apiUrl, `/projects/${uuid}/blobs`, { token, body: form })
+}
+
+export const sync = (apiUrl: string, token: string, uuid: string, payload: { message: string, files: SyncFileInput[], folders: SyncFolderInput[], publish?: boolean }) =>
+  apiRequest<SyncResponse>(apiUrl, `/projects/${uuid}/sync`, { token, body: payload })
+
+/** Deploy the project's current server state (compile → live bundle). Used by `push --publish` when
+ *  there are no file changes to sync. */
+export const publishProject = (apiUrl: string, token: string, uuid: string) =>
+  apiRequest<{ published: boolean, size: number }>(apiUrl, `/projects/${uuid}/publish`, { token, body: {} })
+
+export type DesignShare = {
+  token: string | null
+  url: string | null
+  /** Whether share-link visitors may WRITE comments (reading is never gated on it). */
+  commentsOpen?: boolean
+}
+
+/** Current public share-link state for a project's design board. */
+export const getDesignShare = (apiUrl: string, token: string, uuid: string) =>
+  apiRequest<DesignShare>(apiUrl, `/projects/${uuid}/design/share`, { token })
+
+/** Enable the design share link (idempotent). */
+export const enableDesignShare = (apiUrl: string, token: string, uuid: string) =>
+  apiRequest<DesignShare>(apiUrl, `/projects/${uuid}/design/share`, { token, body: {} })
+
+/** Revoke the design share link. */
+export const disableDesignShare = (apiUrl: string, token: string, uuid: string) =>
+  apiRequest<DesignShare>(apiUrl, `/projects/${uuid}/design/share`, { token, method: "DELETE" })
+
+/** Let / stop share-link visitors WRITING comments. Reading the existing conversation is unaffected,
+ *  so switching this off never hides feedback that already arrived. */
+export const setDesignCommentsOpen = (apiUrl: string, token: string, uuid: string, open: boolean) =>
+  apiRequest<{ commentsOpen: boolean }>(apiUrl, `/projects/${uuid}/design/comments/open`, { token, body: { open } })
+
+/* ---- Design-board comments (docs/design-comments-plan.md) ---------------------------------
+ * The platform is the source of truth; `design/comments/` (one file per thread) is the mirror the
+ * running `lecodes design` sync — or `comments pull` — fills. The shapes below are the same
+ * document the design package's core defines —
+ * spelled out here, like every other DTO in this file, because `lecodes-design` is an optional
+ * peer the CLI must typecheck and run without. */
+
+export type CommentAnchor = {
+  screen?: string
+  state?: string
+  element?: string
+  point?: [number, number]
+  world?: [number, number]
+}
+export type CommentMessage = {
+  id: string
+  author: string
+  /** Provenance: `share` = unverified stranger on the link, `ai` = Claude on a member's behalf. */
+  origin: "share" | "editor" | "cli" | "ai"
+  at: string
+  body: string
+  editedAt?: string
+  mine?: boolean
+}
+export type CommentThread = {
+  id: string
+  number: number
+  anchor: CommentAnchor
+  resolved: boolean
+  resolvedAt?: string | null
+  createdAt: string
+  updatedAt: string
+  commitId?: number | null
+  messages: CommentMessage[]
+  mine?: boolean
+}
+
+export type DesignCommentsSnapshot = {
+  threads: CommentThread[]
+  cursor: string | null
+  canComment: boolean
+  shared?: boolean
+  commentsOpen?: boolean
+  /** The project's thread-number allocator, so a pull can't hand out a used number. */
+  nextNumber?: number
+}
+
+export const listDesignComments = (apiUrl: string, token: string, uuid: string) =>
+  apiRequest<DesignCommentsSnapshot>(apiUrl, `/projects/${uuid}/design/comments`, { token })
+
+/** `origin` is provenance, carried up so a reply Claude wrote doesn't reach the reviewer looking
+ *  like one the developer typed. The account is the identity either way; the server rejects any
+ *  value but `cli` / `ai` / `editor`. */
+export const createDesignComment = (
+  apiUrl: string, token: string, uuid: string,
+  input: { anchor: CommentAnchor, body: string, origin?: CommentMessage["origin"] },
+) => apiRequest<CommentThread>(apiUrl, `/projects/${uuid}/design/comments`, { token, body: input })
+
+export const replyDesignComment = (
+  apiUrl: string, token: string, uuid: string, threadId: string, body: string,
+  origin?: CommentMessage["origin"],
+) => apiRequest<CommentThread>(
+  apiUrl, `/projects/${uuid}/design/comments/${threadId}/messages`, { token, body: { body, origin } })
+
+export const resolveDesignComment = (apiUrl: string, token: string, uuid: string, threadId: string, resolved: boolean) =>
+  apiRequest<CommentThread>(apiUrl, `/projects/${uuid}/design/comments/${threadId}`, { token, method: "PATCH", body: { resolved } })
+
+export const deleteDesignComment = (apiUrl: string, token: string, uuid: string, threadId: string) =>
+  apiRequest<{ ok: boolean }>(apiUrl, `/projects/${uuid}/design/comments/${threadId}`, { token, method: "DELETE" })
+
+/** Re-anchor a pin. The anchor goes up whole — `element` is replaced, never merged, or a stale name
+ *  silently re-anchors the pin to whatever else still answers to it. */
+export const moveDesignComment = (
+  apiUrl: string, token: string, uuid: string, threadId: string, anchor: CommentAnchor,
+) => apiRequest<CommentThread>(apiUrl, `/projects/${uuid}/design/comments/${threadId}`, {
+  token,
+  method: "PATCH",
+  body: { screen: anchor.screen, state: anchor.state, element: anchor.element, point: anchor.point },
+})
+
+export const editDesignCommentMessage = (
+  apiUrl: string, token: string, uuid: string, threadId: string, messageId: string, body: string,
+) => apiRequest<CommentThread>(
+  apiUrl, `/projects/${uuid}/design/comments/${threadId}/messages/${messageId}`, { token, method: "PATCH", body: { body } })
+
+export const deleteDesignCommentMessage = (
+  apiUrl: string, token: string, uuid: string, threadId: string, messageId: string,
+) => apiRequest<{ threadRemoved: boolean }>(
+  apiUrl, `/projects/${uuid}/design/comments/${threadId}/messages/${messageId}`, { token, method: "DELETE" })
+
+/* ---- Push notifications (`lecodes pn`, docs/push-plan.md) ---------------------------------
+ * Every call here authenticates with the stored PAT: /push/send accepts a developer-role user
+ * token exactly like a project push key, so test sends need no key at all. Keys are minted for
+ * ONE purpose — the developer's own production server — and only an owner can manage them. */
+
+export type PushSendPayload = {
+  to?: string[]
+  users?: string[]
+  title: string
+  body?: string
+  url?: string
+  data?: Record<string, unknown>
+  badge?: number
+}
+export type PushSendResult = { sent: number, failed: { address: string, reason: string }[] }
+
+export type PushDevice = {
+  address: string
+  platform: "apns" | "fcm" | "webpush"
+  environment: "production" | "sandbox"
+  hostApp: string
+  user: string | null
+  createdAt: string
+  lastSeenAt: string
+  disabledAt: string | null
+}
+
+export type PushKey = {
+  id: number
+  name: string
+  prefix: string
+  createdAt: string
+  lastUsedAt: string | null
+}
+/** Only the mint response carries `key` — the plaintext exists in this one response and nowhere else. */
+export type CreatedPushKey = PushKey & { key: string }
+
+export const sendPush = (apiUrl: string, token: string, uuid: string, payload: PushSendPayload) =>
+  apiRequest<PushSendResult>(apiUrl, `/projects/${uuid}/push/send`, { token, body: payload })
+
+export const listPushDevices = (apiUrl: string, token: string, uuid: string, user?: string) =>
+  apiRequest<{ devices: PushDevice[], truncated: boolean }>(
+    apiUrl, `/projects/${uuid}/push/registrations${user ? `?user=${encodeURIComponent(user)}` : ""}`, { token })
+
+export const forgetPushDevice = (apiUrl: string, token: string, uuid: string, address: string) =>
+  apiRequest<void>(apiUrl, `/projects/${uuid}/push/registrations/${encodeURIComponent(address)}`, { token, method: "DELETE" })
+
+export const listPushKeys = (apiUrl: string, token: string, uuid: string) =>
+  apiRequest<PushKey[]>(apiUrl, `/projects/${uuid}/push/keys`, { token })
+
+export const createPushKey = (apiUrl: string, token: string, uuid: string, name?: string) =>
+  apiRequest<CreatedPushKey>(apiUrl, `/projects/${uuid}/push/keys`, { token, body: { name } })
+
+export const revokePushKey = (apiUrl: string, token: string, uuid: string, id: number) =>
+  apiRequest<void>(apiUrl, `/projects/${uuid}/push/keys/${id}`, { token, method: "DELETE" })
+
+export const downloadBlob = async (apiUrl: string, src: string): Promise<Uint8Array> => {
+  const resp = await fetch(`${apiUrl}${src}`)
+  if (!resp.ok) throw new CliError(`Failed to download ${src} (status ${resp.status})`)
+  return new Uint8Array(await resp.arrayBuffer())
+}

package/src/browserAuth.ts

@@ -0,0 +1,87 @@
+import { createServer } from "node:http"
+import type { AddressInfo } from "node:net"
+import { spawn } from "node:child_process"
+import { randomBytes } from "node:crypto"
+import { hostname } from "node:os"
+import { CliError, c, info, log } from "./util"
+
+/*
+ * Browser login (loopback OAuth-style flow, like `vercel`/`gh`):
+ *   1. start a one-shot HTTP listener on 127.0.0.1:<random port>
+ *   2. open the browser to <web>/app/cli-auth?port&state&name
+ *   3. the web page (user already signed in) mints a personal access token and redirects it back
+ *      to the local listener, which captures it and shows a success page.
+ * `state` is a random nonce echoed back to prevent another local page from injecting a token.
+ */
+
+const SUCCESS_HTML = `<!doctype html><meta charset="utf-8"><title>lecodes</title>
+<body style="font-family:system-ui,sans-serif;background:#0f1115;color:#e6e6e6;display:grid;place-items:center;height:100vh;margin:0">
+<div style="text-align:center;max-width:420px;padding:32px">
+<h1 style="font-size:20px;margin:0 0 8px">&#10003; Authorized</h1>
+<p style="color:#9aa0aa;margin:0;font-size:14px">You can close this tab and return to your terminal.</p></div>`
+
+const errorHtml = (msg: string) => `<!doctype html><meta charset="utf-8"><title>lecodes</title>
+<body style="font-family:system-ui,sans-serif;background:#0f1115;color:#e6e6e6;display:grid;place-items:center;height:100vh;margin:0">
+<div style="text-align:center;max-width:420px;padding:32px">
+<h1 style="font-size:20px;margin:0 0 8px">Authorization failed</h1>
+<p style="color:#9aa0aa;margin:0;font-size:14px">${msg}</p></div>`
+
+/** Open a URL in the default browser (best-effort; the URL is also printed as a fallback). */
+export const openBrowser = (url: string) => {
+  let cmd: string
+  let args: string[]
+  if (process.platform === "win32") { cmd = "rundll32"; args = [ "url.dll,FileProtocolHandler", url ] }
+  else if (process.platform === "darwin") { cmd = "open"; args = [ url ] }
+  else { cmd = "xdg-open"; args = [ url ] }
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true })
+    child.on("error", () => {})
+    child.unref()
+  } catch { /* fall back to the printed URL */ }
+}
+
+/** Run the browser login flow against `webBase` (the app origin) and resolve the access token. */
+export const browserLogin = async (
+  webBase: string, timeoutMs = 5 * 60 * 1000, open: (url: string) => void = openBrowser,
+): Promise<string> => {
+  const state = randomBytes(16).toString("hex")
+
+  let resolve!: (token: string) => void
+  let reject!: (err: Error) => void
+  const tokenPromise = new Promise<string>((res, rej) => { resolve = res; reject = rej })
+
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? "/", "http://127.0.0.1")
+    if (url.pathname !== "/") { res.writeHead(404); res.end(); return }
+    const token = url.searchParams.get("token")
+    if (!token || url.searchParams.get("state") !== state) {
+      res.writeHead(400, { "content-type": "text/html" })
+      res.end(errorHtml("Invalid or expired authorization."))
+      return
+    }
+    res.writeHead(200, { "content-type": "text/html" })
+    res.end(SUCCESS_HTML)
+    resolve(token)
+  })
+
+  await new Promise<void>((res, rej) => {
+    server.once("error", rej)
+    server.listen(0, "127.0.0.1", res)
+  })
+  const port = (server.address() as AddressInfo).port
+
+  const timer = setTimeout(() => reject(new CliError("Timed out waiting for browser authorization.")), timeoutMs)
+
+  const authUrl = `${webBase}/app/cli-auth?port=${port}&state=${state}&name=${encodeURIComponent(hostname())}`
+  info("Opening your browser to authorize the CLI…")
+  log(c.dim("  " + authUrl))
+  log(c.dim("  (waiting — finish in the browser, or press Ctrl+C to cancel)"))
+  open(authUrl)
+
+  try {
+    return await tokenPromise
+  } finally {
+    clearTimeout(timer)
+    server.close()
+  }
+}

package/src/cmgenTool.ts

@@ -0,0 +1,104 @@
+import { existsSync, readdirSync } from "node:fs"
+import { homedir } from "node:os"
+import { join, resolve } from "node:path"
+import { downloadReleaseArchive, fetchReleaseProduct, semverNewer, type ManifestVersion } from "./releases"
+import { CliError, note } from "./util"
+
+/*
+ * Filament's cmgen (environment tool) — the tool behind `lecodes assets sky`, which turns an
+ * equirectangular .exr/.hdr into the two cubemaps a scene needs: the sharp one that gets DRAWN as
+ * the sky, and the roughness-prefiltered one (+ spherical harmonics) that LIGHTS it.
+ *
+ * The binary is NOT shipped with the CLI (most projects never bake an environment). It downloads on
+ * first use from the same S3 release bucket as the desktop renderer and matc (product "cmgen" in
+ * releases/versions.json — published by scripts/release/release-windows.ps1 from the desktop
+ * build's in-tree filament host tools, so the KTX it writes always matches the engine the hosts
+ * ship). Cache: ~/.lecodes/cmgen/cmgen-<version>/. LECODES_CMGEN overrides resolution entirely
+ * (local dev: packages/desktop/build/creator-gl/filament/tools/cmgen/cmgen.exe).
+ *
+ * The CLI resolves it and hands the path to lecodes-assets through LECODES_CMGEN, so that package
+ * stays network-free and still works standalone against a local build.
+ *
+ * No version pin, same reasoning as matc: the KTX1 layout is tied to the vendored Filament and
+ * changes rarely, so resolution takes the newest cached copy, else downloads `latest`.
+ */
+
+const exeName = () => (process.platform === "win32" ? "cmgen.exe" : "cmgen")
+
+const platformKey = (): string => {
+  if (process.platform === "win32") return "windows-x64"
+  if (process.platform === "linux") return "linux-x64"
+  throw new CliError(
+    process.platform === "darwin"
+      ? "cmgen isn't published for macOS yet — build filament's host tools locally and set LECODES_CMGEN."
+      : `cmgen isn't published for ${process.platform}.`,
+  )
+}
+
+const cacheRoot = () => join(homedir(), ".lecodes", "cmgen")
+
+/** Locate the cmgen binary inside a cache/stage dir (the archive may or may not nest a folder). */
+const findCmgenIn = (dir: string): string | null => {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, entry.name)
+    if (entry.isFile() && entry.name === exeName()) return p
+    if (entry.isDirectory()) { const found = findCmgenIn(p); if (found) return found }
+  }
+  return null
+}
+
+/** Versions with a working cmgen binary in the cache, newest first. */
+export const installedCmgenVersions = (): string[] => {
+  try {
+    return readdirSync(cacheRoot(), { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name.startsWith("cmgen-"))
+      .map((e) => e.name.slice("cmgen-".length))
+      .filter((v) => findCmgenIn(join(cacheRoot(), `cmgen-${v}`)) !== null)
+      .sort(semverNewer)
+  } catch {
+    return []
+  }
+}
+
+export const fetchCmgenManifest = (): Promise<{ latest: string, versions: ManifestVersion[] }> =>
+  fetchReleaseProduct("cmgen", "cmgen (environment tool)")
+
+const downloadCmgen = async (version: string, versions: ManifestVersion[], dest: string): Promise<void> => {
+  const key = platformKey()
+  const file = versions.find((v) => v.version === version)?.files[key]
+  if (!file) {
+    throw new CliError(
+      `cmgen ${version} [${key}] isn't published — build filament's host tools locally and point ` +
+      `LECODES_CMGEN at the binary.`,
+    )
+  }
+  note(`Downloading the environment tool (cmgen ${version}, ${(file.size / 1024 / 1024).toFixed(1)} MB)…`)
+  await downloadReleaseArchive(file, {
+    cacheRoot: cacheRoot(),
+    dest,
+    validate: (dir) => (findCmgenIn(dir) ? null : "The downloaded archive doesn't contain the cmgen binary."),
+  })
+}
+
+/** The cmgen binary WITHOUT touching the network: LECODES_CMGEN → newest cached version → null. */
+export const resolveCmgenExeCached = (): string | null => {
+  const override = process.env.LECODES_CMGEN
+  if (override) {
+    if (!existsSync(override)) throw new CliError(`LECODES_CMGEN points at "${override}" which doesn't exist.`)
+    return resolve(override)
+  }
+  const cached = installedCmgenVersions()[0]
+  return cached ? findCmgenIn(join(cacheRoot(), `cmgen-${cached}`)) : null
+}
+
+/** The cmgen binary: LECODES_CMGEN → newest cached version → download the latest release. */
+export const resolveCmgenExe = async (): Promise<string> => {
+  const cached = resolveCmgenExeCached()
+  if (cached) return cached
+  const { latest, versions } = await fetchCmgenManifest()
+  const dir = join(cacheRoot(), `cmgen-${latest}`)
+  await downloadCmgen(latest, versions, dir)
+  const exe = findCmgenIn(dir)
+  if (!exe) throw new CliError(`cmgen cache at ${dir} is broken — delete the folder and retry.`)
+  return exe
+}