@stage5/lumine 0.2.5 → 0.2.7

package/README.md

@@ -77,6 +77,32 @@ which can differ from a method's `Twinkle.*` SDK return shape — check
 `TWINKLE_BUILD_SDK.md` for SDK return shapes. Methods that change data require
 `--allow-write`.
 
+## Assets and AI image generation
+
+Binary media never lives in the workspace — assets are uploaded to Twinkle and
+referenced from code by URL. `lumine assets upload <file...>` uploads images or
+audio; `lumine assets list` prints your uploads and refreshes
+`.twinkle/assets.json`.
+
+`lumine assets generate "<prompt>" --model <gpt-image-2|nano-banana>` creates
+an AI-generated image asset instead of uploading one. `--model` is required
+(gpt-image-2 = best quality, slower, pricier; nano-banana = Gemini, faster,
+cheaper). Generation spends your Twinkle AI Battery, so the CLI shows the
+estimated cost and asks for confirmation first — non-interactive runs must pass
+`--yes` to consent. `--quality low|medium|high` applies to gpt-image-2 only.
+
+## Thumbnails
+
+`lumine thumbnail set <file>` uploads a jpg/png/webp (max 8MB) as the build's
+thumbnail. `lumine thumbnail capture` screenshots the running app server-side
+and sets the result (add `--out <file>` to keep a local copy).
+`lumine thumbnail generate ["<prompt>"] --model <gpt-image-2|nano-banana>`
+generates an AI image and sets it as the thumbnail (the image is also kept as a
+normal reusable asset); without a prompt the server composes one from the build
+title and description. Replacing an existing thumbnail asks for confirmation;
+pass `--yes` for non-interactive runs. Thumbnail commands are blocked in
+read-only `pull --main` checkouts.
+
 The CLI checks npm for the latest `@stage5/lumine` version on normal commands.
 If the installed copy is outdated, it prints an update warning and records the
 version state in `.twinkle/lumine-project.json` so local agents can tell when

package/lib/api.js

@@ -68,6 +68,29 @@ export async function loadBuildFiles({ options, auth, buildId, includeContent })
   });
 }
 
