lecodes-cli 2.2.11 → 2.2.14

package/src/commands/releases.ts

@@ -0,0 +1,168 @@
+import { existsSync, readFileSync } from "node:fs"
+import { resolve } from "node:path"
+import { CliError, UsageError, bool, c, confirm, defineCommand, info, log, relativeTime, str, success, table, warn } from "../cli"
+import { SchemaChangeError, listReleases, uploadReleaseBundle, useRelease } from "../platform/api"
+import { diffLocal, hasChanges, scanProject } from "../project/localFiles"
+import { runPush } from "./push"
+import { linkedProject } from "./shared"
+
+/*
+ * `lecodes releases` — the project's releases (docs/plans/publishing-plan.md): every publish is an
+ * immutable release with an auto-bumped version, one of them is CURRENT (what
+ * `https://<handle>.le.codes`, the viewers and the store run). `releases use <version>` makes
+ * another one current — a rollback, without a compile. `releases upload <app.js>` makes a release
+ * of a bundle compiled HERE — for an SDK the platform's build service no longer compiles with.
+ *
+ * What `publish`, `push --publish` and `releases use` share lives here too: the result line and
+ * the confirmation of a schema change that deletes production data.
+ */
+
+/** `1.2.4` vs `1.2.10`, numerically per part (the platform bumps the patch on every publish). */
+export const compareVersions = (a: string, b: string): number => {
+  const pa = a.split("."), pb = b.split(".")
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (parseInt(pa[i] ?? "0", 10) || 0) - (parseInt(pb[i] ?? "0", 10) || 0)
+    if (d) return d
+  }
+  return 0
+}
+
+export const formatSize = (bytes: number): string =>
+  bytes < 1024 ? `${bytes} B` : bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)} KB` : `${(bytes / 1024 / 1024).toFixed(1)} MB`
+
+/** The platform's page for a phone: open in the app, or the QR of itself on a desktop. It is the
+ *  le.codes one whether or not the project has its web version on. */
+export const qrUrl = (apiUrl: string, uuid: string): string => `${apiUrl}/qr/${uuid}`
+
+/** `✓ Published 1.2.4 · https://nt0qnjn9.le.codes · 1.1 MB · SDK 2.2.11` and the QR page under it;
+ *  a publish the platform answered `unchanged` (the head is the live release already, none made):
+ *  `✓ Nothing changed — 1.2.4 is current · https://nt0qnjn9.le.codes`. */
+export const reportRelease = (
+  release: { version: string, url: string, size?: number, sdk?: string, unchanged?: boolean },
+  qr: string,
+  verb: "Published" | "Rolled back to" | "Uploaded" = "Published",
+): void => {
+  const parts = [release.unchanged ? `Nothing changed — ${release.version} is current` : `${verb} ${release.version}`, release.url.replace(/\/+$/, "")]
+  if (!release.unchanged) {
+    if (typeof release.size === "number") parts.push(formatSize(release.size))
+    if (release.sdk) parts.push(`SDK ${release.sdk}`)
+  }
+  success(parts.join(" · "))
+  info(`  ${c.dim("QR")} ${qr}`)
+}
+
+/**
+ * A release call, sent first WITHOUT `allowDestructive`. When the prod database refuses the schema
+ * because applying it deletes data, the ops are shown and the call goes again with it — at once
+ * under `--allow-destructive`, after a y/N in a terminal, never without one (the error names the
+ * flag). A schema that cannot migrate at all is a plain error. null = the developer said no.
+ */
+export const withSchemaConfirm = async <T>(
+  call: (allowDestructive: boolean) => Promise<T>,
+  opts: { allowDestructive: boolean, retry: string },
+): Promise<T | null> => {
+  try {
+    return await call(false)
+  } catch (e) {
+    if (!(e instanceof SchemaChangeError)) throw e
+    if (e.incompatible !== null) {
+      throw new CliError(`The production database cannot migrate to this schema in place${e.incompatible ? `: ${e.incompatible}` : ""}. Nothing changed.`, 409)
+    }
+    warn("The schema change deletes data in the production database:")
+    for (const op of e.destructive) log(c.red(`    ${op}`))
+    if (!opts.allowDestructive) {
+      if (!process.stdin.isTTY) throw new CliError(`Nothing changed. Run \`${opts.retry} --allow-destructive\` to apply it.`, 409)
+      if (!(await confirm("Delete that data and go on?", false))) { info(c.dim("Cancelled — nothing changed.")); return null }
+    }
+    return await call(true)
+  }
+}
+
+const allowDestructiveFlag = { "allow-destructive": bool("apply a schema change that deletes production data without asking") }
+
+const use = defineCommand({
+  name: "use",
+  usage: "<version>",
+  summary: "Make a release current again — a rollback, no compile",
+  description: "The release's bundle becomes what the project's address, the viewers and the store run, and its server is deployed to production again (the database migrates to that release's schema: a change that deletes data is shown and asked about, like a publish).",
+  flags: allowDestructiveFlag,
+  examples: ["lecodes releases use 1.2.3"],
+  run: async ({ args, flags }) => {
+    const version = args[0]?.replace(/^v/, "")
+    if (!version) throw new UsageError("Which release? `lecodes releases` lists them.")
+    const { apiUrl, token, manifest } = linkedProject()
+    const releases = await listReleases(apiUrl, token, manifest.uuid)
+    const target = releases.find(r => r.version === version)
+    if (!target) throw new CliError(`${manifest.name} has no release ${version} — \`lecodes releases\` lists them.`)
+    const previous = releases.find(r => r.current)
+
+    const res = await withSchemaConfirm(
+      allowDestructive => useRelease(apiUrl, token, manifest.uuid, version, { allowDestructive }),
+      { allowDestructive: flags["allow-destructive"], retry: `lecodes releases use ${version}` },
+    )
+    if (!res) return
+    const back = previous !== undefined && compareVersions(res.version, previous.version) < 0
+    reportRelease({ ...target, ...res }, qrUrl(apiUrl, manifest.uuid), back ? "Rolled back to" : "Published")
+  },
+})
+
+/**
+ * `releases upload <app.js>`: a bundle compiled here becomes the live release, no build on the
+ * platform — the way out when the build service's SDK makes bundles an app still in the stores
+ * cannot run (its SDK line is older). Compile with the CLI of that SDK and `--remote-assets`, so
+ * the bundle names the project's uploaded resources the way the platform's own builds do (the
+ * release pins them); `<app.js>.map` beside it goes up with it. Local changes are pushed first as
+ * the release's checkpoint, as `publish` does. The platform reads the bundle's `// sdk:` into the
+ * release — `lecodes releases` shows it — and refuses a project with server code (its server is
+ * built with the client).
+ */
+const upload = defineCommand({
+  name: "upload",
+  usage: "<app.js>",
+  summary: "Make a bundle compiled here the current release — no build on the platform",
+  description: "For a bundle the platform's build service cannot make any more: compiled with an older SDK's CLI (`compile --remote-assets`, so it names the project's uploaded resources), it becomes the current release with its own `// sdk:` — what the viewers of that SDK line run. Local changes are pushed first as the release's checkpoint. A project with server code cannot take one (its server is built with the client).",
+  flags: { message: str("checkpoint message when there are local changes (default \"Release\")", { alias: "m", value: "<text>" }) },
+  examples: ["lecodes releases upload app.js", "lecodes releases upload build/app.js -m \"Kungur for the 2.1 app\""],
+  run: async ({ args, flags }) => {
+    const file = args[0]
+    if (!file) throw new UsageError("Which bundle? `lecodes releases upload <app.js>`.")
+    const path = resolve(file)
+    if (!existsSync(path)) throw new CliError(`No such file: ${file}`)
+    const code = readFileSync(path, "utf8")
+    const sdk = /^\/\/ sdk: (\S+)/m.exec(code)?.[1]
+    if (!sdk) throw new CliError(`${file} is not a LeCodes bundle: no \`// sdk:\` header line. \`lecodes compile --remote-assets -o app.js\` writes one.`)
+    const map = existsSync(`${path}.map`) ? readFileSync(`${path}.map`, "utf8") : null
+
+    const { root, manifest, apiUrl, token } = linkedProject()
+    if (hasChanges(diffLocal(manifest, scanProject(root, manifest)))) await runPush({ message: flags.message || "Release" })
+    const release = await uploadReleaseBundle(apiUrl, token, manifest.uuid, { code, map })
+    reportRelease(release, qrUrl(apiUrl, manifest.uuid), "Uploaded")
+  },
+})
+
+export default defineCommand({
+  name: "releases",
+  summary: "List the project's releases (● = the current one); `releases use <version>` rolls back, `releases upload <app.js>` releases a bundle compiled here",
+  description: "Every `lecodes publish` (or the editor's Publish button) makes a release: an immutable build with its own version. The current one is what https://<handle>.le.codes, the viewers and the store run.",
+  commands: [use, upload],
+  examples: ["lecodes releases", "lecodes releases use 1.2.3", "lecodes releases upload app.js"],
+  run: async () => {
+    const { apiUrl, token, manifest } = linkedProject()
+    const releases = await listReleases(apiUrl, token, manifest.uuid)
+    if (releases.length === 0) {
+      info(`${manifest.name} has no releases yet — \`lecodes publish\` makes the first.`)
+      return
+    }
+    table([
+      ["", c.dim("VERSION"), c.dim("DATE"), c.dim("SIZE"), c.dim("SDK")],
+      ...releases.map(r => [
+        r.current ? c.green("●") : "",
+        r.current ? c.bold(r.version) : r.version,
+        relativeTime(r.createdAt),
+        formatSize(r.size),
+        r.sdk,
+      ]),
+    ])
+    if (!releases.some(r => r.current)) info(c.dim("  Unpublished: no release is current."))
+  },
+})

