@stage5/lumine 0.1.7 → 0.1.9

package/README.md

@@ -5,6 +5,8 @@ Launch Twinkle Lumine builds from any terminal.
 ```bash
 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 projects
 npx @stage5/lumine@latest explore --sort forks
 npx @stage5/lumine@latest reference https://www.twin-kle.com/app/123
@@ -19,6 +21,13 @@ Run `lumine` with no subcommand for the easiest flow: sign in when needed,
 choose one of your owned or team projects, and pull the saved project files into
 a local folder.
 
+Use `lumine new` to create a new Twinkle Build with the same website create
+route used by Build Studio. The CLI asks for a title when one is not passed and
+asks for an optional description. It creates the Build and pulls an editable
+local workspace, but it does not auto-start a Lumine greeting or prompt run, so
+creating a project from the CLI does not spend AI battery. Add project files
+locally, including `/index.html`, then run `lumine save`.
+
 For team projects, Lumine mirrors the website workspace flow: choosing or
 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

package/bin/lumine.js

@@ -119,6 +119,7 @@ const COMMANDS = new Set([
   "login",
   "logout",
   "whoami",
+  "new",
   "projects",
   "explore",
   "select",
@@ -167,6 +168,10 @@ async function main() {
     await whoami(options);
     return;
   }
+  if (options.command === "new") {
+    await newBuild(options);
+    return;
+  }
   if (options.command === "projects") {
     await projects(options);
     return;
@@ -314,6 +319,26 @@ async function whoami(options) {
   );
 }
 
+async function newBuild(options) {
+  const title = await resolveNewBuildTitle(options);
+  const description = await resolveNewBuildDescription(options);
+  const auth = await ensureAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:write" });
+  const createResult = await createBuild({
+    options,
+    auth,
+    title,
+    description,
+  });
+  const buildId = Number(createResult.build?.id || 0);
+  if (!buildId) {
+    throw new Error("Twinkle did not return a created Build.");
+  }
+  const result = await pullBuildFiles({ options, auth, buildId });
+  await saveSelectedBuild({ options, auth, build: result.build });
+  printNewBuildResult({ createResult, pullResult: result });
+}
+
 async function workspace(options) {
   const auth = await ensureAuth(options);
   const selectedBuild = options.target
@@ -774,6 +799,19 @@ async function forkBuild({ options, auth, buildId }) {
   });
 }
 
+async function createBuild({ options, auth, title, description }) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/create`,
+    authToken: auth.token,
+    body: {
+      title,
+      ...(description ? { description } : {}),
+    },
+    timeoutMs: options.timeoutMs,
+  });
+}
+
 async function saveProjectFiles({ options, auth, buildId, files, summary }) {
   return await requestJson({
     method: "PUT",
@@ -1517,6 +1555,9 @@ function printPullResult(result) {
     }
     return;
   }
+  if (result.fileCount === 0) {
+    console.log("No project files yet. Create /index.html before your first save.");
+  }
   console.log('Codex: codex "Read AGENTS.md, then make the requested change."');
   console.log(
     'Claude Code: claude "Read CLAUDE.md, then make the requested change."',
@@ -1529,6 +1570,12 @@ function printPullResult(result) {
   }
 }
 
+function printNewBuildResult({ createResult, pullResult }) {
+  const build = pullResult.build || createResult.build || {};
+  console.log(`Created ${formatBuildTitle(build)}.`);
+  printPullResult(pullResult);
+}
+
 function printReferenceResult(result) {
   const build = result.build || {};
   const sourceBuildId =
@@ -1868,6 +1915,7 @@ function parseArgs(args) {
   const booleanFlags = new Set([
     "noOpen",
     "open",
+    "noDescription",
     "publish",
     "save",
     "noUpdateCheck",
@@ -1898,6 +1946,20 @@ function parseArgs(args) {
   return {
     command,
     target: raw.url || raw.target || positional[0] || "",
+    title:
+      String(
+        raw.title ||
+          (command === "new" ? positional.join(" ") : ""),
+      ).trim() || "",
+    description:
+      Object.prototype.hasOwnProperty.call(raw, "description")
+        ? String(raw.description || "").trim()
+        : null,
+    descriptionProvided: Object.prototype.hasOwnProperty.call(
+      raw,
+      "description",
+    ),
+    noDescription: parseBoolean(raw.noDescription, false),
     searchQuery:
       String(
         raw.search ||
@@ -1990,6 +2052,40 @@ async function resolveRequiredBuildIdOrSelected(
   );
 }
 
+async function resolveNewBuildTitle(options) {
+  const title = String(options.title || "").trim();
+  if (title) return title;
+  if (!input.isTTY || !output.isTTY) {
+    throw new Error('Pass a title: `lumine new "My Build"` or `lumine new --title "My Build"`.');
+  }
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = await rl.question("Build title: ");
+    const normalized = String(answer || "").trim();
+    if (!normalized) {
+      throw new Error("Title is required.");
+    }
+    return normalized;
+  } finally {
+    rl.close();
+  }
+}
+
+async function resolveNewBuildDescription(options) {
+  if (options.noDescription) return null;
+  if (options.descriptionProvided) {
+    return String(options.description || "").trim() || null;
+  }
+  if (!input.isTTY || !output.isTTY) return null;
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = await rl.question("Description (optional): ");
+    return String(answer || "").trim() || null;
+  } finally {
+    rl.close();
+  }
+}
+
 function resolveRequiredBuildId(value) {
   const buildId = resolveBuildReference(value).buildId;
   if (buildId > 0) return buildId;
@@ -2170,6 +2266,7 @@ function printHelp() {
   lumine login
   lumine whoami
   lumine logout
+  lumine new [title]
   lumine projects
   lumine explore [search terms]
   lumine select [twinkle-build-url]
@@ -2186,6 +2283,8 @@ function printHelp() {
 Examples:
   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 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
@@ -2203,6 +2302,9 @@ Options:
   --auth-file <path>    Saved login path
   --auth-token <token>  Override saved login
   --dir <path>          Directory for pulled project files
+  --title <text>        New Build title
+  --description <text>  Optional New Build description
+  --no-description      Skip the New Build description prompt
   --summary <text>      Save summary
   --search <text>       Search public open-source Builds
   --sort <sort>         Sort open-source Builds: forks, popular, recent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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.25.1
-Updated: 2026-05-28
-Generated: 2026-05-28T10:24:18.784Z
+Version: 1.26.1
+Updated: 2026-06-08
+Generated: 2026-06-08T05:37:13.752Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -14,7 +14,7 @@ Generated: 2026-05-28T10:24:18.784Z
 - 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.aiStories for read-only existing AI Story galleries, readers, quizzes, topic chapter indexes, 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.
 - Use Twinkle.world for realtime multiplayer rooms, avatar presence, movement, emotes, and lightweight actions; keep durable MMO state in sharedDb/privateDb.
@@ -93,10 +93,18 @@ files:read, user:read, users:read, dailyReflections:read, content:read, sharedDb
   - Returns: { subscription }
   - Subscribe the current viewer to an app-defined notification channel target.
   - Example: await Twinkle.notifications.subscribe('room.message', { targetKey: 'room:lobby', launchTarget: { view: 'room', roomId: 'lobby' } });
+- async subscribeMany([{ channelKey, targetKey, launchTarget }]) | scopes: notifications:write
+  - Returns: { subscriptions }
+  - Subscribe the current viewer to multiple app-defined notification channel targets in one request.
+  - Example: await Twinkle.notifications.subscribeMany([{ channelKey: 'room.message', targetKey: 'room:lobby', launchTarget: { view: 'room', roomId: 'lobby' } }]);
 - async unsubscribe(channelKey, { targetKey }) | scopes: notifications:write
   - Returns: { subscription: null }
   - Unsubscribe the current viewer from an app-defined notification channel target.
   - Example: await Twinkle.notifications.unsubscribe('room.message', { targetKey: 'room:lobby' });
+- async unsubscribeMany([{ channelKey, targetKey }]) | scopes: notifications:write
+  - Returns: { subscriptions: [], removed }
+  - Unsubscribe the current viewer from multiple app-defined notification channel targets in one request.
+  - Example: await Twinkle.notifications.unsubscribeMany([{ channelKey: 'room.message', targetKey: 'room:lobby' }]);
 - async notifySubscribers(channelKey, { targetKey, eventKey, label, summary, launchTarget, payload }) | scopes: notifications:emit
   - Returns: { sent }
   - Notify viewers who opted into an app-defined channel target, without requiring a sharedDb write.
@@ -216,14 +224,18 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Example: const { card } = await Twinkle.aiCards.get(cardId);
 
 ### Twinkle.aiStories
-- async list({ limit, cursor, difficulty, type, isListening, userId, hasImage, hasQuestions } = {}) | scopes: content:read
+- async list({ limit, cursor, order, difficulty, type, topicKey, 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, 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
+  - List completed existing user-generated AI Stories, optionally filtered by exact level/type/topicKey book and ordered newest or oldest first.
+  - Example: const { stories } = await Twinkle.aiStories.list({ difficulty: 1, type: 'science', topicKey: 'Astronomy', order: 'oldest', limit: 20 });
+- async chapters({ limit, cursor, difficulty, type, topicKey, isListening, userId, hasImage, hasQuestions } = {}) | scopes: content:read
+  - Returns: { chapters: [{ difficulty, type, topicKey, title, sampleTopic, storyCount, readingCount, listeningCount, imageCount, questionCount, latestStoryId, latestTimeStamp }], cursor?, pagination: { limit, hasMore, nextCursor }, filters }
+  - List server-built AI Story books grouped by level, type, and topic, with counts and navigation metadata but no story bodies.
+  - Example: const page = await Twinkle.aiStories.chapters({ limit: 200 });
+- async search({ query, limit, cursor, order, difficulty, type, topicKey, 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, readers, and passage typing games.
-  - Example: const { stories } = await Twinkle.aiStories.search({ query: searchText, hasQuestions: true, limit: 12 });
+  - Search completed existing user-generated AI Stories by topic or story text, optionally within an exact level/type/topicKey book.
+  - Example: const { stories } = await Twinkle.aiStories.search({ query: searchText, difficulty: 2, type: 'history', topicKey: 'Ancient Rome', order: 'oldest', 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 for passage typing, media URLs, and normalized questions when available.