@stage5/lumine 0.1.4 → 0.1.6

package/README.md

@@ -49,6 +49,12 @@ Reference folders are marked `readOnly` in `.twinkle/lumine-project.json`.
 Running `lumine save` from a reference folder is blocked; fork the source Build
 first if you want an editable workspace.
 
+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
+they should rerun with `npx @stage5/lumine@latest`. Use `--no-update-check` to
+skip that advisory network check.
+
 After pulling a project, run an agent from the pulled folder:
 
 ```bash

package/bin/lumine.js

@@ -8,12 +8,14 @@ import { stdin as input, stdout as output } from "process";
 
 const DEFAULT_API_URL = "https://api.twinkle.network";
 const DEFAULT_SITE_URL = "https://www.twin-kle.com";
+const DEFAULT_NPM_REGISTRY_URL = "https://registry.npmjs.org";
 const DEFAULT_AUTH_FILE = path.join(
   os.homedir(),
   ".twinkle",
   "lumine-cli-auth.json",
 );
 const DEFAULT_TIMEOUT_MS = 20000;
+const UPDATE_CHECK_TIMEOUT_MS = 1500;
 const DEFAULT_PROJECT_LIMIT = 50;
 const PROJECT_METADATA_DIR = ".twinkle";
 const PROJECT_METADATA_FILE = "lumine-project.json";
@@ -35,6 +37,7 @@ const BUNDLED_SDK_REFERENCE_URL = new URL(
   "../sdk/BUILD_SDK_INDEX.md",
   import.meta.url,
 );
+const PACKAGE_METADATA_URL = new URL("../package.json", import.meta.url);
 const SDK_REFERENCE_FALLBACK = `${LUMINE_SDK_REFERENCE_MARKER}
 # Twinkle Build SDK Reference
 
@@ -47,6 +50,8 @@ Use these current source-of-truth rules:
 - Use Twinkle.privateDb for simple private per-user preferences, drafts, settings, and small JSON state.
 - Use Twinkle.userDb only for advanced private SQLite tables, indexes, many rows, filtered queries, or aggregates.
 - Use Twinkle.sharedDb for shared multi-user JSON data.
+- Use Twinkle.aiCards.list/search/get for existing public AI Card words, exampleText sentence material, and word levels.
+- Use Twinkle.aiStories.list/search/get for existing AI Story passage text, story media, and questions.
 - Use Twinkle.ai.chat with history entries shaped as { role, content }, not { text }.
 - Use Twinkle.preview for canvas, WebGL, Three.js, fullscreen, and game layout.
 - Prefer existing documented Twinkle.* methods over guessing names from old code.
@@ -61,6 +66,7 @@ Lumine CLI as the source of truth for saving this workspace back to Twinkle.
 
 - Read .twinkle/lumine-project.json before changing files.
 - Treat build.canWrite, build.canPublish, and build.contributionRootBuildId as authoritative.
+- If lumineCli.updateAvailable is true, ask the user to rerun with npx @stage5/lumine@latest before saving.
 - Read ${SDK_REFERENCE_FILE} before adding, removing, or changing any Twinkle.* SDK calls.
 - If build.canWrite is false, do not save changes.
 - If build.canPublish is false or contributionRootBuildId is set, this checkout is a contribution branch. Save only to this branch and do not run lumine launch or lumine save --publish.
@@ -102,6 +108,7 @@ the workspace to save.
 ## Source Of Truth
 
 - Read .twinkle/lumine-project.json before using these files.
+- If lumineCli.updateAvailable is true, ask the user to rerun with npx @stage5/lumine@latest before borrowing patterns.
 - If metadata.readOnly is true or build.role is "reference", do not run lumine save from this directory.
 - To start from this Build, run lumine fork with the source build id and edit the forked workspace.
 - Do not edit another local checkout to bypass reference read-only semantics.