package/src/dev/backendWorker.ts

@@ -4,11 +4,12 @@ import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { format } from "node:util"
 import {
-  createAuthHost, createFilesHost, createInvoker, createSubscribeGuard, describeServer, loadServerModules, runSeed,
-  setChannelPublisher, setDbTransport, type AuthHost, type Heic, type LoadedServer, type Sharp,
+  createAuthHost, createFilesHost, createInvoker, createPushHost, createSubscribeGuard, describeServer, loadServerModules, runSeed,
+  setChannelPublisher, setDbTransport, type AuthHost, type Heic, type LoadedServer, type PushRelay, type Sharp,
 } from "lecodes-sdk/server"
 import { loadPeer } from "../hosts/peerInstall"
-import type { FromWorker, LogLevel, ToWorker } from "./localBackend"
+import { ApiError, sendPush } from "../platform/api"
+import type { FromWorker, LogLevel, PushSender, ToWorker } from "./localBackend"
 
 /*
  * The process a project's server bundle runs in under `lecodes dev` — the local twin of the runner's
@@ -96,6 +97,21 @@ const openDb = async (dir: string, filesDir: string, schema: string): Promise<st
   }
 }
 
+/** Push notifications go out through the platform's send route on the developer's own login, as `lecodes pn send`
+ *  does — a project push key is never needed here. The platform's 404 for an address it knows no more
+ *  (`unknown_addresses`) is answered as `unknown`, for the host to drop and send the rest again. */
+const pushRelay = (sender: PushSender): PushRelay => async (to, message) => {
+  try {
+    return await sendPush(sender.apiUrl, sender.token, sender.uuid, { to, ...message })
+  } catch (e) {
+    const body = e instanceof ApiError ? e.body as { code?: string, addresses?: unknown } | null : null
+    if (body?.code === "unknown_addresses" && Array.isArray(body.addresses)) {
+      return { sent: 0, failed: [], unknown: body.addresses.filter((a): a is string => typeof a === "string") }
+    }
+    throw new Error(`push: the platform refused the send: ${(e as Error).message}`)
+  }
+}
+
 const load = async (m: Extract<ToWorker, { t: "load" }>) => {
   const noDb = () => { throw new Error("db: the database is not open yet — query it inside an endpoint, not while the module loads") }
   setDbTransport({ exec: (op) => (db ?? noDb()).exec(op), batch: (ops) => (db ?? noDb()).batch(ops) })
@@ -116,6 +132,13 @@ const load = async (m: Extract<ToWorker, { t: "load" }>) => {
     log: (level, text) => post({ t: "log", level, text }),
   })
   authHost.install()
