@stage5/lumine 0.2.14 → 0.2.16

package/README.md

@@ -7,7 +7,10 @@ npx @stage5/lumine@latest
 npx @stage5/lumine@latest login
 npx @stage5/lumine@latest new "Daily Reflection App"
 npx @stage5/lumine@latest new --title "Daily Reflection App" --description "Private journal with streaks"
+npx @stage5/lumine@latest rename "My New Build Title"
+npx @stage5/lumine@latest rename "New Title" --target 123
 npx @stage5/lumine@latest projects
+npx @stage5/lumine@latest branches 884
 npx @stage5/lumine@latest explore --sort forks
 npx @stage5/lumine@latest reference https://www.twin-kle.com/app/123
 npx @stage5/lumine@latest fork https://www.twin-kle.com/app/123
@@ -33,6 +36,10 @@ pulling the owner's main project creates or reuses your contribution branch and
 checks out that branch locally. Saves go to your branch, so the project owner
 can merge or replace main from Twinkle.
 
+Use `lumine branches <build-url-or-id>` to list the contribution branches you
+can review, including each contributor, branch number, status, and URL. Then use
+`lumine diff <branch-url>` to inspect one branch.
+
 Use `lumine explore` to list public open-source Build apps that can be used as
 examples or starting points. It supports `--search` and `--sort forks`,
 `--sort popular`, or `--sort recent`. Use `lumine reference <build-url-or-id>`

package/lib/api.js

@@ -30,6 +30,21 @@ export async function listOpenSourceBuilds({ options, auth }) {
   return Array.isArray(result.builds) ? result.builds : [];
 }
 