@@ -132,10 +139,14 @@ main().catch((error) => {
 
 async function main() {
   const options = parseArgs(process.argv.slice(2));
+  options.lumineCli = await loadLumineCliVersionInfo({ options });
   if (options.help) {
     printHelp();
     return;
   }
+  if (options.updateCheck) {
+    await maybeCheckForLumineCliUpdate({ options });
+  }
 
   if (options.command === "workspace") {
     await workspace(options);
@@ -1117,6 +1128,7 @@ async function writeProjectMetadata({
           : null,
         apiUrl: options.apiUrl,
         siteUrl: options.siteUrl,
+        lumineCli: serializeLumineCliMetadata(options),
         manifest,
         pulledAt,
         lastSavedAt,
@@ -1164,6 +1176,7 @@ async function writeReferenceMetadata({
         },
         apiUrl: options.apiUrl,
         siteUrl: options.siteUrl,
+        lumineCli: serializeLumineCliMetadata(options),
         manifest,
         pulledAt,
       },
@@ -1258,6 +1271,20 @@ async function saveSelectedBuild({ options, auth, build }) {
   });
 }
 
+function serializeLumineCliMetadata(options) {
+  const info = options.lumineCli || {};
+  return {
+    packageName: info.packageName || "@stage5/lumine",
+    version: info.version || null,
+    latestVersion: info.latestVersion || null,
+    updateAvailable: Boolean(info.updateAvailable),
+    updateCommand: info.updateCommand || "npx @stage5/lumine@latest",
+    checkedAt: info.checkedAt || null,
+    checkFailed: Boolean(info.checkFailed),
+    checkSkipped: Boolean(info.checkSkipped),
+  };
+}
+
 function printBuildList(builds) {
   if (!builds.length) {
     console.log("No owned or team Twinkle builds found.");
@@ -1503,6 +1530,117 @@ async function request({ method = "GET", url, authToken, body, timeoutMs }) {
   }
 }
 
+async function loadLumineCliVersionInfo({ options }) {
+  const packageMetadata = await loadLocalPackageMetadata();
+  const packageName = packageMetadata.name || "@stage5/lumine";
+  const version = packageMetadata.version || null;
+  return {
+    packageName,
+    version,
+    latestVersion: null,
+    updateAvailable: false,
+    updateCommand: `npx ${packageName}@latest`,
+    checkedAt: null,
+    checkFailed: false,
+    checkSkipped: !options.updateCheck,
+  };
+}
+
+async function loadLocalPackageMetadata() {
+  try {
+    const rawPackage = await fs.readFile(PACKAGE_METADATA_URL, "utf8");
+    const parsedPackage = JSON.parse(rawPackage);
+    return {
+      name: String(parsedPackage?.name || "").trim(),
+      version: String(parsedPackage?.version || "").trim(),
+    };
+  } catch {
+    return {
+      name: "@stage5/lumine",
+      version: null,
+    };
+  }
+}
+
+async function maybeCheckForLumineCliUpdate({ options }) {
+  const info = options.lumineCli || (await loadLumineCliVersionInfo({ options }));
+  const checkedAt = new Date().toISOString();
+  if (!info.packageName || !info.version) {
+    options.lumineCli = {
+      ...info,
+      checkedAt,
+      checkFailed: true,
+      checkSkipped: false,
+    };
+    return;
+  }
+
+  try {
+    const latestVersion = await loadLatestPackageVersion({
+      packageName: info.packageName,
+      registryUrl: options.npmRegistryUrl,
+    });
+    const updateAvailable = isNewerVersion(latestVersion, info.version);
+    options.lumineCli = {
+      ...info,
+      latestVersion,
+      updateAvailable,
+      checkedAt,
+      checkFailed: false,
+      checkSkipped: false,
+    };
+    if (updateAvailable) {
+      printLumineCliUpdateWarning(options.lumineCli);
+    }
+  } catch {
+    options.lumineCli = {
+      ...info,
+      checkedAt,
+      checkFailed: true,
+      checkSkipped: false,
+    };
+  }
+}
+
+async function loadLatestPackageVersion({ packageName, registryUrl }) {
+  const encodedPackageName = encodeURIComponent(packageName);
+  const result = await requestJson({
+    url: `${registryUrl}/${encodedPackageName}/latest`,
+    timeoutMs: UPDATE_CHECK_TIMEOUT_MS,
+  });
+  const latestVersion = String(result?.version || "").trim();
+  if (!latestVersion) {
+    throw new Error("No latest package version returned");
+  }
+  return latestVersion;
+}
+
+function isNewerVersion(latestVersion, currentVersion) {
+  const latestParts = parseSemverParts(latestVersion);
+  const currentParts = parseSemverParts(currentVersion);
+  if (!latestParts || !currentParts) return false;
+  for (let index = 0; index < 3; index += 1) {
+    if (latestParts[index] > currentParts[index]) return true;
+    if (latestParts[index] < currentParts[index]) return false;
+  }
+  return false;
+}
+
+function parseSemverParts(value) {
+  const match = String(value || "")
+    .trim()
+    .match(/^v?(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+function printLumineCliUpdateWarning(info) {
+  console.error(
+    `lumine: update available for ${info.packageName}: ${info.version} -> ${info.latestVersion}.`,
+  );
+  console.error(`lumine: run \`${info.updateCommand}\` to use the latest CLI.`);
+}
+
 function parseArgs(args) {
   const firstArg = args[0] || "";
   const firstArgIsCommand =
@@ -1517,7 +1655,13 @@ function parseArgs(args) {
   const rest = command === "workspace" ? args : args.slice(1);
   const raw = {};
   const positional = [];
-  const booleanFlags = new Set(["noOpen", "open", "publish", "save"]);
+  const booleanFlags = new Set([
+    "noOpen",
+    "open",
+    "publish",
+    "save",
+    "noUpdateCheck",
+  ]);
 
   for (let i = 0; i < rest.length; i += 1) {
     const arg = rest[i];
@@ -1557,6 +1701,13 @@ function parseArgs(args) {
     siteUrl: trimTrailingSlash(
       String(raw.siteUrl || process.env.TWINKLE_SITE_URL || DEFAULT_SITE_URL),
     ),
+    npmRegistryUrl: trimTrailingSlash(
+      String(
+        raw.npmRegistryUrl ||
+          process.env.LUMINE_NPM_REGISTRY_URL ||
+          DEFAULT_NPM_REGISTRY_URL,
+      ),
+    ),
     authFile: String(
       raw.authFile || process.env.TWINKLE_CLI_AUTH_FILE || DEFAULT_AUTH_FILE,
     ),
@@ -1579,6 +1730,7 @@ function parseArgs(args) {
     openBrowser: parseBoolean(raw.noOpen, false)
       ? false
       : parseBoolean(raw.open, true),
+    updateCheck: parseBoolean(raw.noUpdateCheck, false) ? false : true,
     timeoutMs: Math.max(
       Number(raw.timeoutMs || process.env.TWINKLE_TIMEOUT_MS) ||
         DEFAULT_TIMEOUT_MS,
@@ -1802,6 +1954,7 @@ Options:
   --publish             Publish after saving
   --save                Save local files before launch
   --limit <number>      Number of projects to show
+  --no-update-check     Skip the npm latest-version check
   --no-open             Print the approval URL without opening a browser
 `);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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.24.0
-Updated: 2026-05-26
-Generated: 2026-05-26T10:20:06.718Z
+Version: 1.25.0
+Updated: 2026-05-28
+Generated: 2026-05-28T09:34:12.631Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -13,6 +13,7 @@ Generated: 2026-05-26T10:20:06.718Z
 - Use Twinkle.leaderboards for public Build scoreboards. Signed-in viewers are ranked by Twinkle username; guests can submit with a display name.
 - Use Twinkle.sharedDb for custom shared multi-user structured data, guestbooks, votes, and append-only run history.
 - Use Twinkle.subjects.search for in-app subject pickers. Twinkle.mount remains an optional host-provided preselection/context shortcut, not a data API.
+- Use Twinkle.aiCards for read-only existing public AI Card words and example texts, including word levels for typing games.
 - Use Twinkle.aiStories for read-only existing AI Story galleries, readers, quizzes, and remix tools.
 - 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.
@@ -200,18 +201,32 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
 - async getSubjectComments(subjectId, { limit, cursor } = {}) | scopes: content:read
   - Returns: { comments: [{ id, content, filePath, fileName, fileSize, thumbUrl, timeStamp }], cursor? }
 
+### Twinkle.aiCards
+- async list({ limit, cursor, level, minLevel, maxLevel, quality, userId, hasImage, hasExample } = {}) | scopes: content:read
+  - Returns: { cards: [{ id, contentType, contentId, word, text, exampleText, prompt, level, wordLevel, quality, style, imagePath, imageUrl, creatorId, ownerId, username, profilePicUrl, timeStamp, lastInteraction }], cursor?, pagination: { limit, hasMore, nextCursor }, filters }
+  - List existing public AI Cards newest first, including each card word, example sentence text, word level, and quality.
+  - Example: const { cards } = await Twinkle.aiCards.list({ level: 2, hasExample: true, limit: 20 });
+- async search({ query, limit, cursor, level, minLevel, maxLevel, quality, userId, hasImage, hasExample } = {}) | scopes: content:read
+  - Returns: { cards: [{ id, contentType, contentId, word, text, exampleText, prompt, level, wordLevel, quality, style, imagePath, imageUrl, creatorId, ownerId, username, profilePicUrl, timeStamp, lastInteraction }], cursor?, pagination: { limit, hasMore, nextCursor }, filters }
+  - Search existing public AI Cards by word, with optional level and quality filters.
+  - Example: const { cards } = await Twinkle.aiCards.search({ query: searchText, minLevel: 1, maxLevel: 3, hasExample: true, limit: 12 });
+- async get(cardId) | scopes: content:read
+  - Returns: { card: { id, contentType, contentId, word, text, exampleText, prompt, level, wordLevel, quality, style, imagePath, imageUrl, creatorId, ownerId, username, profilePicUrl, timeStamp, lastInteraction } }
+  - Fetch one existing public AI Card by id, including word, example text, and level metadata.
+  - Example: const { card } = await Twinkle.aiCards.get(cardId);
+
 ### Twinkle.aiStories
 - async list({ limit, cursor, difficulty, type, isListening, userId, hasImage, hasQuestions } = {}) | scopes: content:read
   - Returns: { stories: [{ id, contentType, contentId, topic, topicKey, type, story, explanation, difficulty, isListening, imagePath, imageUrl, audioPath, audioUrl, questions, questionsBy, hasImage, hasQuestions, userId, username, profilePicUrl, timeStamp }], cursor?, pagination: { limit, hasMore, nextCursor }, filters }
-  - List completed existing user-generated AI Stories newest first for galleries, quiz apps, readers, and image/story collections.
+  - List completed existing user-generated AI Stories newest first for galleries, quiz apps, readers, passage typing, and image/story collections.
   - Example: const { stories } = await Twinkle.aiStories.list({ hasImage: true, hasQuestions: true, limit: 12 });
 - async search({ query, limit, cursor, difficulty, type, isListening, userId, hasImage, hasQuestions } = {}) | scopes: content:read
   - Returns: { stories: [{ id, contentType, contentId, topic, topicKey, type, story, explanation, difficulty, isListening, imagePath, imageUrl, audioPath, audioUrl, questions, questionsBy, hasImage, hasQuestions, userId, username, profilePicUrl, timeStamp }], cursor?, pagination: { limit, hasMore, nextCursor }, filters }
-  - Search completed existing user-generated AI Stories by topic or story text for galleries, quizzes, and readers.
+  - Search completed existing user-generated AI Stories by topic or story text for galleries, quizzes, readers, and passage typing games.
   - Example: const { stories } = await Twinkle.aiStories.search({ query: searchText, hasQuestions: true, limit: 12 });
 - async get(storyId) | scopes: content:read
   - Returns: { story: { id, contentType, contentId, topic, topicKey, type, story, explanation, difficulty, isListening, imagePath, imageUrl, audioPath, audioUrl, questions, questionsBy, hasImage, hasQuestions, userId, username, profilePicUrl, timeStamp } }
-  - Fetch one completed existing AI Story by id, including story text, media URLs, and normalized questions when available.
+  - Fetch one completed existing AI Story by id, including story text for passage typing, media URLs, and normalized questions when available.
   - Example: const { story } = await Twinkle.aiStories.get(storyId);
 
 ### Twinkle.grammarbles
@@ -302,8 +317,10 @@ world.updatePresence({ x, y, z, facing });
 ### Twinkle.reflections
 - async getDailyReflections({ userIds, cursor, lastId, limit } = {}) | scopes: dailyReflections:read
   - Returns: { reflections: [{ id, userId, response, questionId, submittedAt, sharedAt, username, profilePicUrl, question }], cursor? }
+  - Read only currently public Daily Reflection shares. response is the exact text the author chose to share publicly, never an unshared raw/private answer.
 - async getDailyReflectionsByUser(userId, { cursor, lastId, limit } = {}) | scopes: dailyReflections:read
   - Returns: { reflections: [{ id, userId, response, questionId, submittedAt, sharedAt, username, profilePicUrl, question }], cursor? }
+  - Read one user's currently public Daily Reflection shares. response is the exact text the author chose to share publicly, never an unshared raw/private answer.
 
 ### Twinkle.privateDb
 - async get(key) | scopes: privateDb:read
@@ -385,6 +402,37 @@ const { comments, pagination } = await Twinkle.subjectComments.list(subjectId, {
 console.log('Title:', subject.title, 'Pages:', comments.length, 'hasMore:', pagination?.hasMore);
 ```
 
+### Typing game content from AI Cards and AI Stories
+Use AI Card words for word mode, AI Card exampleText for sentence mode, and AI Story story text for passage mode. Keep leaderboards separate per mode.
+Keywords: typing, ai cards, ai stories, words, sentences, passages, leaderboard
+
+```js
+const wordPage = await Twinkle.aiCards.list({ level: 1, hasExample: true, limit: 20 });
+const wordTargets = wordPage.cards.map((card) => ({
+  text: card.word,
+  level: card.level,
+  sourceId: card.id
+}));
+const sentenceTargets = wordPage.cards.map((card) => ({
+  text: card.exampleText,
+  level: card.level,
+  sourceId: card.id
+}));
+
+const passagePage = await Twinkle.aiStories.list({ difficulty: 2, limit: 10 });
+const passageTargets = passagePage.stories.map((story) => ({
+  text: story.story,
+  level: story.difficulty,
+  sourceId: story.id
+}));
+
+await Twinkle.leaderboards.submit({
+  boardKey: 'arcade-typing-words',
+  score: finalScore,
+  meta: { mode: 'words', level }
+});
+```
+
 ### Search AI Stories for a quiz app
 Use existing user-generated AI Stories as source material for visual galleries, readers, and question-based games.
 Keywords: ai stories, story, quiz, questions, image, gallery