+  // Push channels: a user's devices are the sessions of the db with sign-in; the notifications go out through the platform
+  // when this checkout is linked and the developer is logged in.
+  createPushHost({
+    db: server.dbs.find(d => d.$auth) ?? null,
+    relay: m.push ? pushRelay(m.push) : null,
+    log: (level, text) => post({ t: "log", level, text }),
+  }).install()
   const auth = authHost.enabled ? authHost : null
   const onError = (id: string, e: unknown) => post({ t: "log", level: "error", text: `${id}: ${(e as Error)?.stack ?? e}` })
   // Stored files (`t.file()`): rows in the database, bytes in the folder beside it

package/src/dev/localBackend.ts

@@ -25,7 +25,7 @@ export type LogLevel = "log" | "info" | "warn" | "error" | "debug"
 type Ctx = Omit<RequestContext, "id">
 
 export type ToWorker =
-  | { t: "load", code: string, dbDir: string, filesDir: string, root: string }
+  | { t: "load", code: string, dbDir: string, filesDir: string, root: string, push: PushSender | null }
   | { t: "invoke", req: number, id: string, args: unknown[], ctx: Ctx }
   | { t: "subscribe", req: number, ch: string, args: unknown[], ctx: Ctx }
   | { t: "stop" }
@@ -37,8 +37,13 @@ export type FromWorker =
   | { t: "publish", ch: string, group: ChannelGroup | null, data: unknown }
   | { t: "log", level: LogLevel, text: string }
 