+export async function listContributionBranches({
+  options,
+  auth,
+  buildId,
+  limit,
+}) {
+  const url = new URL(`${options.apiUrl}/build/${buildId}/contributions`);
+  url.searchParams.set("limit", String(limit));
+  return await requestJson({
+    url: url.toString(),
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
 export async function loadBuildMetadata({ options, auth, buildId }) {
   const result = await loadBuildFiles({
     options,
@@ -290,12 +305,26 @@ export async function updateBuildThumbnailUrl({
   auth,
   buildId,
   thumbnailUrl,
+}) {
+  return updateBuildMetadata({
+    options,
+    auth,
+    buildId,
+    patch: { thumbnailUrl },
+  });
+}
+
+export async function updateBuildMetadata({
+  options,
+  auth,
+  buildId,
+  patch,
 }) {
   return requestJson({
     method: "PUT",
     url: `${options.apiUrl}/build/${buildId}`,
     authToken: auth.token,
-    body: { thumbnailUrl },
+    body: patch,
     timeoutMs: options.timeoutMs,
   });
 }

package/lib/commands.js

@@ -31,6 +31,7 @@ import {
   loadBuildVersionFiles,
   loadBuildVersions,
   loadContributionDiff,
+  listContributionBranches,
   loadLumineCliVersionInfo,
   loadOpenSourceBuildFiles,
   maybeCheckForLumineCliUpdate,
@@ -40,6 +41,7 @@ import {
   replaceMainWithContribution,
   resolveBranchBuild,
   saveProjectFiles,
+  updateBuildMetadata,
 } from "./api.js";
 import { assetsCommand, writeAssetsManifest } from "./assets.js";
 import { thumbnailCommand } from "./thumbnail.js";
@@ -75,6 +77,7 @@ import {
   collectProjectLimitFindings,
   findLocalProjectMetadata,
   isIndexHtmlPath,
+  isReadOnlyProjectMetadata,
   isReadOnlyReferenceMetadata,
   removeLocalProjectFilesNotIn,
   stashLocalProjectFilesBeforePull,
@@ -121,10 +124,18 @@ export async function main() {
     await newBuild(options);
     return;
   }
+  if (options.command === "rename") {
+    await renameBuild(options);
+    return;
+  }
   if (options.command === "projects") {
     await projects(options);
     return;
   }
+  if (options.command === "branches") {
+    await branches(options);
+    return;
+  }
   if (options.command === "explore") {
     await explore(options);
     return;
@@ -221,6 +232,59 @@ export async function newBuild(options) {
   printNewBuildResult({ createResult, pullResult: result });
 }
 
+export async function renameBuild(options) {
+  const title = String(options.title || "").trim();
+  if (!title) {
+    throw new Error(
+      'Pass a title: `lumine rename "My New Build Title"` or `lumine rename --title "My New Build Title"`.',
+    );
+  }
+  const auth = await ensureAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:write" });
+  const localProject = await findLocalProjectMetadata(
+    path.resolve(options.dir || process.cwd()),
+  );
+  const buildId = await resolveRequiredBuildIdOrSelected(options, auth, {
+    localProject,
+  });
+  const currentBuild = await loadBuildMetadata({ options, auth, buildId });
+  if (currentBuild.canWrite === false) {
+    throw new Error(`You cannot rename Build #${buildId}.`);
+  }
+  if (Number(currentBuild.contributionRootBuildId || 0) > 0) {
+    throw new Error(
+      "Contribution branches use the original Build title and cannot be renamed.",
+    );
+  }
+  const result = await updateBuildMetadata({
+    options,
+    auth,
+    buildId,
+    patch: { title },
+  });
+  if (result?.success !== true || !result?.build) {
+    throw new Error(result?.error || "Failed to rename the Build.");
+  }
+  const updatedBuild = { ...currentBuild, ...result.build };
+  await saveSelectedBuild({ options, auth, build: updatedBuild });
+  if (
+    localProject?.rootDir &&
+    Number(localProject.metadata?.buildId || 0) === buildId &&
+    !isReadOnlyProjectMetadata(localProject.metadata)
+  ) {
+    await writeProjectMetadata({
+      dir: localProject.rootDir,
+      options,
+      build: updatedBuild,
+      manifest: localProject.metadata.manifest || null,
+      pulledAt: localProject.metadata.pulledAt || null,
+      lastSavedAt: localProject.metadata.lastSavedAt || null,
+      filesHash: localProject.metadata.filesHash || null,
+    });
+  }
+  console.log(`Renamed Build #${buildId} to "${updatedBuild.title}".`);
+}
+
 export async function workspace(options) {
   const auth = await ensureAuth(options);
   const selectedBuild = options.target
@@ -246,6 +310,33 @@ export async function projects(options) {
   printBuildList(builds);
 }
 
+export async function branches(options) {
+  const auth = await resolveAuth(options);
+  const requestedBuildId = await resolveRequiredBuildIdOrSelected(
+    options,
+    auth,
+  );
+  const requestedBuild = await loadBuildMetadata({
+    options,
+    auth,
+    buildId: requestedBuildId,
+  });
+  const rootBuildId =
+    Number(requestedBuild.contributionRootBuildId || 0) ||
+    Number(requestedBuild.id || 0);
+  const rootBuild =
+    rootBuildId === Number(requestedBuild.id || 0)
+      ? requestedBuild
+      : await loadBuildMetadata({ options, auth, buildId: rootBuildId });
+  const result = await listContributionBranches({
+    options,
+    auth,
+    buildId: rootBuildId,
+    limit: options.limit,
+  });
+  printContributionBranches({ result, rootBuild, options });
+}
+
 export async function explore(options) {
   const auth = await resolveAuth(options);
   const builds = await listOpenSourceBuilds({ options, auth });
@@ -1561,6 +1652,34 @@ export function printContributionDiff({ result, build }) {
   }
 }
 
+export function printContributionBranches({ result, rootBuild, options }) {
+  const contributions = Array.isArray(result?.contributions)
+    ? result.contributions
+    : [];
+  console.log(`Branches for ${formatBuildTitle(rootBuild)}:`);
+  if (!contributions.length) {
+    console.log("No contribution branches.");
+    return;
+  }
+  for (const [index, contribution] of contributions.entries()) {
+    const branchNumber = Number(contribution.contributionBranchNumber || 0);
+    const branchLabel = branchNumber
+      ? `branch ${branchNumber}`
+      : `branch #${contribution.id}`;
+    const title = String(contribution.title || "Untitled branch").trim();
+    const contributor = String(contribution.username || "unknown").trim();
+    const status = String(contribution.contributionStatus || "draft").trim();
+    console.log(
+      `${index + 1}. ${title} - ${contributor} - ${branchLabel} (${status})`,
+    );
+    if (branchNumber) {
+      console.log(
+        `   ${options.siteUrl}/build/${Number(rootBuild.id)}/${branchNumber}`,
+      );
+    }
+  }
+}
+
 export function printUpdateFromMainResult({ result, build, dir, mergedFiles }) {
   const branchNumber = Number(build?.contributionBranchNumber || 0) || 0;
   const branchLabel = branchNumber
@@ -1693,10 +1812,16 @@ export function parseArgs(args) {
     quality: raw.quality ? String(raw.quality) : "",
     assetName: raw.name ? String(raw.name) : "",
     out: raw.out ? String(raw.out) : "",
-    target: raw.url || raw.target || positional[0] || "",
+    target:
+      raw.url ||
+      raw.target ||
+      (command === "rename" ? "" : positional[0] || ""),
     title:
       String(
-        raw.title || (command === "new" ? positional.join(" ") : ""),
+        raw.title ||
+          (command === "new" || command === "rename"
+            ? positional.join(" ")
+            : ""),
       ).trim() || "",
     description: Object.prototype.hasOwnProperty.call(raw, "description")
       ? String(raw.description || "").trim()
@@ -1916,7 +2041,9 @@ export function printHelp() {
   lumine whoami
   lumine logout
   lumine new [title]
+  lumine rename [title] [--target <twinkle-build-url-or-id>]
   lumine projects
+  lumine branches [twinkle-build-url-or-id] [--limit <n>]
   lumine explore [search terms]
   lumine select [twinkle-build-url]
   lumine pull [twinkle-build-url]
@@ -1949,7 +2076,10 @@ Examples:
   npx @stage5/lumine@latest
   npx @stage5/lumine@latest login
   npx @stage5/lumine@latest new "Daily Reflection App"
+  npx @stage5/lumine@latest rename "My New Build Title"
+  npx @stage5/lumine@latest rename "New Title" --target 123
   npx @stage5/lumine@latest new --title "Daily Reflection App" --description "Private journal with streaks"
+  npx @stage5/lumine@latest branches 884
   npx @stage5/lumine@latest explore --sort forks
   npx @stage5/lumine@latest reference https://www.twin-kle.com/app/123
   npx @stage5/lumine@latest fork https://www.twin-kle.com/app/123
@@ -1983,9 +2113,10 @@ Options:
   --auth-file <path>    Saved login path
   --auth-token <token>  Override saved login
   --dir <path>          Directory for pulled project files
+  --target <build>      Explicit Build URL or ID for rename (positionals are title-only)
   --main                With pull/versions/restore: target the team project's main
   --version <n>         With pull: read-only checkout of previous save v<n>
-  --title <text>        New Build title
+  --title <text>        Build title for new/rename
   --description <text>  Optional New Build description
   --no-description      Skip the New Build description prompt
   --summary <text>      Save summary

package/lib/constants.js

@@ -308,6 +308,7 @@ export const AGENT_INSTRUCTION_FILES = ["AGENTS.md", "CLAUDE.md"];
 export const MAIN_CHECKOUT_READONLY_COMMANDS = new Set([
   "pull",
   "check",
+  "branches",
   "diff",
   "sdk",
   "select",
@@ -324,7 +325,9 @@ export const COMMANDS = new Set([
   "logout",
   "whoami",
   "new",
+  "rename",
   "projects",
+  "branches",
   "explore",
   "select",
   "pull",

package/lib/workspace.js

@@ -779,14 +779,15 @@ export function resolveProjectDirForSave({ options, localProject }) {
 export function assertLocalProjectCanBeSaved(localProject) {
   const metadata = localProject?.metadata;
   if (!metadata) return;
-  if (metadata.mainCheckout === true) {
+  const readOnlyKind = readOnlyProjectMetadataKind(metadata);
+  if (readOnlyKind === "main") {
     const rootBuildId =
       Number(metadata.buildId || 0) || Number(metadata.build?.id || 0) || 0;
     throw new Error(
       `This is a read-only checkout of main${rootBuildId ? ` for Build ${rootBuildId}` : ""}. Make edits in your branch workspace (\`lumine pull${rootBuildId ? ` ${rootBuildId}` : ""}\`), and run \`lumine update-from-main\` there to bring main's changes into it.`,
     );
   }
-  if (metadata.versionCheckout === true) {
+  if (readOnlyKind === "version") {
     const checkoutBuildId =
       Number(metadata.buildId || 0) || Number(metadata.build?.id || 0) || 0;
     const checkoutVersion = Number(metadata.checkoutVersion || 0) || 0;
@@ -794,7 +795,7 @@ export function assertLocalProjectCanBeSaved(localProject) {
       `This is a read-only checkout of a previous save${checkoutVersion ? ` (v${checkoutVersion})` : ""}${checkoutBuildId ? ` for Build ${checkoutBuildId}` : ""}. To bring this save back, run \`lumine restore${checkoutVersion ? ` ${checkoutVersion}` : " <n>"}\` from the editable workspace, then \`lumine save\`.`,
     );
   }
-  if (isReadOnlyReferenceMetadata(metadata)) {
+  if (readOnlyKind === "reference") {
     const sourceBuildId =
       Number(metadata.reference?.sourceBuildId || 0) ||
       Number(metadata.buildId || 0) ||
@@ -804,7 +805,7 @@ export function assertLocalProjectCanBeSaved(localProject) {
       `This is a read-only Lumine reference${sourceBuildId ? ` for Build ${sourceBuildId}` : ""}. Run \`lumine fork${sourceBuildId ? ` ${sourceBuildId}` : ""}\` to create an editable workspace.`,
     );
   }
-  if (metadata.build?.canWrite === false) {
+  if (readOnlyKind === "server") {
     throw new Error(
       "This Lumine checkout is read-only for the current CLI login. Pull or diff it for review; project-owner branch edits must go through merge or replace-main.",
     );
@@ -819,6 +820,18 @@ export function isReadOnlyReferenceMetadata(metadata) {
   );
 }
 
+export function isReadOnlyProjectMetadata(metadata) {
+  return readOnlyProjectMetadataKind(metadata) !== null;
+}
+
+export function readOnlyProjectMetadataKind(metadata) {
+  if (metadata?.mainCheckout === true) return "main";
+  if (metadata?.versionCheckout === true) return "version";
+  if (isReadOnlyReferenceMetadata(metadata)) return "reference";
+  if (metadata?.build?.canWrite === false) return "server";
+  return null;
+}
+
 export function resolveLocalProjectFilePath({ rootDir, projectPath }) {
   const relativePath = projectPathToRelativePath(projectPath);
   const root = path.resolve(rootDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {

package/sdk/BUILD_SDK_INDEX.md

@@ -1,8 +1,8 @@
 # Build SDK Index
 
-Version: 1.26.3
-Updated: 2026-07-10
-Generated: 2026-07-10T05:52:15.007Z
+Version: 1.27.0
+Updated: 2026-07-21
+Generated: 2026-07-23T05:57:27.486Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -25,7 +25,7 @@ Generated: 2026-07-10T05:52:15.007Z
 - Build app tab mute is enforced by the host runtime automatically for standard media elements and Web Audio connections to AudioContext.destination. Apps with custom audio engines can also observe Twinkle.onAudioMuteChange and check Twinkle.isAudioMuted.
 
 ## Token Scopes
-files:read, user:read, users:read, dailyReflections:read, content:read, sharedDb:read, sharedDb:write, privateDb:read, privateDb:write, files:write, chat:read, chat:write, notifications:read, notifications:write, notifications:emit, reminders:read, reminders:write
+files:read, user:read, users:read, dailyReflections:read, content:read, content:write, sharedDb:read, sharedDb:write, privateDb:read, privateDb:write, files:write, chat:read, chat:write, notifications:read, notifications:write, notifications:emit, reminders:read, reminders:write
 
 ## Namespaces
 
@@ -80,6 +80,14 @@ files:read, user:read, users:read, dailyReflections:read, content:read, sharedDb
   - The parent validates that the target is still a Build preview URL before navigating.
   - External URLs are rejected and do not receive the Build bridge nonce.
   - Example: await Twinkle.app.navigate('./arena.html');
+- async openContent(target) | scopes: none
+  - Returns: { success, url }
+  - Open a recognized Twinkle content page in the parent app from a viewer click or tap.
+  - Call this directly from a user click or tap handler; calls without an active user action are rejected.
+  - The trusted parent displays the canonical destination and requires viewer confirmation before navigating.
+  - Only recognized Twinkle content URLs are accepted. The parent preserves its current signed-in origin when opening the content.
+  - Use navigate() for routes inside the current Build and openContent() for Twinkle subjects, comments, apps, profiles, and other content pages.
+  - Example: await Twinkle.app.openContent('https://www.twin-kle.com/subjects/432');
 
 ### Twinkle.preview
 - getLayout() | scopes: none
@@ -310,6 +318,9 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - Generate or edit an image from a prompt and optional base64/data-URL reference image.
   - Signed-in viewers only.
   - Each successful image generation consumes AI Energy from the signed-in viewer.
+  - Call generateImage directly from an explicit viewer action such as a button click. Calls from page load, timers, background work, or programmatic retries are rejected.
+  - Twinkle shows a host-owned confirmation for every generation. One approval authorizes exactly one request.
+  - Only one image generation may be active at a time. Do not queue or automatically retry cancellation, ai_image_generation_in_progress, USER_ACTIVATION_REQUIRED, or 429 errors.
   - Default engine is openai and default quality is high.
   - The SDK timeout defaults to 390000ms for image generation because high-quality image runs can exceed normal request timing.
   - Pass onStatus to receive real-time stages from the backend: prompt_ready, in_progress, generating, partial_image, completed, and error.
@@ -382,6 +393,19 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Returns: { comments: [{ id, content, filePath, fileName, fileSize, thumbUrl, timeStamp }], cursor? }
   - Returns only the current viewer's own comments on the given subject.
   - Supports cursor-based pagination. Pass cursor from previous response to load more.
+- async getWriteStatus({ subjectId, commentId } = {}) | scopes: content:read
+  - Returns: { writeStatus: { serverNow, subjectCreate, commentCreate, subjectEdit, commentEdit } }
+  - Each operation slice is { cooldownSeconds, availableAt, retryAfterSeconds }.
+  - serverNow is unix seconds so progress bars ignore client clock skew.
+  - Pass subjectId/commentId to include per-target edit cooldowns.
+- async create({ title, description }) | scopes: content:write
+  - Returns: { subject, writeStatus }
+  - Creates a normal site subject (title + description only in v1).
+  - Site-wide durable cooldown: 600s between creates. 429 includes writeStatus.
+- async edit({ subjectId, title, description }) | scopes: content:write
+  - Returns: { subject, writeStatus }
+  - Own subjects only (userId === uploader). Never uses moderator edit rights.
+  - Per-subject edit cooldown: 10s.
 
 ### Twinkle.aiCards
 - async list({ limit, cursor, level, minLevel, maxLevel, quality, userId, hasImage, hasExample } = {}) | scopes: content:read
@@ -468,6 +492,13 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - For subject-poster books that include poster replies, use author: subjectPoster, includeReplies: true, and replyScope: ownThread so the poster's replies to other people do not become pages.
   - Supports cursor-based pagination. Pass cursor from the previous response to load more.
   - Example: const { subjects } = await Twinkle.subjects.search({ query: searchText, limit: 12 }); const subjectId = pickedSubject.id; const page = await Twinkle.subjectComments.list(subjectId, { sortBy: 'oldest', author: 'subjectPoster', includeReplies: true, replyScope: 'ownThread', limit: 50 });
+- async create({ subjectId, content }) | scopes: content:write
+  - Returns: { comment, writeStatus }
+  - Adds a top-level subject comment (book page). Own subject only.
+  - Site-wide durable cooldown: 20s between comment creates. 429 includes writeStatus.
+- async edit({ commentId, content }) | scopes: content:write
+  - Returns: { comment, writeStatus }
+  - Own comments only. Per-comment edit cooldown: 10s.
 
 ### Twinkle.profileComments
 - async getProfileComments({ profileUserId, limit, offset, sortBy, includeReplies, range, since, until } = {}) | scopes: content:read
@@ -540,7 +571,7 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Update a viewer-owned shared row, optionally notifying safe recipients from the canonical write.
   - Updates an entry. Only the entry creator or the build owner can update.
   - data must be a JSON object, max 10 KB.
-  - notify may include eventKey, label, summary, recipients, and target. Supported recipients include { kind: 'sharedDbEntryAuthor', entryId }.
+  - notify may include eventKey, label, summary, recipients, and target. Supported recipients include { kind: 'sharedDbEntryAuthor', entryId } and { kind: 'subjectAuthor', subjectId } (subject must be referenced by this build via a subject-linked sharedDb entry).
 - async deleteEntry(entryId) | scopes: sharedDb:write
   - Returns: { success: true }
   - Deletes an entry. Only the entry creator or the build owner can delete.