+export async function loadBuildVersions({ options, auth, buildId, limit }) {
+  const url = new URL(`${options.apiUrl}/cli/build/${buildId}/versions`);
+  if (limit) url.searchParams.set("limit", String(limit));
+  return await requestJson({
+    url: url.toString(),
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+export async function loadBuildVersionFiles({
+  options,
+  auth,
+  buildId,
+  versionNumber,
+}) {
+  return await requestJson({
+    url: `${options.apiUrl}/cli/build/${buildId}/versions/${versionNumber}/files`,
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
 export async function resolveBranchBuild({
   options,
   auth,
@@ -219,17 +242,81 @@ export async function buildApiJson({
   buildApiToken,
   endpointPath,
   body,
+  timeoutMs,
 }) {
   return requestJson({
     method: "POST",
     url: `${options.apiUrl}/build/${buildId}/${endpointPath}`,
     authToken: auth.token,
     body: body || {},
-    timeoutMs: options.timeoutMs,
+    timeoutMs: timeoutMs || options.timeoutMs,
     headers: { "x-build-api-token": buildApiToken },
   });
 }
 
+export async function requestThumbnailSignedUpload({
+  options,
+  auth,
+  buildId,
+  fileSize,
+  contentType,
+}) {
+  return requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/${buildId}/thumbnail`,
+    authToken: auth.token,
+    body: { fileSize, contentType },
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+export async function updateBuildThumbnailUrl({
+  options,
+  auth,
+  buildId,
+  thumbnailUrl,
+}) {
+  return requestJson({
+    method: "PUT",
+    url: `${options.apiUrl}/build/${buildId}`,
+    authToken: auth.token,
+    body: { thumbnailUrl },
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+export async function captureBuildThumbnailPreview({
+  options,
+  auth,
+  buildId,
+  previewPath,
+  timeoutMs,
+}) {
+  return requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/${buildId}/thumbnail/capture-preview`,
+    authToken: auth.token,
+    body: { previewPath },
+    timeoutMs: timeoutMs || options.timeoutMs,
+  });
+}
+
+export async function generateBuildThumbnailRequest({
+  options,
+  auth,
+  buildId,
+  body,
+  timeoutMs,
+}) {
+  return requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/${buildId}/thumbnail/generate`,
+    authToken: auth.token,
+    body: body || {},
+    timeoutMs: timeoutMs || options.timeoutMs,
+  });
+}
+
 export async function fetchAllRuntimeAssets({
   options,
   auth,

package/lib/assets.js

@@ -4,9 +4,12 @@ import readline from "readline/promises";
 import { stdin as input, stdout as output } from "process";
 
 import {
+  ASSET_GENERATE_TIMEOUT_MS,
   ASSET_MIME_BY_EXTENSION,
   ASSET_UPLOAD_CHUNK_BYTES,
   ASSETS_METADATA_FILE,
+  GENERATE_MODEL_ALIASES,
+  GENERATE_QUALITIES,
   PROJECT_METADATA_DIR,
   RUNTIME_ASSET_REFERENCE_PATTERN,
 } from "./constants.js";
@@ -48,9 +51,169 @@ export async function assetsCommand(options) {
     await assetsPrune(options);
     return;
   }
+  if (subcommand === "generate") {
+    await assetsGenerate(options);
+    return;
+  }
   throw new Error(
-    "Usage: lumine assets [list] | lumine assets upload <file...> | lumine assets delete <assetId> | lumine assets prune [--yes]",
+    'Usage: lumine assets [list] | lumine assets upload <file...> | lumine assets generate "<prompt>" --model <gpt-image-2|nano-banana> | lumine assets delete <assetId> | lumine assets prune [--yes]',
+  );
+}
+
+export function resolveGenerateModel(options) {
+  const rawModel = String(options.model || "").trim();
+  const model = GENERATE_MODEL_ALIASES[rawModel];
+  if (!model) {
+    throw new Error(
+      "--model is required: gpt-image-2 (best quality, slower, pricier) or nano-banana (Gemini — faster, cheaper). No default model is applied.",
+    );
+  }
+  const rawQuality = String(options.quality || "").trim();
+  if (rawQuality && !GENERATE_QUALITIES.has(rawQuality)) {
+    throw new Error("--quality must be low, medium, or high.");
+  }
+  if (rawQuality && model !== "gpt-image-2") {
+    throw new Error(
+      "--quality only applies to gpt-image-2; nano-banana has a single quality tier.",
+    );
+  }
+  return { model, quality: rawQuality || null };
+}
+
+export function formatBatteryPercent(energyUnits, fullBatteryUnits) {
+  const total = Number(fullBatteryUnits) || 1_000_000;
+  const percent = ((Number(energyUnits) || 0) / total) * 100;
+  if (percent <= 0) return "~0%";
+  if (percent < 1) return "<1%";
+  return `~${Math.round(percent)}%`;
+}
+
+export function describeGenerateHttpError(error) {
+  const code = String(error?.data?.code || "").trim();
+  if (error?.status === 429 && code === "ai_energy_depleted") {
+    return "Your AI battery is empty. Recharge on Twinkle or try again tomorrow.";
+  }
+  if (error?.status === 409) {
+    return "Another image generation is already running for your account — wait for it to finish, then retry.";
+  }
+  if (code === "build_runtime_file_storage_limit_exceeded") {
+    return `${error?.data?.error || "Storage quota exceeded."} Free space with \`lumine assets prune\`.`;
+  }
+  if (error?.status === 404) {
+    return "Twinkle API does not support asset generation yet (deploy the latest API first).";
+  }
+  return null;
+}
+
+export async function assetsGenerate(options) {
+  const prompt = String(options.positional[1] || "").trim();
+  if (!prompt) {
+    throw new Error(
+      'Usage: lumine assets generate "<prompt>" --model <gpt-image-2|nano-banana> [--quality low|medium|high] [--name <fileName>] [--yes]',
+    );
+  }
+  const { model, quality } = resolveGenerateModel(options);
+  const fileName = String(options.assetName || "").trim();
+  const buildId = await resolveSdkBuildId(options);
+  const auth = await ensureAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:sdk" });
+  const { token } = await mintBuildApiToken({
+    options,
+    auth,
+    buildId,
+    scopes: ["files:read", "files:write"],
+  });
+
+  const requestBody = {
+    prompt,
+    model,
+    ...(quality ? { quality } : {}),
+    ...(fileName ? { fileName } : {}),
+  };
+
+  if (!options.assumeYes) {
+    let estimate = null;
+    try {
+      const estimateResult = await buildApiJson({
+        options,
+        auth,
+        buildId,
+        buildApiToken: token,
+        endpointPath: "api/assets/generate",
+        body: { ...requestBody, estimateOnly: true },
+      });
+      estimate = estimateResult?.estimate || null;
+    } catch (error) {
+      const friendly = describeGenerateHttpError(error);
+      if (friendly) throw new Error(friendly);
+      throw error;
+    }
+    const selectedOption = (estimate?.options || []).find(
+      (option) => option.model === model,
+    );
+    const costLine = selectedOption
+      ? `  Estimated battery cost: ${formatBatteryPercent(selectedOption.energyUnits, estimate?.fullBatteryUnits)} of a full AI battery (~$${Number(selectedOption.estimatedUsd || 0).toFixed(2)})`
+      : "  Estimated battery cost: unavailable";
+    const remainingLine = estimate
+      ? `  Battery remaining now:  ${formatBatteryPercent(estimate.energyRemaining, estimate.fullBatteryUnits)}`
+      : "";
+    console.log(
+      `Generate 1 image with ${model}${quality ? ` (quality ${quality})` : ""}?`,
+    );
+    console.log(costLine);
+    if (remainingLine) console.log(remainingLine);
+    const confirmed = await confirmPrompt("Proceed? [y/N] ");
+    if (confirmed === null) {
+      console.log("Not a TTY — re-run with --yes to generate.");
+      return;
+    }
+    if (!confirmed) {
+      console.log("Aborted. Nothing generated.");
+      return;
+    }
+  }
+
+  console.log("Generating image... this can take a minute.");
+  let result;
+  try {
+    result = await buildApiJson({
+      options,
+      auth,
+      buildId,
+      buildApiToken: token,
+      endpointPath: "api/assets/generate",
+      body: requestBody,
+      timeoutMs: ASSET_GENERATE_TIMEOUT_MS,
+    });
+  } catch (error) {
+    const friendly = describeGenerateHttpError(error);
+    if (friendly) throw new Error(friendly);
+    throw error;
+  }
+  const asset = result?.asset;
+  if (!asset?.url) {
+    throw new Error("Generation finished but no asset was returned.");
+  }
+  console.log(
+    `Generated ${asset.originalFileName || asset.fileName} (${formatBytes(asset.sizeBytes)}) as asset #${asset.id}`,
   );
+  console.log(`  ${asset.url}`);
+  const remaining = result?.aiUsagePolicy?.energyRemaining;
+  if (Number.isFinite(Number(remaining))) {
+    console.log(
+      `Battery remaining: ${formatBatteryPercent(Number(remaining), result?.aiUsagePolicy?.fullBatteryUnits)}`,
+    );
+  }
+  console.log(
+    "Reference this URL from your project files (e.g. a src/assets.js module).",
+  );
+  await refreshWorkspaceAssetsManifest({
+    options,
+    auth,
+    buildId,
+    buildApiToken: token,
+  });
+  return asset;
 }
 
 export async function assetsList(options) {