+/** How `pushChannel.send` reaches the platform's sender from this machine: the linked project and the developer's
+ *  own login (what `lecodes pn send` sends with). `null` = not linked or not logged in: sends answer 0, said once. */
+export type PushSender = { apiUrl: string, token: string, uuid: string }
+
 export type LocalBackendOptions = {
   root: string
+  push?: PushSender | null
   /** The database's folder (default `.lecodes/db`). */
   dbDir?: string
   /** The stored files' folder (`t.file()`; default: beside the database — `.lecodes/files`). */
@@ -147,7 +152,7 @@ export const startLocalBackend = (options: LocalBackendOptions): LocalBackend =>
         if (!closed) log(`[server:error] the server process exited (${status ?? "killed"}) — it starts again with the next call`)
       }
     })
-    child.send({ t: "load", code: bundle, dbDir, filesDir, root: options.root } satisfies ToWorker)
+    child.send({ t: "load", code: bundle, dbDir, filesDir, root: options.root, push: options.push ?? null } satisfies ToWorker)
   })
 
   const stop = async (l: Live) => {

package/src/dev/projectBackend.ts

@@ -3,7 +3,8 @@ import { join, relative } from "node:path"
 import { createChannelHub, fileResponse, isMultipart, receiveUploads, UploadError, type Upload } from "lecodes-sdk/server"
 import { compileServer, hasServerFiles, type CompileEntry } from "../compile/projectCompile"
 import { loadPeer } from "../hosts/peerInstall"
-import { LECODES_DIR } from "../project/manifest"
+import { LECODES_DIR, readManifest } from "../project/manifest"
+import { session } from "../commands/shared"
 import { readAppConfigAt } from "../commands/app/shared"
 import { filesDirOf, startLocalBackend, type LocalBackend } from "./localBackend"
 import { serve, type Served, type Socket, type SocketHandlers } from "./serve"
@@ -73,7 +74,12 @@ export const createProjectBackend = (options: ProjectBackendOptions): ProjectBac
       : Promise.resolve({ ok: false as const, status: 404, message: "The project has no server files" }),
   })
   const sockets = new Set<Socket>()
-  const start = () => startLocalBackend({ root, dbDir, log, onPublish: (ch, group, data) => hub.publish("", ch, group, data) })
+  // `pushChannel.send` reaches the platform's sender through the developer's own login when the checkout is linked —
+  // the way `lecodes pn send` sends; a project standing alone, or no login, sends nothing (said once in the console)
+  const push = (() => {
+    try { const { apiUrl, token } = session(); return { apiUrl, token, uuid: readManifest(root).uuid } } catch { return null }
+  })()
+  const start = () => startLocalBackend({ root, dbDir, log, push, onPublish: (ch, group, data) => hub.publish("", ch, group, data) })
 
   const envelope = (body: unknown) => new Response(JSON.stringify(body), { status: 200, headers: { "content-type": "application/json", "cache-control": "no-store", ...CORS } })
 

package/src/hosts/desktopScript.ts

