lecodes-cli 0.20.2 → 1.0.0

package/src/platform/api.ts

@@ -0,0 +1,302 @@
+import { CliError } from "../cli"
+
+/* 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 → platform/browserAuth.ts}

@@ -3,7 +3,7 @@ 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"
+import { CliError, c, info, log } from "../cli"
 
 /*
  * Browser login (loopback OAuth-style flow, like `vercel`/`gh`):

package/src/{config.ts → platform/config.ts}

@@ -1,7 +1,7 @@
 import { homedir } from "node:os"
 import { join } from "node:path"
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs"
-import { CliError } from "./util"
+import { CliError } from "../cli"
 
 /* Global CLI config in ~/.lecodes/config.json: the server URL + the personal access token.
  * Env vars LECODES_API / LECODES_TOKEN override the stored values (handy for CI). */

package/src/{serverDiff.ts → platform/serverDiff.ts}

@@ -1,8 +1,8 @@
 import { readFileSync } from "node:fs"
 import type { Project, ProjectAsset } from "./api"
-import type { LocalScan } from "./localFiles"
-import { classifyKind, isTextKind } from "./localFiles"
-import { buildPaths } from "./project"
+import type { LocalScan } from "../project/localFiles"
+import { classifyKind, isTextKind } from "../project/localFiles"
+import { buildPaths } from "../project/materialize"
 import { basename } from "node:path"
 
 /*

package/src/{projectEnv.ts → project/env.ts}

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs"
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs"
 import { homedir } from "node:os"
 import { dirname, join, resolve } from "node:path"
 
@@ -57,7 +57,12 @@ export const applyDotEnv = (
 ): Record<string, string> => {
   const out: Record<string, string> = {}
   for (const [key, raw] of Object.entries(parsed)) {
-    if (!KEY_RE.test(key) || env[key] !== undefined) continue
+    if (!KEY_RE.test(key)) continue
+    // Bun auto-loads the cwd's .env into process.env before any code runs, so a project's own
+    // keys arrive here already set — to their RAW text, `./` paths unresolved. That is not the
+    // shell overriding the file, it is the same file seen twice: apply the resolution. A shell
+    // value that differs from the file's text is a real override and stays.
+    if (env[key] !== undefined && env[key] !== raw) continue
     let value = raw
     if (value.startsWith("./") || value.startsWith("../")) value = resolve(dir, value)
     else if (value === "~" || value.startsWith("~/")) value = join(homedir(), value.slice(1))
@@ -96,3 +101,29 @@ export const loadProjectEnv = (cwd = process.cwd()): string[] => {
     return []
   }
 }
+
+/** Set keys in `<root>/.env` — an existing `KEY=` line is REPLACED (rotating a secret must not
+ *  leave two live lines), a new one is appended, other lines are kept verbatim — and make sure
+ *  git can't swallow the file (`.env` in .gitignore). Returns the paths touched, root-relative.
+ *  Values are written raw: quote them yourself if they carry spaces or `#`. */
+export const upsertDotEnv = (root: string, entries: Record<string, string>): string[] => {
+  const touched: string[] = []
+  const envPath = join(root, ".env")
+  let content = existsSync(envPath) ? readFileSync(envPath, "utf8") : ""
+  for (const [key, value] of Object.entries(entries)) {
+    const line = `${key}=${value}`
+    const re = new RegExp(`^(?:export\\s+)?${key}\\s*=.*$`, "m")
+    if (re.test(content)) content = content.replace(re, line)
+    else content = content + (!content || content.endsWith("\n") ? "" : "\n") + line + "\n"
+  }
+  writeFileSync(envPath, content)
+  touched.push(".env")
+
+  const ignorePath = join(root, ".gitignore")
+  const ignore = existsSync(ignorePath) ? readFileSync(ignorePath, "utf8") : ""
+  if (!ignore.split("\n").some(l => l.trim() === ".env")) {
+    appendFileSync(ignorePath, `${!ignore || ignore.endsWith("\n") ? "" : "\n"}.env\n`)
+    touched.push(".gitignore")
+  }
+  return touched
+}

package/src/{localFiles.ts → project/localFiles.ts}

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs"
 import { join, relative } from "node:path"
 import { sanitizeAssetName } from "lecodes-sdk/compile/assetName"
-import { sha256, toKey } from "./util"
+import { sha256, toKey } from "./paths"
 import { loadIgnore, type IgnoreMatcher } from "./ignore"
 import type { FileKind, Manifest } from "./manifest"
 

package/src/{manifest.ts → project/manifest.ts}

@@ -1,6 +1,6 @@
 import { dirname, join } from "node:path"
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs"
-import { CliError } from "./util"
+import { CliError } from "../cli"
 
 /* The per-checkout state in <root>/.lecodes/manifest.json: which remote project this is, the
  * head we last synced from (for drift detection), and a path -> { id, type, sha } map used to

package/src/{project.ts → project/materialize.ts}

@@ -1,8 +1,8 @@
 import { dirname, join } from "node:path"
 import { mkdirSync, writeFileSync } from "node:fs"
-import { downloadBlob, type Project, type ProjectAsset } from "./api"
+import { downloadBlob, type Project, type ProjectAsset } from "../platform/api"
 import type { FileKind, ManifestFile } from "./manifest"
-import { sha256 } from "./util"
+import { sha256 } from "./paths"
 
 /* Writes a project's asset tree to disk and returns the path -> { id, type, sha } map for the
  * manifest. Shared by clone and pull. */

package/src/project/paths.ts

@@ -0,0 +1,20 @@
+import { createHash } from "node:crypto"
+import { sanitizeAssetName } from "lecodes-sdk/compile/assetName"
+import { CliError } from "../cli/errors"
+
+/* How a project file is addressed: the same posix key on every platform, and the hash the
+ * manifest stores per file. */
+
+export const sha256 = (data: string | Uint8Array): string => createHash("sha256").update(data).digest("hex")
+
+/** Normalize any path to a leading-slash, forward-slash, "." / ".." free key (e.g. "/a/b.ts").
+ *  Each segment gets the platform's canonical spelling (sdk/compile/assetName) — macOS hands out
+ *  decomposed names ("й" as и + U+0306) from readdir, which would otherwise key a file differently
+ *  than the same name typed in an import or stored on the server. */
+export const toKey = (path: string): string => {
+  const parts = path.replace(/\\/g, "/").split("/").map(p => p.trim()).filter(p => p && p !== ".")
+  if (parts.some(p => p === "..")) throw new CliError(`Unsafe path: ${path}`)
+  const names = parts.map(p => sanitizeAssetName(p))
+  if (names.some(name => !name)) throw new CliError(`Wrong path: ${path}`)
+  return "/" + names.join("/")
+}

package/src/{textDiff.ts → project/textDiff.ts}

@@ -1,4 +1,4 @@
-import { c } from "./util"
+import { c } from "../cli"
 
 /* A small line-level unified diff (LCS-based) for `lecodes diff`. Good enough for source files;
  * for very large inputs it bails out to a one-line summary to avoid O(n·m) blow-up. */