@stage5/lumine 0.2.39 → 0.2.40

package/README.md

@@ -14,6 +14,8 @@ npx @stage5/lumine@latest describe --no-description --target 123
 npx @stage5/lumine@latest upgrade https://www.twin-kle.com/app/123
 npx @stage5/lumine@latest projects
 npx @stage5/lumine@latest branches 884
+npx @stage5/lumine@latest forum 884 --json
+npx @stage5/lumine@latest forum listen 884 --json
 npx @stage5/lumine@latest suggestions 884
 npx @stage5/lumine@latest explore --sort forks
 npx @stage5/lumine@latest reference https://www.twin-kle.com/app/123
@@ -58,6 +60,16 @@ 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 forum [build-url-or-id]` to read the complete canonical Team Forum
+history visible to the current workspace. A project owner reading Main receives
+Main plus every branch's posts and replies. A branch contributor receives that
+branch plus every project-owner post and reply on Main, including older Main
+threads that were not separately broadcast. `--json` returns one complete
+snapshot. `lumine forum listen --json` then polls from the last server-confirmed
+sequence and emits newline-delimited update batches without advancing through a
+partial or failed read. Pass `--cursor <sequence>` only when intentionally
+resuming a previously confirmed cursor; the default starts at the beginning.
+
 Branch contributors can nudge the project owner from their pulled branch with
 `lumine suggest branch [message]` or `lumine suggest thumbnail`. The thumbnail
 command offers the thumbnail currently saved on that branch. Project owners can

package/lib/commands.js

@@ -63,6 +63,7 @@ import { probeUrl, requestJson } from "./http.js";
 import { sdkCommand } from "./sdk.js";
 import { doctorCommand, normalizePreviewUrl } from "./doctor.js";
 import { adminCommand } from "./admin.js";
+import { runBuildForumCommand } from "./forum.js";
 import {
   defaultMainCheckoutDir,
   defaultReferenceDir,
@@ -156,6 +157,10 @@ export async function main() {
     await branches(options);
     return;
   }
+  if (options.command === "forum") {
+    await forum(options);
+    return;
+  }
   if (options.command === "suggest") {
     await sendSuggestion(options);
     return;
@@ -450,6 +455,28 @@ export async function branches(options) {
   printContributionBranches({ result, rootBuild, options });
 }
 
+export async function forum(options) {
+  const explicitAction = ["read", "listen"].includes(
+    String(options.positional?.[0] || ""),
+  );
+  const maximumPositionals = explicitAction ? 2 : 1;
+  if ((options.positional?.length || 0) > maximumPositionals) {
+    throw new Error(
+      "Usage: lumine forum [read|listen] [twinkle-build-url-or-id]",
+    );
+  }
+  if (options.forumCursor === null) {
+    throw new Error("--cursor must be a non-negative integer.");
+  }
+  if (options.forumPollMs === null) {
+    throw new Error("--poll-ms must be an integer from 1000 through 60000.");
+  }
+  const auth = await resolveAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:read" });
+  const buildId = await resolveRequiredBuildIdOrSelected(options, auth);
+  await runBuildForumCommand({ options, auth, buildId });
+}
+
 export async function sendSuggestion(options) {
   const suggestionType = String(options.suggestionAction || "").trim();
   if (suggestionType !== "branch" && suggestionType !== "thumbnail") {
@@ -2233,10 +2260,39 @@ export function parseArgs(args) {
           positional[0] === "list" ? positional[1] || "" : positional[0] || "",
         )
       : "";
+  const forumAction =
+    command === "forum" && ["read", "listen"].includes(positional[0])
+      ? String(positional[0])
+      : "read";
+  const forumTarget =
+    command === "forum"
+      ? String(
+          forumAction === "read" && positional[0] !== "read"
+            ? positional[0] || ""
+            : positional[1] || "",
+        )
+      : "";
+  const forumCursor = Object.prototype.hasOwnProperty.call(raw, "cursor")
+    ? /^\d+$/.test(String(raw.cursor).trim()) &&
+      Number.isSafeInteger(Number(raw.cursor))
+      ? Number(raw.cursor)
+      : null
+    : 0;
+  const forumPollMs = Object.prototype.hasOwnProperty.call(raw, "pollMs")
+    ? /^\d+$/.test(String(raw.pollMs).trim()) &&
+      Number.isSafeInteger(Number(raw.pollMs)) &&
+      Number(raw.pollMs) >= 1000 &&
+      Number(raw.pollMs) <= 60_000
+      ? Number(raw.pollMs)
+      : null
+    : 3000;
 
   return {
     command,
     positional,
+    forumAction,
+    forumCursor,
+    forumPollMs,
     suggestionAction,
     suggestionId:
       command === "suggestions" && suggestionAction !== "list"
@@ -2310,7 +2366,9 @@ export function parseArgs(args) {
         ? ""
         : command === "suggestions"
           ? suggestionListTarget
-          : positional[0] || ""),
+          : command === "forum"
+            ? forumTarget
+            : positional[0] || ""),
     title:
       String(
         raw.title ||
@@ -2568,6 +2626,8 @@ export function printHelp() {
   lumine upgrade [twinkle-build-url-or-id]
   lumine projects
   lumine branches [twinkle-build-url-or-id] [--limit <n>]
+  lumine forum [read] [twinkle-build-url-or-id] [--cursor <sequence>] [--json]
+  lumine forum listen [twinkle-build-url-or-id] [--cursor <sequence>] [--poll-ms <ms>] [--json]
   lumine suggest branch [message] [--target <twinkle-branch-url>]
   lumine suggest thumbnail [--target <twinkle-branch-url>]
   lumine suggestions [twinkle-build-url-or-id]
@@ -2645,6 +2705,8 @@ Examples:
   npx @stage5/lumine@latest upgrade https://www.twin-kle.com/app/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 forum 884 --json
+  npx @stage5/lumine@latest forum listen --json
   npx @stage5/lumine@latest suggest branch "Ready for review"
   npx @stage5/lumine@latest suggest thumbnail
   npx @stage5/lumine@latest suggestions 884
@@ -2696,7 +2758,8 @@ Options:
   --no-description      Skip New description or clear with describe
   --summary <text>      Save summary
   --note <text>         Suggestion, notable-user, or AI-bucket context
-  --cursor <id>         Continue an owner suggestion inbox listing
+  --cursor <id>         Continue suggestions, Forum activity, or admin listing
+  --poll-ms <ms>        Forum listener interval (1000-60000; default 3000)
   --after <date>        Admin subjects: inclusive Unix/ISO creation boundary
   --effort unassigned  Admin subjects: show only unassigned effort
   --unviewed           Admin content lists: retain unviewed and unknown items

package/lib/constants.js

@@ -168,6 +168,17 @@ lumine save --summary "Describe the change"
   need --allow-write and mutate real app data.
 - Owned canonical builds may be published only when the user explicitly asks.
 
+## Team Forum
+
+- Before starting team-project work, run \`lumine forum --json\` and read every
+  canonical post and reply returned for this workspace. Main owners receive
+  Main plus all branch activity; branch contributors receive their branch plus
+  every project-owner post and reply on Main.
+- During longer collaborative work, keep \`lumine forum listen --json\` open in
+  a separate terminal. It resumes only from server-confirmed cursors and emits
+  complete canonical update batches. Do not infer teammate intent from stale
+  files or local state when the Forum provides the current instruction.
+
 ## Team Suggestions
 
 - After saving contribution-branch work, use \`lumine suggest branch "Ready for review"\`
@@ -319,6 +330,7 @@ export const MAIN_CHECKOUT_READONLY_COMMANDS = new Set([
   "pull",
   "check",
   "branches",
+  "forum",
   "diff",
   "sdk",
   "select",
@@ -341,6 +353,7 @@ export const COMMANDS = new Set([
   "upgrade",
   "projects",
   "branches",
+  "forum",
   "suggest",
   "suggestions",
   "explore",

package/lib/forum.js

@@ -0,0 +1,375 @@
+import { requestJson } from "./http.js";
+import { sleep } from "./util.js";
+
+const FORUM_SCOPE_MODES = new Set(["all", "branch", "main"]);
+const FORUM_EVENT_TYPES = new Set(["thread", "reply"]);
+const MAX_FORUM_SNAPSHOT_PAGES = 100_000;
+
+function forumProtocolError(message) {
+  const error = new Error(`Invalid Forum response: ${message}`);
+  error.code = "lumine_forum_protocol_error";
+  error.retryable = false;
+  return error;
+}
+
+function normalizeForumSequence(value, label) {
+  const sequence = Number(value);
+  if (!Number.isSafeInteger(sequence) || sequence < 0) {
+    throw forumProtocolError(`${label} must be a non-negative safe integer`);
+  }
+  return sequence;
+}
+
+function normalizePositiveForumId(value, label) {
+  const id = Number(value);
+  if (!Number.isSafeInteger(id) || id <= 0) {
+    throw forumProtocolError(`${label} must be a positive safe integer`);
+  }
+  return id;
+}
+
+export function buildForumScopeKey(scope) {
+  const mode = String(scope?.mode || "");
+  if (!FORUM_SCOPE_MODES.has(mode)) {
+    throw forumProtocolError("scope.mode is not recognized");
+  }
+  const rootBuildId = normalizePositiveForumId(
+    scope?.rootBuildId,
+    "scope.rootBuildId",
+  );
+  const workspaceBuildId = normalizePositiveForumId(
+    scope?.workspaceBuildId,
+    "scope.workspaceBuildId",
+  );
+  const contributionBuildId = scope?.contributionBuildId
+    ? normalizePositiveForumId(
+        scope.contributionBuildId,
+        "scope.contributionBuildId",
+      )
+    : 0;
+  if (mode === "branch" && contributionBuildId !== workspaceBuildId) {
+    throw forumProtocolError(
+      "branch scope does not match its contribution workspace",
+    );
+  }
+  if (mode !== "branch" && contributionBuildId !== 0) {
+    throw forumProtocolError("non-branch scope has a contribution build");
+  }
+  return `${mode}:${rootBuildId}:${workspaceBuildId}:${contributionBuildId}`;
+}
+
+export async function loadBuildForumPage({
+  options,
+  auth,
+  buildId,
+  afterActivitySeq,
+  snapshotActivitySeq,
+  limit,
+}) {
+  const url = new URL(`${options.apiUrl}/cli/build/${buildId}/forum`);
+  url.searchParams.set("afterActivitySeq", String(afterActivitySeq));
+  if (snapshotActivitySeq > 0) {
+    url.searchParams.set("snapshotActivitySeq", String(snapshotActivitySeq));
+  }
+  url.searchParams.set("limit", String(limit));
+  return await requestJson({
+    url: url.toString(),
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+function validateForumPage({
+  page,
+  buildId,
+  pageCursor,
+  snapshotActivitySeq,
+  expectedScopeKey,
+}) {
+  const projectId = normalizePositiveForumId(page?.project?.id, "project.id");
+  const requestedBuildId = normalizePositiveForumId(
+    page?.requestedBuildId,
+    "requestedBuildId",
+  );
+  if (requestedBuildId !== buildId) {
+    throw forumProtocolError("requestedBuildId changed during the read");
+  }
+  const scopeKey = buildForumScopeKey(page?.scope);
+  if (Number(page?.scope?.rootBuildId) !== projectId) {
+    throw forumProtocolError("project.id does not match scope.rootBuildId");
+  }
+  if (expectedScopeKey && scopeKey !== expectedScopeKey) {
+    throw forumProtocolError(
+      "the authorized Forum workspace changed; restart the listener",
+    );
+  }
+
+  const pageSnapshotActivitySeq = normalizeForumSequence(
+    page?.pagination?.snapshotActivitySeq,
+    "pagination.snapshotActivitySeq",
+  );
+  if (
+    snapshotActivitySeq > 0 &&
+    pageSnapshotActivitySeq !== snapshotActivitySeq
+  ) {
+    throw forumProtocolError("snapshotActivitySeq changed between pages");
+  }
+  if (pageSnapshotActivitySeq < pageCursor) {
+    throw forumProtocolError("snapshotActivitySeq precedes the page cursor");
+  }
+
+  const events = Array.isArray(page?.events) ? page.events : null;
+  if (!events) throw forumProtocolError("events is not an array");
+  const pageLimit = Number(page?.pagination?.limit);
+  if (
+    !Number.isSafeInteger(pageLimit) ||
+    pageLimit < 1 ||
+    pageLimit > 100 ||
+    events.length > pageLimit
+  ) {
+    throw forumProtocolError("pagination.limit does not bound the page");
+  }
+  let lastActivitySeq = pageCursor;
+  for (const event of events) {
+    if (!FORUM_EVENT_TYPES.has(String(event?.type || ""))) {
+      throw forumProtocolError("event.type is not recognized");
+    }
+    normalizePositiveForumId(event?.id, "event.id");
+    normalizePositiveForumId(event?.threadId, "event.threadId");
+    const activitySeq = normalizeForumSequence(
+      event?.activitySeq,
+      "event.activitySeq",
+    );
+    if (
+      activitySeq <= lastActivitySeq ||
+      activitySeq > pageSnapshotActivitySeq
+    ) {
+      throw forumProtocolError(
+        "events are not strictly ordered inside the snapshot",
+      );
+    }
+    lastActivitySeq = activitySeq;
+  }
+
+  if (typeof page?.pagination?.hasMore !== "boolean") {
+    throw forumProtocolError("pagination.hasMore is not boolean");
+  }
+  const nextActivitySeq = normalizeForumSequence(
+    page?.pagination?.nextActivitySeq,
+    "pagination.nextActivitySeq",
+  );
+  if (page.pagination.hasMore) {
+    if (
+      events.length === 0 ||
+      nextActivitySeq !== lastActivitySeq ||
+      nextActivitySeq <= pageCursor ||
+      nextActivitySeq >= pageSnapshotActivitySeq
+    ) {
+      throw forumProtocolError("the next Forum page cursor is not progressive");
+    }
+  } else if (nextActivitySeq !== pageSnapshotActivitySeq) {
+    throw forumProtocolError(
+      "the final Forum page did not confirm the full snapshot cursor",
+    );
+  }
+
+  return {
+    events,
+    nextActivitySeq,
+    pageSnapshotActivitySeq,
+    scopeKey,
+  };
+}
+
+export async function readCompleteBuildForumSnapshot({
+  options,
+  auth,
+  buildId,
+  afterActivitySeq = 0,
+  expectedScopeKey = "",
+  loadPage = loadBuildForumPage,
+  maxPages = MAX_FORUM_SNAPSHOT_PAGES,
+}) {
+  const normalizedBuildId = normalizePositiveForumId(buildId, "buildId");
+  const startingActivitySeq = normalizeForumSequence(
+    afterActivitySeq,
+    "afterActivitySeq",
+  );
+  let pageCursor = startingActivitySeq;
+  let snapshotActivitySeq = 0;
+  let scopeKey = expectedScopeKey;
+  let firstPage = null;
+  const events = [];
+
+  for (let pageNumber = 1; pageNumber <= maxPages; pageNumber += 1) {
+    const page = await loadPage({
+      options,
+      auth,
+      buildId: normalizedBuildId,
+      afterActivitySeq: pageCursor,
+      snapshotActivitySeq,
+      limit: options.limit,
+    });
+    const validated = validateForumPage({
+      page,
+      buildId: normalizedBuildId,
+      pageCursor,
+      snapshotActivitySeq,
+      expectedScopeKey: scopeKey,
+    });
+    if (!firstPage) firstPage = page;
+    if (!scopeKey) scopeKey = validated.scopeKey;
+    snapshotActivitySeq = validated.pageSnapshotActivitySeq;
+    events.push(...validated.events);
+    pageCursor = validated.nextActivitySeq;
+    if (!page.pagination.hasMore) {
+      return {
+        project: firstPage.project,
+        requestedBuildId: normalizedBuildId,
+        scope: firstPage.scope,
+        events,
+        pagination: {
+          fromActivitySeq: startingActivitySeq,
+          snapshotActivitySeq,
+          nextActivitySeq: pageCursor,
+          hasMore: false,
+        },
+        scopeKey,
+      };
+    }
+  }
+
+  throw forumProtocolError("snapshot exceeded the safe pagination bound");
+}
+
+export function isRetryableForumListenerError(error) {
+  if (error?.retryable === false) return false;
+  const status = Number(error?.status || 0);
+  if (!status) return true;
+  return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+
+function formatForumTimestamp(value) {
+  const timestamp = Number(value || 0);
+  if (!Number.isFinite(timestamp) || timestamp <= 0) return "unknown time";
+  return new Date(timestamp * 1000).toISOString();
+}
+
+function formatForumLocation(event) {
+  if (!event?.branch) return "Main";
+  const branchNumber = Number(event.branch.number || 0);
+  return branchNumber > 0
+    ? `Branch #${branchNumber}`
+    : `Branch build #${event.branch.id}`;
+}
+
+function sanitizeForumTerminalText(value) {
+  // Forum text is user-authored. Preserve canonical content in JSON output,
+  // but prevent control, escape, carriage-return, and bidi override bytes from
+  // driving or visually rewriting a human reader's terminal.
+  return String(value || "").replace(
+    /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g,
+    "",
+  );
+}
+
+function printIndented(value) {
+  for (const line of sanitizeForumTerminalText(value).split("\n")) {
+    console.log(`    ${line}`);
+  }
+}
+
+export function printBuildForumSnapshot(snapshot, { json, kind }) {
+  const output = {
+    type: kind,
+    project: snapshot.project,
+    requestedBuildId: snapshot.requestedBuildId,
+    scope: snapshot.scope,
+    events: snapshot.events,
+    cursor: {
+      fromActivitySeq: snapshot.pagination.fromActivitySeq,
+      throughActivitySeq: snapshot.pagination.nextActivitySeq,
+    },
+  };
+  if (json) {
+    console.log(JSON.stringify(output));
+    return;
+  }
+
+  const projectTitle =
+    sanitizeForumTerminalText(snapshot.project?.title).trim() ||
+    `Build #${snapshot.project?.id || snapshot.requestedBuildId}`;
+  console.log(`${projectTitle} — Team Forum`);
+  if (snapshot.events.length === 0) {
+    console.log("No new visible Forum posts or replies.");
+    return;
+  }
+  for (const event of snapshot.events) {
+    const author =
+      sanitizeForumTerminalText(event?.author?.username).trim() ||
+      (event?.author?.role === "lumine" ? "Lumine" : "unknown user");
+    const action = event.type === "reply" ? "replied in" : "opened";
+    console.log(
+      `${formatForumTimestamp(event.createdAt)}  ${formatForumLocation(event)}  ${author} ${action} #${event.threadId} “${sanitizeForumTerminalText(event.threadTitle)}”`,
+    );
+    if (event.replyTo) {
+      const target =
+        sanitizeForumTerminalText(event.replyTo.username).trim() ||
+        `reply #${event.replyTo.replyId}`;
+      console.log(`    ↳ replying to ${target}`);
+    }
+    printIndented(event.body);
+  }
+}
+
+export async function runBuildForumCommand({ options, auth, buildId }) {
+  const listen = options.forumAction === "listen";
+  let cursor = options.forumCursor;
+  let scopeKey = "";
+  let firstSnapshot = true;
+  let consecutiveFailures = 0;
+
+  while (true) {
+    let snapshot;
+    try {
+      snapshot = await readCompleteBuildForumSnapshot({
+        options,
+        auth,
+        buildId,
+        afterActivitySeq: cursor,
+        expectedScopeKey: scopeKey,
+      });
+    } catch (error) {
+      if (!listen || !isRetryableForumListenerError(error)) throw error;
+      consecutiveFailures += 1;
+      const retryDelayMs = Math.min(
+        options.forumPollMs * 2 ** Math.min(consecutiveFailures - 1, 4),
+        30_000,
+      );
+      console.error(
+        `Forum listener temporarily lost contact (${error?.message || error}). Retrying from confirmed cursor ${cursor} in ${retryDelayMs}ms.`,
+      );
+      await sleep(retryDelayMs);
+      continue;
+    }
+
+    if (firstSnapshot || snapshot.events.length > 0) {
+      printBuildForumSnapshot(snapshot, {
+        json: options.json,
+        kind: firstSnapshot ? "forum.snapshot" : "forum.update",
+      });
+    }
+    cursor = snapshot.pagination.nextActivitySeq;
+    scopeKey = snapshot.scopeKey;
+    if (!listen) return;
+
+    if (firstSnapshot) {
+      console.error(
+        `Listening for canonical Forum updates from cursor ${cursor}. Press Ctrl-C to stop.`,
+      );
+    }
+    firstSnapshot = false;
+    consecutiveFailures = 0;
+    await sleep(options.forumPollMs);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.39",
+  "version": "0.2.40",
   "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.32.0
-Updated: 2026-08-02
-Generated: 2026-08-13T00:13:49.827Z
+Version: 1.32.1
+Updated: 2026-08-14
+Generated: 2026-08-14T03:20:48.358Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -20,6 +20,7 @@ Generated: 2026-08-13T00:13:49.827Z
 - Use Twinkle.grammarbles for public Grammarbles question-bank trainer apps and optional signed-in viewer attempt-history filtering.
 - Use Twinkle.chess for chess engine play and analysis; app code still owns chess rules, legal moves, board state, and UI.
 - Use Twinkle.world for realtime multiplayer rooms, avatar presence, movement, emotes, and lightweight actions; world sessions are disposable and durable MMO state belongs in sharedDb/privateDb.
+- Every Twinkle-owned profilePicUrl field returned by the SDK is an absolute HTTPS URL ready for img src, or null. Fields inside app-owned JSON such as sharedDb entry data are not rewritten.
 - Use Twinkle.characters.chat for real Zero/Ciel NPC dialogue with shared room context and AI Energy-aware thinking modes.
 - Twinkle.ai.chat history entries must use { role, content }; map local message.text fields to content before passing history.
 - Live web search is enabled by default for Twinkle.ai.chat and for Medium/High Twinkle.ai.generateObject and Twinkle.characters.chat requests. App authors can pass webSearch: false to disable it for their app. Search uses the provider's live web-search tool and is included in AI Energy usage; structured and character Lite Mode remains tool-free.
@@ -672,6 +673,7 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Always available in the build iframe.
   - World state is ephemeral and heartbeat/TTL based. Use sharedDb/privateDb for durable inventory, XP, quests, ownership, and saved progress — but write those LOW-frequency only (on a user action or an occasional snapshot, never per frame/tick); per-frame/live state stays in world presence or client memory. The server rate-limits sharedDb/privateDb writes and returns 429.
   - Events are room-scoped and include serverTime, seq, eventId, schemaVersion, sessionId, player, and room metadata.
+  - Signed-in player identity comes from the canonical Twinkle user record; player.profilePicUrl is only used for guests and is returned only when it is a valid absolute HTTPS URL.
   - Subscribe to session.ended and catch updatePresence/send errors. Stop using stale handles and reconnect only when Twinkle.world.isSessionEndedError(error) is true; for other Twinkle.world.isRecoverableSessionError(error) cases, drop the transient presence/action and keep the handle.
   - Use updatePresence for live avatar snapshots and send for lightweight actions such as emotes, interactions, and chat bubbles.
   - Throttle movement updates in app code, usually 5-15 updates per second. Do not call updatePresence from every animation frame.