@@ -41,7 +41,7 @@ export type DesktopPlanStep = {
   paintDump?: string
   /** A `dump` output step: the file the host wrote. */
   dump?: string
-  /** Expect keys the native host can't evaluate (`audio`: the headless recorder's) — reported as skipped. */
+  /** Expect keys the native host can't evaluate (`audio`, `toast`: the headless renderer's records) — reported as skipped. */
   skippedExpect: string[]
   /** Outputs the native host can't produce (`json`: the headless renderer's semantic shape — use `dump`). */
   skippedOutputs: string[]
@@ -58,7 +58,7 @@ export type DesktopPlan = {
 
 const ACTIONS = ["tap", "type", "fill", "scroll", "wait", "frames", "drag", "hold", "hover", "key", "keyDown", "keyUp", "look", "mouseTo", "wheel", "stick", "gamepad", "camera", "view"] as const
 const SEMANTIC_EXPECT = ["text", "notText", "node", "notNode", "screen", "value"]
-const UNSUPPORTED_EXPECT = ["audio"]
+const UNSUPPORTED_EXPECT = ["audio", "toast"]
 const VIEW_NAMES = ["iso", "top", "front", "side", "back"]
 const isVec3 = (v: unknown): v is [number, number, number] => Array.isArray(v) && v.length === 3 && v.every((n) => typeof n === "number")
 
@@ -362,7 +362,7 @@ export const evaluateDesktopRun = (plan: DesktopPlan, output: string, readFile:
   let ok = true
   for (const st of plan.steps) {
     const skipped = [
-      ...st.skippedExpect.map((k) => `expect.${k} (the headless audio recorder's — not on a native host)`),
+      ...st.skippedExpect.map((k) => `expect.${k} (the headless renderer's record — not on a native host)`),
       ...st.skippedOutputs.map((k) => `${k} output (the headless renderer's shape — use "dump" on a native host)`),
     ]
     let error: string | undefined

package/src/platform/api.ts

@@ -37,12 +37,27 @@ export type SyncResponse = {
   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. */
+  /** Set when the push requested `publish`: whether the release went out. */
   published?: boolean
-  /** A human-readable reason when `publish` was requested but the deploy failed (push still landed). */
+  /** The publish found the head to be the live release already and made none (as in `release`). */
+  unchanged?: true
+  /** The release, when `published`. */
+  release?: PublishResult
+  /** A human-readable reason when `publish` was requested but the release failed (push still landed). */
   publishError?: string
 }
 
+/** A release that went live: `url` = the project's origin (`https://<handle>.le.codes/`).
+ *  `unchanged`: the head was the live release already — no release was made, these are its values. */
+export type PublishResult = { unchanged?: true, version: string, handle: string, url: string, size: number, sdk: string }
+
+/** One release of `GET /projects/:uuid/publish` (newest first). */
+export type Release = { version: string, sdk: string, createdAt: string, size: number, hasServer: boolean, current: boolean }
+
+/** `GET /projects/:uuid/publish`: the project's publishing state. (`/projects/:uuid/releases` is the
+ *  LIBRARY releases route, not these.) */
+export type PublishState = { handle: string | null, url: string | null, webEnabled: boolean, live: unknown, releases: Release[] }
+
 const errorMessage = (body: unknown, status: number): string => {
   if (typeof body === "string" && body) return body
   if (body && typeof body === "object") {
@@ -62,6 +77,16 @@ const errorMessage = (body: unknown, status: number): string => {
 
 type RequestOptions = { method?: string, body?: unknown, token?: string }
 
+/** An HTTP failure: the CliError (message + status) plus the parsed body, for a caller that reads
+ *  more of the answer than its sentence (the 409 of a schema change). */
+export class ApiError extends CliError {
+  readonly body: unknown
+  constructor(message: string, status: number, body: unknown) {
+    super(message, status)
+    this.body = body
+  }
+}
+
 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
@@ -84,7 +109,7 @@ export const apiRequest = async <T = unknown>(apiUrl: string, path: string, opts
     : contentType.startsWith("text/") ? await resp.text()
     : null
 
-  if (resp.status >= 400) throw new CliError(errorMessage(parsed, resp.status), resp.status)
+  if (resp.status >= 400) throw new ApiError(errorMessage(parsed, resp.status), resp.status, parsed)
   return parsed as T
 }
 
@@ -117,13 +142,94 @@ export const uploadBlob = (apiUrl: string, token: string, uuid: string, name: st
   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 }) =>
+/** `publish` releases the project after the push; `force` beside it makes a release even when the
+ *  head is the live one already. */
+export const sync = (apiUrl: string, token: string, uuid: string, payload: { message: string, files: SyncFileInput[], folders: SyncFolderInput[], publish?: boolean, force?: 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: {} })
+/* ---- Releases (docs/plans/publishing-plan.md) ---------------------------------------------
+ * A publish compiles the head (checkpointed by the platform when dirty), deploys its server to the
+ * prod runner and makes the release current; `use` makes an older (or newer) release current again
+ * without a compile. Both can be refused over the prod database's schema — the editor's 409. */
+
+/** The prod database refused the release's schema. `destructive` = the ops that delete data (the
+ *  call goes through again with `allowDestructive`); `incompatible` = marcidb's reason the schema
+ *  cannot migrate in place at all (no flag takes it; null when it can). */
+export class SchemaChangeError extends CliError {
+  readonly destructive: string[]
+  readonly incompatible: string | null
+  constructor(message: string, destructive: string[], incompatible: string | null) {
+    super(message, 409)
+    this.destructive = destructive
+    this.incompatible = incompatible
+  }
+}
+
+/** A plan op as one line: the platform relays the runner's `{ op, entity, field?, text }` objects. */
+const opText = (op: unknown): string => {
+  if (typeof op === "string") return op
+  if (op && typeof op === "object" && typeof (op as { text?: unknown }).text === "string") return (op as { text: string }).text
+  return JSON.stringify(op)
+}
+
+/** The 409 `{ error, destructive?, incompatible? }` as a SchemaChangeError; anything else unchanged
+ *  (a 409 "a publish is already under way" is a plain refusal). */
+export const schemaChangeOf = (e: unknown): unknown => {
+  if (!(e instanceof ApiError) || e.status !== 409 || !e.body || typeof e.body !== "object") return e
+  const body = e.body as { error?: unknown, destructive?: unknown, incompatible?: unknown }
+  const destructive = Array.isArray(body.destructive) ? body.destructive.map(opText) : null
+  const incompatible = typeof body.incompatible === "string" ? body.incompatible : body.incompatible === true ? "" : null
+  if (!destructive && incompatible === null) return e
+  return new SchemaChangeError(typeof body.error === "string" ? body.error : "The schema change needs a confirmation", destructive ?? [], incompatible)
+}
+
+/** A release call's failure in the CLI's words: the schema 409 typed, a build error (400, publish
+ *  only) said as one, a service of ours being down (502 / 503) said as ours, not the project's. */
+const releaseFailure = (e: unknown, opts: { build: boolean }): unknown => {
+  const schema = schemaChangeOf(e)
+  if (schema !== e || !(e instanceof ApiError)) return schema
+  if (opts.build && e.status === 400) return new CliError(`Build failed:
+${e.message}`, 400)
+  if (e.status === 502 || e.status === 503) {
+    // An nginx error page is HTML — its text says nothing the sentence doesn't.
+    const detail = e.message.trimStart().startsWith("<") ? "" : `: ${e.message.trim()}`
+    const service = opts.build ? "The platform's build service is unavailable" : "The platform could not reach the app backend"
+    return new CliError(`${service} (${e.status})${detail}. Nothing changed — try again in a minute.`, e.status)
+  }
+  return e
+}
+
+/** Publish the project's head (= the editor's Publish button). `unchanged` when it is the live
+ *  release already — `force` makes a release all the same. */
+export const publishProject = async (apiUrl: string, token: string, uuid: string, opts: { allowDestructive?: boolean, force?: boolean } = {}): Promise<PublishResult> => {
+  try {
+    const body = { ...(opts.allowDestructive ? { allowDestructive: true } : {}), ...(opts.force ? { force: true } : {}) }
+    return await apiRequest<PublishResult>(apiUrl, `/projects/${uuid}/publish`, { token, body })
+  } catch (e) { throw releaseFailure(e, { build: true }) }
+}
+
+/** The project's releases, newest first; `current` marks the live one. */
+export const listReleases = async (apiUrl: string, token: string, uuid: string): Promise<Release[]> =>
+  (await apiRequest<PublishState>(apiUrl, `/projects/${uuid}/publish`, { token })).releases
+
+/** Make an existing release current (a rollback, or forward again) — no compile. */
+export const useRelease = async (apiUrl: string, token: string, uuid: string, version: string, opts: { allowDestructive?: boolean } = {}): Promise<{ version: string, handle: string, url: string }> => {
+  try {
+    return await apiRequest<{ version: string, handle: string, url: string }>(
+      apiUrl, `/projects/${uuid}/releases/${encodeURIComponent(version)}/use`, { token, body: opts.allowDestructive ? { allowDestructive: true } : {} })
+  } catch (e) { throw releaseFailure(e, { build: false }) }
+}
+
+/** A bundle compiled here as the live release — of the SDK its header names, no build on the
+ *  platform (`lecodes releases upload`). A refusal (no `// sdk:`, a project with server code) is a 400 as text. */
+export const uploadReleaseBundle = async (apiUrl: string, token: string, uuid: string, bundle: { code: string, map: string | null }): Promise<PublishResult> => {
+  const form = new FormData()
+  form.append("app", new Blob([ bundle.code ], { type: "text/javascript" }), "app.js")
+  if (bundle.map !== null) form.append("map", new Blob([ bundle.map ], { type: "application/json" }), "app.js.map")
+  try {
+    return await apiRequest<PublishResult>(apiUrl, `/projects/${uuid}/releases/upload`, { token, body: form })
+  } catch (e) { throw releaseFailure(e, { build: false }) }
+}
 
 export type DesignShare = {
   token: string | null
@@ -247,6 +353,8 @@ export const deleteDesignCommentMessage = (
 export type PushSendPayload = {
   to?: string[]
   users?: string[]
+  /** The server's push channel the notification is of (`<path>#<export>`): the app's side hears each channel's own. */
+  channel?: string
   title: string
   body?: string
   url?: string

package/src/plugin/generate.ts

@@ -17,7 +17,7 @@ import { emitSwift } from "./emitSwift"
 import { emitWeb } from "./emitWeb"
 import { lower } from "./lower"
 import { MANIFEST_FILE, ManifestError, readManifestIfAny, type PluginManifest } from "./manifest"
-import { missingDeclarations, usesPermissions, type PermissionKind } from "./permissions"
+import { missingDeclarations, usesFeatures, usesPermissions, type PermissionKind } from "./permissions"
 import { DEFAULT_SDK_PATH, PACKAGE_FILE, PackageError, emitPackageSwift } from "./emitPackage"
 
 // A path as the report shows it: relative to `from`, with `/` on every platform (a report is
@@ -89,21 +89,24 @@ export const generatePlugin = (ts: typeof tsModule, plugin: PluginDir): { contra
 }
 
 /** The declarations the contract's `@permission` kinds need, held against the plugin's manifests:
- *  the usage strings of ios.infoPlist (a missing one crashes the app at the prompt) and the
+ *  the usage strings of ios.infoPlist (a missing one crashes the app at the prompt), the
  *  `<uses-permission>` elements of android/src/main/AndroidManifest.xml (a missing one is a
- *  silent refusal). Checked where the plugin has the half; a plugin without a manifest (a project's
- *  own, the shell declares for it) is not held. */
+ *  silent refusal) and the `<uses-feature android:required="false">` of each feature those
+ *  permissions imply (a missing one makes Play require the hardware). Checked where the plugin has
+ *  the half; a plugin without a manifest (a project's own, the shell declares for it) is not held. */
 const checkPermissions = (plugin: PluginDir, contract: Contract, manifest: PluginManifest | null): void => {
   if (!manifest) return
   const kinds: PermissionKind[] = []
   for (const ch of contract.channels) for (const m of ch.methods) for (const k of m.permissions) if (!kinds.includes(k)) kinds.push(k)
   if (kinds.length === 0) return
   const androidManifest = join(plugin.dir, "android", "src", "main", "AndroidManifest.xml")
-  const androidNames = manifest.android ? (existsSync(androidManifest) ? usesPermissions(readFileSync(androidManifest, "utf8")) : []) : null
-  const missing = missingDeclarations(kinds, manifest.ios ? manifest.ios.infoPlist ?? {} : null, androidNames)
+  const androidXml = manifest.android ? (existsSync(androidManifest) ? readFileSync(androidManifest, "utf8") : "") : null
+  const missing = missingDeclarations(kinds, manifest.ios ? manifest.ios.infoPlist ?? {} : null,
+    androidXml === null ? null : usesPermissions(androidXml), androidXml === null ? null : usesFeatures(androidXml))
   const problems: string[] = []
   if (missing.infoPlist.length) problems.push(`ios.infoPlist: the contract's @permission needs ${missing.infoPlist.join(", ")} — the usage string the dialog shows`)
   if (missing.android.length) problems.push(`android/src/main/AndroidManifest.xml: the contract's @permission needs <uses-permission android:name="…"/> for ${missing.android.join(", ")}`)
+  if (missing.androidFeatures.length) problems.push(`android/src/main/AndroidManifest.xml: the contract's @permission implies <uses-feature android:name="…" android:required="false"/> for ${missing.androidFeatures.join(", ")} — without it Play requires the hardware`)
   if (problems.length) throw new ManifestError(join(plugin.dir, MANIFEST_FILE), problems)
 }
 

package/src/plugin/permissions.ts

@@ -4,6 +4,9 @@
 // asks nothing (the browser's API prompts itself). A kind's needs on each platform are known here,
 // so `lecodes plugin gen` can hold the plugin's manifests to them: the Info.plist usage strings the
 // manifest declares (ios.infoPlist) and the `<uses-permission>` elements of the Android manifest.
+// Android implies a REQUIRED hardware feature from some of those permissions (RECORD_AUDIO → the
+// microphone), so the Android manifest also declares each one `<uses-feature android:required="false">`
+// — else Play requires the hardware of every device the app installs on.
 //
 // The kinds are the SDK's (`permissions.query / request` in lecodes-sdk: sdk/src/runtime/permissions.ts).
 
@@ -13,32 +16,57 @@ export type PermissionKind = (typeof PERMISSION_KINDS)[number]
 export const isPermissionKind = (s: string): s is PermissionKind => (PERMISSION_KINDS as readonly string[]).includes(s)
 
 /** What a kind needs declared: Info.plist keys (every one), Android permissions (every group has
- *  one of its names in the manifest — location takes FINE or COARSE). */
-export const PERMISSION_NEEDS: Record<PermissionKind, { infoPlist: string[], android: string[][] }> = {
-  camera: { infoPlist: ["NSCameraUsageDescription"], android: [["android.permission.CAMERA"]] },
-  microphone: { infoPlist: ["NSMicrophoneUsageDescription"], android: [["android.permission.RECORD_AUDIO"]] },
+ *  one of its names in the manifest — location takes FINE or COARSE), and the Android features those
+ *  permissions imply (every one declared `android:required="false"`). */
+export const PERMISSION_NEEDS: Record<PermissionKind, { infoPlist: string[], android: string[][], androidFeatures: string[] }> = {
+  camera: { infoPlist: ["NSCameraUsageDescription"], android: [["android.permission.CAMERA"]], androidFeatures: ["android.hardware.camera"] },
+  microphone: {
+    infoPlist: ["NSMicrophoneUsageDescription"],
+    android: [["android.permission.RECORD_AUDIO"]],
+    androidFeatures: ["android.hardware.microphone"],
+  },
   location: {
     infoPlist: ["NSLocationWhenInUseUsageDescription"],
     android: [["android.permission.ACCESS_FINE_LOCATION", "android.permission.ACCESS_COARSE_LOCATION"]],
+    androidFeatures: ["android.hardware.location"],
   },
   // Speech recognition: its own purpose string on iOS, the microphone's permission on Android. A
   // method that recognizes live speech tags `microphone` beside it (the audio is the microphone's).
-  speech: { infoPlist: ["NSSpeechRecognitionUsageDescription"], android: [["android.permission.RECORD_AUDIO"]] },
+  speech: {
+    infoPlist: ["NSSpeechRecognitionUsageDescription"],
+    android: [["android.permission.RECORD_AUDIO"]],
+    androidFeatures: ["android.hardware.microphone"],
+  },
 }
 
 /** The `android:name`s of the `<uses-permission>` elements of an AndroidManifest.xml. */
 export const usesPermissions = (xml: string): string[] =>
   [...xml.matchAll(/<uses-permission(?:-sdk-23)?\b[^>]*\bandroid:name\s*=\s*"([^"]+)"/g)].map(m => m[1]!)
 
+/** The `<uses-feature>` elements of an AndroidManifest.xml that name a feature (a `glEsVersion` one
+ *  names none), in any attribute order. `android:required` absent = true, Android's default. */
+export const usesFeatures = (xml: string): { name: string, required: boolean }[] => {
+  const out: { name: string, required: boolean }[] = []
+  for (const m of xml.replace(/<!--[\s\S]*?-->/g, "").matchAll(/<uses-feature\b[^>]*>/g)) {
+    const attr = (re: RegExp): string | undefined => re.exec(m[0])?.[2]
+    const name = attr(/\bandroid:name\s*=\s*(["'])(.*?)\1/)
+    if (name) out.push({ name, required: attr(/\bandroid:required\s*=\s*(["'])(.*?)\1/)?.trim() !== "false" })
+  }
+  return out
+}
+
 /** The declarations the kinds need and the manifests lack: `infoPlist` keys missing from the iOS
- *  manifest's ios.infoPlist (null = no iOS half), `android` permission groups with no name in the
- *  Android manifest (null = no Android half). Each entry names the kind that needs it. */
+ *  manifest's ios.infoPlist (null = no iOS half); `android` permission groups with no name in the
+ *  Android manifest, and `androidFeatures` the permissions imply that it does not declare
+ *  `android:required="false"` — absent, or declared required: a plugin never requires hardware, the
+ *  app may (both null = no Android half). Each entry names the kind that needs it. */
 export const missingDeclarations = (
   kinds: PermissionKind[],
   infoPlist: Record<string, string> | null,
   androidNames: string[] | null,
-): { infoPlist: string[], android: string[] } => {
-  const out = { infoPlist: [] as string[], android: [] as string[] }
+  androidFeatures: { name: string, required: boolean }[] | null,
+): { infoPlist: string[], android: string[], androidFeatures: string[] } => {
+  const out = { infoPlist: [] as string[], android: [] as string[], androidFeatures: [] as string[] }
   for (const kind of kinds) {
     const needs = PERMISSION_NEEDS[kind]
     if (infoPlist) for (const key of needs.infoPlist) {
@@ -47,6 +75,10 @@ export const missingDeclarations = (
     if (androidNames) for (const group of needs.android) {
       if (!group.some(name => androidNames.includes(name))) out.android.push(`${group.join(" or ")} (${kind})`)
     }
+    if (androidFeatures) for (const feature of needs.androidFeatures) {
+      const declared = androidFeatures.filter(f => f.name === feature)
+      if (declared.length === 0 || declared.some(f => f.required)) out.androidFeatures.push(`${feature} (${kind})`)
+    }
   }
-  return { infoPlist: [...new Set(out.infoPlist)], android: [...new Set(out.android)] }
+  return { infoPlist: [...new Set(out.infoPlist)], android: [...new Set(out.android)], androidFeatures: [...new Set(out.androidFeatures)] }
 }