lecodes-cli 2.4.10 → 2.5.0

package/src/hosts/peerInstall.ts

@@ -61,7 +61,11 @@ const manualCommand = (dir: string, specs: string[]) => commandLine(ownManager()
  * Install peers into the prefix. Asks for consent unless `opts.yes` / LECODES_YES / `--yes` say so;
  * throws CliError with the manual command when it can't ask or the user declines.
  */
-export const installPeers = async (names: string[], why: string, opts: { yes?: boolean } = {}): Promise<void> => {
+export const installPeers = async (names: string[], why: string, opts: { yes?: boolean, at?: Record<string, string> } = {}): Promise<void> => {
+  // `at`: an exact version per npm peer instead of its spec's range — `lecodes update` moving one to the newest
+  // release in its range: bun keeps a locked version that already satisfies the range (canvas stayed 0.1.65
+  // under ^0.1.65 with 0.1.100 out), so the range alone would move nothing
+  const specOf = async (name: string) => opts.at?.[name] ? `${name}@${opts.at[name]}` : peerSpec(name)
   const dir = peersDir()
   mkdirSync(dir, { recursive: true })
   const manifest = join(dir, "package.json")
@@ -73,7 +77,7 @@ export const installPeers = async (names: string[], why: string, opts: { yes?: b
   }
   // The renderer must be in place before canvas's range can be read off it — install in order.
   const ordered = [...names].sort((a, b) => (a === "lecodes-headless" ? -1 : b === "lecodes-headless" ? 1 : 0))
-  const specsNow = await Promise.all(ordered.map(peerSpec))
+  const specsNow = await Promise.all(ordered.map(specOf))
 
   const yes = opts.yes === true || !!process.env.LECODES_YES
   if (!yes) {
@@ -92,7 +96,7 @@ export const installPeers = async (names: string[], why: string, opts: { yes?: b
   if (!tool) throw new CliError(`Neither npm nor bun is on PATH, so ${names.join(" + ")} can't be installed automatically. Install one, or run on a machine with Node:  ${manualCommand(dir, specsNow)}`)
 
   for (const name of ordered) {
-    const spec = await peerSpec(name) // canvas's range comes from the renderer installed a step earlier
+    const spec = await specOf(name) // canvas's range comes from the renderer installed a step earlier
     const argv = installIntoArgv(tool, dir, [spec])
     note(`$ ${tool} ${argv.join(" ")}`)
     const r = spawnSync(tool, argv, { stdio: "inherit", shell: process.platform === "win32", timeout: 10 * 60_000 })

package/src/hub/api.ts

@@ -0,0 +1,220 @@
+import { CliError } from "../cli"
+
+/*
+ * The client of hub's HTTP API (LeCodesHub/docs: accounts.md "Device flow", deploy.md "The project
+ * API"). Every call takes the hub origin and, when it needs one, the PAT (`Authorization: Bearer
+ * lch_…`). Failures are `HubApiError`: a CliError carrying the HTTP status and the parsed body, the
+ * same shape as the old platform client (src/platform/api.ts), so a command can tell a 404 from a
+ * 403 and print the server's sentence. The device-flow poll is the one call that reads statuses
+ * as answers (428 pending, 410 expired) instead of errors.
+ */
+
+export type Visibility = "public" | "private"
+
+/** `POST /api/account/device`. */
+export type DeviceStart = { deviceCode: string, userCode: string, verificationUrl: string, interval: number, expiresIn: number }
+
+/** One poll of `POST /api/account/device/token`. `slow-down` is RFC 8628's `slow_down`. */
+export type DevicePoll = { kind: "token", token: string } | { kind: "pending" } | { kind: "slow-down" } | { kind: "expired" }
+
+/** `POST /api/repos`. `remote` is the repo's smart-HTTP URL (`https://hub.le.codes/ns/name.git`). */
+export type CreatedRepo = { repo: unknown, project: unknown, remote: string }
+
+/** queued → building → ready | failed; a queued one superseded by a newer push is cancelled. */
+export type DeployStatus = "queued" | "building" | "ready" | "failed" | "cancelled" | (string & {})
+
+/** One row of `GET /api/projects/:ns/:name/deploys`. `environment` is null for a preview. */
+export type HubDeploy = {
+  number: number
+  commit: string
+  ref: string
+  message?: string | null
+  author?: string | null
+  status: DeployStatus
+  host: string
+  environment?: string | null
+  createdAt: string
+  finishedAt?: string | null
+  size?: number | null
+  /** Only on `GET …/deploys/:number`. */
+  error?: string | null
+  warnings?: string[]
+  sdk?: string | null
+}
+
+export type HubEnvironment = {
+  name: string
+  rule?: { branch: string } | { tag: string }
+  host: string
+  current?: HubDeploy | null
+}
+
+/** `GET /api/projects/:ns/:name` (deploy.md "The project API"): `project`, its `environments` with
+ *  their current deployment, the owner's `usage`. The repo's `ns/name` is the caller's own. */
+export type HubProject = {
+  project: { handle: string, visibility?: Visibility, sdk?: string | null, serverUrl?: string, deploys?: number, createdAt?: string }
+  environments: HubEnvironment[]
+  usage?: Record<string, unknown>
+}
+
+/** An HTTP failure: the message, the status and the parsed body. */
+export class HubApiError extends CliError {
+  readonly body: unknown
+  constructor(message: string, status: number, body: unknown) {
+    super(message, status)
+    this.body = body
+  }
+}
+
+const errorMessage = (body: unknown, status: number): string => {
+  if (typeof body === "string" && body.trim()) return body.trim()
+  if (body && typeof body === "object") {
+    const b = body as Record<string, unknown>
+    if (typeof b.message === "string") return b.message
+    if (typeof b.error === "string") return b.error
+    // field errors: { error: { slug: "taken" } } or { error: { slug: { message } } }
+    if (b.error && typeof b.error === "object") {
+      const [field, first] = Object.entries(b.error)[0] ?? []
+      if (typeof first === "string") return `${field}: ${first}`
+      if (first && typeof first === "object" && typeof (first as { message?: unknown }).message === "string") return `${field}: ${(first as { message: string }).message}`
+    }
+  }
+  return `Request failed with status ${status}`
+}
+
+type RequestOptions = { method?: string, body?: unknown, token?: string, accept?: string }
+
+/** The raw response of a hub call (network failure → CliError naming the origin). */
+export const hubFetch = async (base: string, path: string, opts: RequestOptions = {}): Promise<Response> => {
+  const headers: Record<string, string> = {}
+  if (opts.token) headers["Authorization"] = "Bearer " + opts.token
+  if (opts.body !== undefined) headers["Content-Type"] = "application/json"
+  if (opts.accept) headers["Accept"] = opts.accept
+  try {
+    return await fetch(`${base}${path}`, {
+      method: opts.method ?? (opts.body !== undefined ? "POST" : "GET"),
+      headers,
+      body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+    })
+  } catch {
+    throw new CliError(`Cannot reach ${base} — is the hub URL correct and online?`)
+  }
+}
+
+const parseBody = async (resp: Response): Promise<unknown> => {
+  const type = resp.headers.get("content-type") ?? ""
+  if (type.startsWith("application/json")) { try { return await resp.json() } catch { return null } }
+  if (type.startsWith("text/")) return await resp.text()
+  return null
+}
+
+const failure = (base: string, status: number, body: unknown, hadToken: boolean): HubApiError => {
+  let message = errorMessage(body, status)
+  if (status === 401) message += hadToken
+    ? ` — ${base} refused the stored token; run \`lecodes hub login\` again`
+    : " — run `lecodes hub login` first"
+  return new HubApiError(message, status, body)
+}
+
+/** A JSON call: the parsed answer, or a HubApiError for a status >= 400. */
+export const hubRequest = async <T = unknown>(base: string, path: string, opts: RequestOptions = {}): Promise<T> => {
+  const resp = await hubFetch(base, path, opts)
+  const body = await parseBody(resp)
+  if (resp.status >= 400) throw failure(base, resp.status, body, !!opts.token)
+  return body as T
+}
+
+const projectPath = (ns: string, name: string): string => `/api/projects/${encodeURIComponent(ns)}/${encodeURIComponent(name)}`
+
+// ---- who am I ---------------------------------------------------------------------------------
+
+export type HubNamespace = { id: number | string, slug: string, name: string, kind: "user" | "org" | (string & {}), role?: string }
+
+/** `GET /api/account` (accounts.md "Who am I"): `namespaces` lists the user's own account first, then orgs. */
+export type HubWhoami = {
+  account: { id: number | string, slug: string, name: string, kind: string, plan: string, staff: boolean }
+  email: string
+  emailVerified: boolean
+  namespaces: HubNamespace[]
+  scopes: string[]
+}
+
+export const whoami = (base: string, token: string): Promise<HubWhoami> =>
+  hubRequest<HubWhoami>(base, "/api/account", { token })
+
+// ---- device flow (RFC 8628) -------------------------------------------------------------------
+
+export const startDeviceLogin = (base: string, body: { scopes: string[], name: string }): Promise<DeviceStart> =>
+  hubRequest<DeviceStart>(base, "/api/account/device", { body })
+
+export const pollDeviceLogin = async (base: string, deviceCode: string): Promise<DevicePoll> => {
+  const resp = await hubFetch(base, "/api/account/device/token", { body: { deviceCode } })
+  const body = await parseBody(resp)
+  const fields = body && typeof body === "object" ? body as { token?: unknown, error?: unknown } : {}
+  if (resp.status < 300 && typeof fields.token === "string") return { kind: "token", token: fields.token }
+  if (resp.status === 410 || fields.error === "expired_token") return { kind: "expired" }
+  if (fields.error === "slow_down") return { kind: "slow-down" }
+  if (resp.status === 428 || fields.error === "authorization_pending") return { kind: "pending" }
+  throw failure(base, resp.status, body, false)
+}
+
+// ---- repos and projects -----------------------------------------------------------------------
+
+/** Create the repo and its project in `ns` (the CLI always names it; `GET /api/account` lists the choices). */
+export const createRepo = (base: string, token: string, body: { ns: string, name: string, visibility: Visibility }): Promise<CreatedRepo> =>
+  hubRequest<CreatedRepo>(base, "/api/repos", { token, body })
+
+export const getProject = (base: string, token: string | undefined, ns: string, name: string): Promise<HubProject> =>
+  hubRequest<HubProject>(base, projectPath(ns, name), { token })
+
+export const listDeploys = (base: string, token: string | undefined, ns: string, name: string): Promise<HubDeploy[]> =>
+  hubRequest<HubDeploy[]>(base, `${projectPath(ns, name)}/deploys`, { token })
+
+export const getDeploy = (base: string, token: string | undefined, ns: string, name: string, number: number): Promise<HubDeploy> =>
+  hubRequest<HubDeploy>(base, `${projectPath(ns, name)}/deploys/${number}`, { token })
+
+/**
+ * Follow a deployment's build log: `GET …/deploys/:number/log?follow=1` as server-sent events.
+ * `onText` gets each event's data (multi-line data joined with "\n", as the SSE spec says). The
+ * promise settles when the server closes the stream or sends an `end` / `done` event. A server that
+ * answers plain text instead (the build finished between the list and this call) is passed through
+ * whole.
+ */
+export const followDeployLog = async (
+  base: string, token: string | undefined, ns: string, name: string, number: number, onText: (text: string) => void,
+): Promise<void> => {
+  const resp = await hubFetch(base, `${projectPath(ns, name)}/deploys/${number}/log?follow=1`, { token, accept: "text/event-stream" })
+  if (resp.status >= 400) throw failure(base, resp.status, await parseBody(resp), !!token)
+  const type = resp.headers.get("content-type") ?? ""
+  if (!type.startsWith("text/event-stream")) { const text = await resp.text(); if (text) onText(text); return }
+  if (!resp.body) return
+  const reader = resp.body.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ""
+  let event = "", data: string[] = []
+  /** Hand the pending event over; true when it was the end marker. */
+  const dispatch = (): boolean => {
+    const end = event === "end" || event === "done"
+    if (data.length && !end) onText(data.join("\n"))
+    event = ""; data = []
+    return end
+  }
+  for (;;) {
+    const { value, done } = await reader.read()
+    if (done) break
+    buffer += decoder.decode(value, { stream: true })
+    let nl: number
+    while ((nl = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, nl).replace(/\r$/, "")
+      buffer = buffer.slice(nl + 1)
+      if (line === "") { if (dispatch()) { await reader.cancel(); return } continue }
+      if (line.startsWith(":")) continue // a comment / keep-alive
+      const colon = line.indexOf(":")
+      const field = colon < 0 ? line : line.slice(0, colon)
+      const val = colon < 0 ? "" : line.slice(colon + 1).replace(/^ /, "")
+      if (field === "data") data.push(val)
+      else if (field === "event") event = val
+    }
+  }
+  dispatch()
+}

package/src/hub/config.ts

@@ -0,0 +1,53 @@
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { CliError } from "../cli"
+
+/*
+ * ~/.lecodes/hub.json — the hub this machine is signed in to and its personal access token:
+ * `{ "url": "https://hub.le.codes", "token": "lch_…" }`. Separate from config.json (the old
+ * le.codes platform), so the two groups never read each other's token. The file is written with
+ * mode 0600: git's credential helper (`lecodes hub credential`) reads the token from it, and it is
+ * the only copy on disk (no `.git-credentials`). The path is resolved on every call, not at module
+ * load, so a test can point HOME / USERPROFILE at a temporary folder.
+ */
+
+export type HubConfig = { url: string, token: string }
+
+export const DEFAULT_HUB = "https://hub.le.codes"
+
+export const hubConfigPath = (): string => join(homedir(), ".lecodes", "hub.json")
+
+/** Strip whitespace and trailing slashes so `url + "/api/…"` composes. */
+export const normalizeHubUrl = (url: string): string => {
+  const trimmed = url.trim().replace(/\/+$/, "")
+  let parsed: URL
+  try { parsed = new URL(trimmed) } catch { throw new CliError(`Not a URL: ${url}`) }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") throw new CliError(`The hub URL must be http(s): ${url}`)
+  return trimmed
+}
+
+/** The stored login, or null when there is none (or the file is unreadable / malformed). */
+export const loadHubConfig = (): HubConfig | null => {
+  try {
+    const raw = JSON.parse(readFileSync(hubConfigPath(), "utf8")) as Partial<HubConfig>
+    if (typeof raw.url === "string" && typeof raw.token === "string" && raw.url && raw.token) return { url: raw.url, token: raw.token }
+  } catch { /* none yet */ }
+  return null
+}
+
+/** The stored login or a "run `lecodes hub login`" error. */
+export const requireHubConfig = (): HubConfig => {
+  const config = loadHubConfig()
+  if (!config) throw new CliError("Not signed in to hub. Run `lecodes hub login` first.")
+  return config
+}
+
+export const saveHubConfig = (config: HubConfig): string => {
+  const file = hubConfigPath()
+  mkdirSync(join(file, ".."), { recursive: true })
+  writeFileSync(file, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 })
+  // `mode` applies only when the file is created; an existing file keeps its bits without this.
+  chmodSync(file, 0o600)
+  return file
+}

package/src/hub/git.ts

@@ -0,0 +1,148 @@
+import { spawnSync } from "node:child_process"
+import { existsSync, realpathSync } from "node:fs"
+import { basename, delimiter, join } from "node:path"
+import { CliError } from "../cli"
+import type { HubConfig } from "./config"
+
+/*
+ * What `lecodes hub` asks of git: running it, the credential-helper line `hub login` writes into the
+ * global config, the answer `hub credential` gives git, and reading `ns/name` back from the `hub`
+ * remote. The CLI never stores the token anywhere git would (no `.git-credentials`): git asks the
+ * helper on every push / fetch and the helper reads ~/.lecodes/hub.json.
+ */
+
+export type GitResult = { ok: boolean, stdout: string, stderr: string }
+
+/** Run git; a missing git binary is a CliError, a non-zero exit is `ok: false` for the caller to read. */
+export const git = (args: string[], cwd = process.cwd()): GitResult => {
+  const r = spawnSync("git", args, { cwd, encoding: "utf8", windowsHide: true })
+  if (r.error) throw new CliError((r.error as NodeJS.ErrnoException).code === "ENOENT" ? "git is not installed (or not on PATH)." : `git failed: ${r.error.message}`)
+  return { ok: r.status === 0, stdout: (r.stdout ?? "").trim(), stderr: (r.stderr ?? "").trim() }
+}
+
+/** Run git and throw its stderr as a CliError when it fails. */
+export const gitOrThrow = (args: string[], cwd = process.cwd()): string => {
+  const r = git(args, cwd)
+  if (!r.ok) throw new CliError(`git ${args.join(" ")} failed${r.stderr ? `: ${r.stderr}` : ""}`)
+  return r.stdout
+}
+
+// ---- which hosts get the token ----------------------------------------------------------------
+
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]", "::1"])
+
+/**
+ * The protocol the token may travel over to this hub: https always; plain http only to a loopback
+ * hub (`--url http://localhost:3000`, a hub run on this machine) — never over the network in clear.
+ * null = the URL is refused.
+ */
+export const tokenProtocol = (hubUrl: string): "https" | "http" | null => {
+  const u = new URL(hubUrl)
+  if (u.protocol === "https:") return "https"
+  if (u.protocol === "http:" && LOOPBACK.has(u.hostname.toLowerCase())) return "http"
+  return null
+}
+
+/** `credential.<this>.helper`: git's URL-scoped key for the hub (`https://hub.le.codes`). */
+export const credentialScope = (hubUrl: string): string => {
+  const u = new URL(hubUrl)
+  return `${u.protocol}//${u.host}`
+}
+
+/** git's credential-helper input: `key=value` lines up to a blank line. */
+export const parseCredentialInput = (input: string): Record<string, string> => {
+  const out: Record<string, string> = {}
+  for (const line of input.split(/\r?\n/)) {
+    if (line === "") break
+    const eq = line.indexOf("=")
+    if (eq > 0) out[line.slice(0, eq)] = line.slice(eq + 1)
+  }
+  return out
+}
+
+/**
+ * What `lecodes hub credential <action>` prints for git. Only `get` answers, and only when the
+ * request is for the stored hub: the same host (port included) over the protocol `tokenProtocol`
+ * allows. Anything else, any other host, `store`, `erase`: nothing — git then asks its next helper,
+ * and the token never leaves for a host it was not minted for.
+ */
+export const credentialAnswer = (action: string, input: string, config: HubConfig | null): string => {
+  if (action !== "get" || !config) return ""
+  const req = parseCredentialInput(input)
+  let stored: URL
+  try { stored = new URL(config.url) } catch { return "" }
+  const protocol = tokenProtocol(config.url)
+  if (!protocol || req.protocol !== protocol) return ""
+  if (!req.host || req.host.toLowerCase() !== stored.host.toLowerCase()) return ""
+  return `username=token\npassword=${config.token}\n`
+}
+
+// ---- the helper line --------------------------------------------------------------------------
+
+const shellQuote = (s: string): string => `'${s.replace(/\\/g, "/").replace(/'/g, `'\\''`)}'`
+
+const real = (p: string): string => { try { return realpathSync(p) } catch { return p } }
+
+/** Some `lecodes` on PATH resolves to `target`. */
+const onPathAs = (target: string): boolean => {
+  const exe = process.platform === "win32" ? "lecodes.exe" : "lecodes"
+  const want = real(target)
+  return (process.env.PATH ?? "").split(delimiter).some(d => {
+    if (!d) return false
+    const cand = join(d, exe)
+    return existsSync(cand) && real(cand) === want
+  })
+}
+
+/**
+ * How git should start THIS CLI, for `credential.<hub>.helper = !<this> hub credential`. git runs
+ * the `!` form through its shell, so the line is a shell command:
+ *   - the standalone binary (src/commands/install.ts: the `lecodes` executable with `chisel` and
+ *     `runtime/` beside it): `lecodes` when the `lecodes` on PATH is this very binary (installed),
+ *     else the binary's absolute path (run from an unpacked archive);
+ *   - the npm package (a script under node_modules run by node / bun): `lecodes`, the bin npm put
+ *     on PATH;
+ *   - a source checkout (`bun tools/cli/src/index.ts`): the runtime and the entry, both absolute —
+ *     a global `lecodes` would be a different CLI.
+ */
+export const selfCommand = (): string => {
+  const exe = basename(process.execPath).toLowerCase().replace(/\.exe$/, "")
+  if (exe === "node" || exe === "bun") {
+    const script = process.argv[1] ? real(process.argv[1]) : ""
+    if (!script || /[\\/]node_modules[\\/]/.test(script)) return "lecodes"
+    return `${shellQuote(process.execPath)} ${shellQuote(script)}`
+  }
+  return onPathAs(process.execPath) ? "lecodes" : shellQuote(process.execPath)
+}
+
+/**
+ * Point git's credential helper for the hub at `lecodes hub credential`, in the global config. Two
+ * writes, as `gh auth setup-git` does: an empty helper first resets the list git has collected from
+ * the system config (Git for Windows ships `credential.helper=manager`, which would otherwise be
+ * asked first and pop its own sign-in for the hub), then ours. Idempotent: `--replace-all` drops
+ * the earlier values of the scoped key.
+ */
+export const configureCredentialHelper = (hubUrl: string, command = selfCommand()): { key: string, value: string } => {
+  const key = `credential.${credentialScope(hubUrl)}.helper`
+  const value = `!${command} hub credential`
+  gitOrThrow(["config", "--global", "--replace-all", key, ""])
+  gitOrThrow(["config", "--global", "--add", key, value])
+  return { key, value }
+}
+
+// ---- the hub remote ---------------------------------------------------------------------------
+
+export type HubRemote = { base: string, ns: string, name: string }
+
+/** `https://hub.le.codes/den/demo.git` → `{ base: "https://hub.le.codes", ns: "den", name: "demo" }`. */
+export const parseHubRemote = (remote: string): HubRemote | null => {
+  let u: URL
+  try { u = new URL(remote.trim()) } catch { return null }
+  if (u.protocol !== "https:" && u.protocol !== "http:") return null
+  const parts = u.pathname.replace(/\/+$/, "").split("/").filter(Boolean)
+  if (parts.length !== 2) return null
+  const [ns, file] = parts
+  const name = file.replace(/\.git$/, "")
+  if (!ns || !name) return null
+  return { base: `${u.protocol}//${u.host}`, ns: decodeURIComponent(ns), name: decodeURIComponent(name) }
+}

package/src/platform/api.ts

@@ -250,6 +250,27 @@ export const enableDesignShare = (apiUrl: string, token: string, uuid: string) =
 export const disableDesignShare = (apiUrl: string, token: string, uuid: string) =>
   apiRequest<DesignShare>(apiUrl, `/projects/${uuid}/design/share`, { token, method: "DELETE" })
 
+/* ---- Project keys (Settings → Keys; `env.NAME` in code) -----------------------------------
+ * The platform never answers a value: a key is listed by name, set (or replaced), removed. */
+export type ProjectSecret = {
+  name: string
+  /** false = nobody set it: the code reads it (`readBy`), the platform lists the name for a value to be given. */
+  set: boolean
+  createdAt: string | null
+  updatedAt: string | null
+  /** Which code reads it, as the platform's last compile of the head found. */
+  readBy: "server" | "app" | "both" | null
+}
+
+export const listSecrets = (apiUrl: string, token: string, uuid: string) =>
+  apiRequest<ProjectSecret[]>(apiUrl, `/projects/${uuid}/secrets`, { token })
+
+export const setSecret = (apiUrl: string, token: string, uuid: string, name: string, value: string) =>
+  apiRequest<ProjectSecret>(apiUrl, `/projects/${uuid}/secrets/${encodeURIComponent(name)}`, { token, method: "PUT", body: { value } })
+
+export const removeSecret = (apiUrl: string, token: string, uuid: string, name: string) =>
+  apiRequest<{ ok: true }>(apiUrl, `/projects/${uuid}/secrets/${encodeURIComponent(name)}`, { 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) =>

package/src/project/env.ts

@@ -17,6 +17,8 @@ import { dirname, join, resolve } from "node:path"
  *     subdirectory; a leading ~/ is the home dir;
  *   - the file is never pushed (ignore.ts BUILTIN_PATTERNS) — LECODES_TOKEN and the Android
  *     keystore passwords are exactly what ends up in it.
+ * The same file holds the APP's keys — `STRIPE_KEY=…`, any capital name that is not the CLI's: read
+ * by `readAppEnv` for the project's server (`env.NAME`), never put into process.env.
  * Syntax: KEY=value per line, `export KEY=value` accepted, # comments, single or double quotes
  * (\n, \t and \" unescape inside double quotes only), blank lines ignored.
  */
@@ -86,6 +88,33 @@ export const findEnvRoot = (start: string): string | null => {
   }
 }
 
+/** How the app's own keys are named (the same rule as Settings → Keys on le.codes). */
+export const APP_ENV_NAME = /^[A-Z][A-Z0-9_]{0,63}$/
+
+/** The app's keys among a parsed .env: every `NAME=value` under the key rule that is not the CLI's own
+ *  (`LECODES_*` / `CREATOR_*`). These never reach process.env — they go to the project's server
+ *  (`env.NAME`, the local backend) and, under `PUBLIC_`, to the app bundle; what the platform's
+ *  Settings → Keys is on le.codes. Pure. */
+export const appEnvOf = (parsed: Record<string, string>): Record<string, string> => {
+  const out: Record<string, string> = {}
+  for (const [key, value] of Object.entries(parsed)) {
+    if (KEY_RE.test(key) || !APP_ENV_NAME.test(key)) continue
+    out[key] = value
+  }
+  return out
+}
+
+/** `<root>/.env`'s app keys (`appEnvOf`), `{}` without the file. Never throws. */
+export const readAppEnv = (root: string): Record<string, string> => {
+  try {
+    const file = join(root, ".env")
+    if (!existsSync(file)) return {}
+    return appEnvOf(parseDotEnv(readFileSync(file, "utf8")))
+  } catch {
+    return {}
+  }
+}
+
 /** Load `<project>/.env` into process.env (see the rules above). Returns the keys it set, for
  *  diagnostics. Never throws — a broken .env is skipped, not a reason the CLI can't run. */
 export const loadProjectEnv = (cwd = process.cwd()): string[] => {