@stage5/lumine 0.2.13 → 0.2.15

package/README.md

@@ -7,6 +7,8 @@ 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 explore --sort forks
 npx @stage5/lumine@latest reference https://www.twin-kle.com/app/123
@@ -40,7 +42,14 @@ to pull source files into a read-only reference folder, or
 `lumine fork <build-url-or-id>` to create your own editable fork and pull it
 locally.
 
-After editing pulled files, run `lumine save` from that folder. The CLI saves
+After editing pulled files, run `lumine save` from that folder. Workspaces record
+a `filesHash` in `.twinkle/lumine-project.json` when you pull or save; the next
+save sends that hash so the server can reject a stale checkout instead of
+silently overwriting newer files. Saves from a folder with no `filesHash` are
+refused unless you pass `--force` (intentional overwrite). Prefer
+`lumine pull` to resync before saving if the folder might be out of date.
+
+The CLI saves
 through Twinkle's normal workspace project-file route, creates a project artifact
 version, records the same save metadata, and marks public builds as having
 unpublished changes. For projects you own, run `lumine launch` to publish the

package/lib/api.js

@@ -139,6 +139,7 @@ export async function saveProjectFiles({
   files,
   summary,
   baseFilesHash,
+  force = false,
 }) {
   return await requestJson({
     method: "PUT",
@@ -152,6 +153,9 @@ export async function saveProjectFiles({
       // reject it instead of silently rewinding newer state (e.g. a branch
       // merged into main after our pull).
       ...(baseFilesHash ? { baseFilesHash } : {}),
+      // Intentional overwrite of a non-empty project without a base claim.
+      // Required when the workspace has no filesHash (old/stale checkout).
+      ...(force ? { force: true } : {}),
     },
     timeoutMs: options.timeoutMs,
   });
@@ -286,12 +290,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

@@ -40,6 +40,7 @@ import {
   replaceMainWithContribution,
   resolveBranchBuild,
   saveProjectFiles,
+  updateBuildMetadata,
 } from "./api.js";
 import { assetsCommand, writeAssetsManifest } from "./assets.js";
 import { thumbnailCommand } from "./thumbnail.js";
@@ -121,6 +122,10 @@ export async function main() {
     await newBuild(options);
     return;
   }
+  if (options.command === "rename") {
+    await renameBuild(options);
+    return;
+  }
   if (options.command === "projects") {
     await projects(options);
     return;
@@ -221,6 +226,58 @@ 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
+  ) {
+    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
@@ -509,13 +566,36 @@ export async function save(options) {
   const files = await collectProjectFiles(dir);
   assertProjectFilesWithinLimits(files);
   // Only claim a base snapshot when this workspace was pulled from the same
-  // build we are saving to; otherwise the save stays unguarded (old behavior).
+  // build we are saving to. Missing filesHash used to mean "unguarded save",
+  // which let stale checkouts silently rewind newer server versions — refuse
+  // that path unless --force is explicit.
+  const metadataBuildId = Number(localProject?.metadata?.buildId || 0);
+  const metadataFilesHash =
+    typeof localProject?.metadata?.filesHash === "string" &&
+    localProject.metadata.filesHash.trim()
+      ? localProject.metadata.filesHash.trim()
+      : null;
   const baseFilesHash =
-    !options.force &&
-    Number(localProject?.metadata?.buildId || 0) === Number(buildId) &&
-    typeof localProject?.metadata?.filesHash === "string"
-      ? localProject.metadata.filesHash
+    !options.force && metadataBuildId === Number(buildId) && metadataFilesHash
+      ? metadataFilesHash
       : null;
+  if (!options.force && !baseFilesHash) {
+    throw new Error(
+      [
+        "Save refused: this workspace has no filesHash (server snapshot token).",
+        "That usually means an old or stale checkout that never recorded what",
+        "it was based on — saving it would overwrite the server without a guard.",
+        "Run `lumine pull` to sync with the server (local edits are preserved),",
+        "then save again. To intentionally overwrite the server with these",
+        "local files, re-run with --force.",
+      ].join("\n"),
+    );
+  }
+  if (options.force && !baseFilesHash) {
+    console.error(
+      "lumine: warning — saving with --force and no filesHash; this overwrites the server project with local files and skips the stale-workspace guard.",
+    );
+  }
   let result;
   try {
     result = await saveProjectFiles({
@@ -525,6 +605,7 @@ export async function save(options) {
       files,
       summary: options.summary || DEFAULT_SAVE_SUMMARY,
       baseFilesHash,
+      force: Boolean(options.force),
     });
   } catch (error) {
     if (error?.data?.code === "build_project_files_stale") {
@@ -537,6 +618,17 @@ export async function save(options) {
         ].join("\n"),
       );
     }
+    if (error?.data?.code === "build_project_files_base_required") {
+      throw new Error(
+        [
+          "Save rejected: the server requires a filesHash base for this project",
+          "(non-empty projects cannot be saved from a workspace that never",
+          "recorded its server snapshot).",
+          "Run `lumine pull` to establish a base, then save again,",
+          "or re-run with --force to overwrite deliberately.",
+        ].join("\n"),
+      );
+    }
     throw error;
   }
   build = result.build ||
@@ -1658,10 +1750,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()
@@ -1881,6 +1979,7 @@ export function printHelp() {
   lumine whoami
   lumine logout
   lumine new [title]
+  lumine rename [title] [--target <twinkle-build-url-or-id>]
   lumine projects
   lumine explore [search terms]
   lumine select [twinkle-build-url]
@@ -1914,6 +2013,8 @@ 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 explore --sort forks
   npx @stage5/lumine@latest reference https://www.twin-kle.com/app/123
@@ -1948,13 +2049,14 @@ 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
-  --force               Save even if the server files changed since this workspace was pulled
+  --force               Overwrite server files even if this workspace is stale or missing filesHash
   --search <text>       Search public open-source Builds
   --sort <sort>         Sort open-source Builds: forks, popular, recent
   --publish             Publish after saving

package/lib/constants.js

@@ -143,6 +143,12 @@ Lumine CLI as the source of truth for saving this workspace back to Twinkle.
 
 - Edit only project files in this workspace.
 - Keep /index.html or /index.htm as the entry file.
+- Before editing an existing project, confirm \`.twinkle/lumine-project.json\`
+  has a \`filesHash\` and matches the build you intend. If the folder may be
+  stale (old pull, missing files, fewer files than last known save), run
+  \`lumine pull\` first — never \`lumine save\` from a guessed/old checkout.
+  Saves without \`filesHash\` are refused (use \`--force\` only for deliberate
+  overwrites). A stale save can delete newer server files.
 - Run lumine save from this folder after edits, with a short summary:
 
 \`\`\`bash
@@ -318,6 +324,7 @@ export const COMMANDS = new Set([
   "logout",
   "whoami",
   "new",
+  "rename",
   "projects",
   "explore",
   "select",

package/lib/workspace.js

@@ -597,7 +597,8 @@ export async function writeProjectMetadata({
         lastSavedAt,
         // Server-issued hash of the project files this workspace is based on.
         // `lumine save` sends it back so a stale workspace cannot silently
-        // rewind newer server state; null means "unknown" (unguarded save).
+        // rewind newer server state. Missing/null refuses save unless --force
+        // (server also rejects unguarded saves onto non-empty projects).
         filesHash: typeof filesHash === "string" ? filesHash : null,
       },
       null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "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.