@stage5/lumine 0.1.9 → 0.2.0

package/README.md

@@ -58,6 +58,25 @@ 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.
 
+## Inspecting Build SDK data
+
+`lumine sdk call <namespace.method> '<jsonArgs>'` calls a build's data SDK
+endpoint with your login and prints the response, so you can inspect real data
+and measure latency while building. Run `lumine sdk list` to see callable
+methods. The JSON args are sent as the request body (shapes follow
+`TWINKLE_BUILD_SDK.md`).
+
+```bash
+lumine sdk call aiStories.chapters '{"limit": 5}'
+lumine sdk call aiStories.list '{"difficulty": 1}' --repeat 5 --build 1374
+```
+
+It targets the build in the current workspace, or pass `--build <id>`. Add
+`--repeat <n>` for min/avg/max latency. Output is the raw endpoint response,
+which can differ from a method's `Twinkle.*` SDK return shape — check
+`TWINKLE_BUILD_SDK.md` for SDK return shapes. Methods that change data require
+`--allow-write`.
+
 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

package/bin/lumine.js

@@ -83,6 +83,12 @@ lumine save --summary "Describe the change"
 \`\`\`
 
 - Run lumine check before launch when possible.
+- Use \`lumine sdk call <namespace.method> '{...}'\` to inspect real endpoint
+  data and measure latency (add --repeat <n>); \`lumine sdk list\` shows
+  callable methods. It prints the raw HTTP endpoint response, which can differ
+  from a method's Twinkle.* SDK return shape (some wrappers unwrap or rename
+  fields) — use ${SDK_REFERENCE_FILE} for SDK return shapes. Write methods
+  need --allow-write and mutate real app data.
 - Owned canonical builds may be published only when the user explicitly asks.
 
 ## App Constraints
@@ -133,6 +139,7 @@ const COMMANDS = new Set([
   "push",
   "check",
   "launch",
+  "sdk",
   "help",
 ]);
 
@@ -220,6 +227,10 @@ async function main() {
     await launch(options);
     return;
   }
+  if (options.command === "sdk") {
+    await sdkCommand(options);
+    return;
+  }
 
   printHelp();
 }
@@ -230,7 +241,13 @@ async function login(options) {
     url: `${options.apiUrl}/cli/device/start`,
     body: {
       clientName: options.clientName,
-      scopes: ["build:read", "build:write", "build:check", "build:publish"],
+      scopes: [
+        "build:read",
+        "build:write",
+        "build:check",
+        "build:publish",
+        "build:sdk",
+      ],
     },
     timeoutMs: options.timeoutMs,
   });
@@ -702,6 +719,490 @@ async function ensureAuth(options) {
   return await resolveAuth(options);
 }
 
+// Build SDK data-API methods callable from the CLI. Method names match the
+// SDK manifest (constants/buildSdkIndex.json in twinkle-api); paths are the
+// HTTP endpoints the Build runtime parent proxies those methods to. The args
+// JSON object is sent verbatim as the POST body, so arg shapes follow
+// TWINKLE_BUILD_SDK.md. Methods that mutate data require --allow-write.
+// Anything not listed can be called with --path api/<endpoint>.
+const SDK_CLI_METHODS = {
+  "aiStories.list": { path: "api/content/ai-stories/list", scopes: ["content:read"] },
+  "aiStories.chapters": { path: "api/content/ai-stories/chapters", scopes: ["content:read"] },
+  "aiStories.search": { path: "api/content/ai-stories/search", scopes: ["content:read"] },
+  "aiStories.get": { path: "api/content/ai-story", scopes: ["content:read"] },
+  "aiCards.list": { path: "api/content/ai-cards/list", scopes: ["content:read"] },
+  "aiCards.search": { path: "api/content/ai-cards/search", scopes: ["content:read"] },
+  "aiCards.get": { path: "api/content/ai-card", scopes: ["content:read"] },
+  "grammarbles.listQuestions": { path: "api/content/grammarbles/questions", scopes: ["content:read"] },
+  "grammarbles.getMyQuestionHistory": { path: "api/content/grammarbles/history", scopes: ["content:read"] },
+  "subjects.getMySubjects": { path: "api/content/my-subjects", scopes: ["content:read"] },
+  "subjects.search": { path: "api/content/subjects/search", scopes: ["content:read"] },
+  "subjects.getSubject": { path: "api/content/subject", scopes: ["content:read"] },
+  "subjects.getSubjectComments": { path: "api/content/subject-comments", scopes: ["content:read"] },
+  "subjectComments.list": { path: "api/content/subject-comment-list", scopes: ["content:read"] },
+  "profileComments.getProfileComments": { path: "api/content/profile-comments", scopes: ["content:read"] },
+  "profileComments.getProfileCommentIds": { path: "api/content/profile-comment-ids", scopes: ["content:read"] },
+  "profileComments.getCommentsByIds": { path: "api/content/profile-comments-by-ids", scopes: ["content:read"] },
+  "profileComments.getProfileCommentCounts": { path: "api/content/profile-comment-counts", scopes: ["content:read"] },
+  "privateDb.get": { path: "api/private-db/get", scopes: ["privateDb:read"] },
+  "privateDb.list": { path: "api/private-db/list", scopes: ["privateDb:read"] },
+  "privateDb.set": { path: "api/private-db/set", scopes: ["privateDb:write"], write: true },
+  "privateDb.remove": { path: "api/private-db/delete", scopes: ["privateDb:write"], write: true },
+  "sharedDb.getTopics": { path: "api/shared-db/topics", scopes: ["sharedDb:read"] },
+  "sharedDb.createTopic": { path: "api/shared-db/topic", scopes: ["sharedDb:write"], write: true },
+  "sharedDb.getEntries": { path: "api/shared-db/entries", scopes: ["sharedDb:read"] },
+  "sharedDb.addEntry": { path: "api/shared-db/entry", scopes: ["sharedDb:write"], write: true },
+  "sharedDb.updateEntry": { path: "api/shared-db/entry/update", scopes: ["sharedDb:write"], write: true },
+  "sharedDb.deleteEntry": { path: "api/shared-db/entry/delete", scopes: ["sharedDb:write"], write: true },
+  "sharedDb.kv.get": { path: "api/shared-db/kv/get", scopes: ["sharedDb:read"] },
+  "sharedDb.kv.list": { path: "api/shared-db/kv/list", scopes: ["sharedDb:read"] },
+  // The kv/set endpoint is batch-shaped ({ namespace, items }); kv.set keeps
+  // the SDK's single-key signature and maps to one item.
+  "sharedDb.kv.set": {
+    path: "api/shared-db/kv/set",
+    scopes: ["sharedDb:write"],
+    write: true,
+    mapArgs: (args) => ({
+      namespace: args.namespace,
+      items: [{ key: args.key, value: args.value }],
+    }),
+    sdkReshape: "the SDK takes (namespace, key, value) and returns { item }",
+  },
+  "sharedDb.kv.setMany": { path: "api/shared-db/kv/set", scopes: ["sharedDb:write"], write: true },
+  "sharedDb.kv.remove": { path: "api/shared-db/kv/delete", scopes: ["sharedDb:write"], write: true },
+  "chat.listRooms": { path: "api/chat/rooms/list", scopes: ["chat:read"] },
+  "chat.createRoom": { path: "api/chat/rooms/create", scopes: ["chat:write"], write: true },
+  "chat.listMessages": { path: "api/chat/messages/list", scopes: ["chat:read"] },
+  "chat.sendMessage": { path: "api/chat/messages/send", scopes: ["chat:write"], write: true },
+  "chat.deleteMessage": { path: "api/chat/messages/delete", scopes: ["chat:write"], write: true },
+  "users.getUser": {
+    path: "api/user",
+    scopes: ["user:read"],
+    sdkReshape: "the SDK returns the user object directly (unwraps { user })",
+  },
+  "users.getUsers": { path: "api/users", scopes: ["users:read"] },
+  "reflections.getDailyReflections": { path: "api/daily-reflections", scopes: ["dailyReflections:read"] },
+  "reminders.list": { path: "api/reminders/list", scopes: ["reminders:read"] },
+  // getDue's backend defaults autoAcknowledge to true, which persists writes
+  // (lastTriggeredAt, and disabling one-shot reminders). Force read-only
+  // probes to autoAcknowledge:false; acknowledging is a write that needs
+  // --allow-write.
+  "reminders.getDue": {
+    path: "api/reminders/due",
+    scopes: ["reminders:read"],
+    writeWhen: (args) => args.autoAcknowledge === true,
+    mapArgs: (args) => ({
+      ...args,
+      autoAcknowledge: args.autoAcknowledge === true,
+    }),
+  },
+  "reminders.create": { path: "api/reminders/create", scopes: ["reminders:write"], write: true },
+  "reminders.update": { path: "api/reminders/update", scopes: ["reminders:write"], write: true },
+  "reminders.remove": { path: "api/reminders/delete", scopes: ["reminders:write"], write: true },
+  "files.list": {
+    path: "api/files/list",
+    scopes: ["files:read"],
+    sdkReshape: "the SDK returns { assets, usage }",
+  },
+  "files.delete": {
+    path: "api/files/delete",
+    scopes: ["files:write"],
+    write: true,
+    sdkReshape: "the SDK returns { success, usage }",
+  },
+  "notifications.getSubscription": { path: "api/notifications/subscription", scopes: ["notifications:read"] },
+  "notifications.subscribe": { path: "api/notifications/subscription/subscribe", scopes: ["notifications:write"], write: true },
+  "notifications.unsubscribe": { path: "api/notifications/subscription/unsubscribe", scopes: ["notifications:write"], write: true },
+  "notifications.subscribeMany": { path: "api/notifications/subscriptions/subscribe", scopes: ["notifications:write"], write: true },
+  "notifications.unsubscribeMany": { path: "api/notifications/subscriptions/unsubscribe", scopes: ["notifications:write"], write: true },
+  "notifications.notifySubscribers": { path: "api/notifications/notify-subscribers", scopes: ["notifications:emit"], write: true },
+  "notifications.getSubjectUpdateSubscription": { path: "api/notifications/subject-update-subscription", scopes: ["notifications:read"] },
+  "notifications.subscribeToSubjectUpdates": { path: "api/notifications/subject-update-subscription/subscribe", scopes: ["notifications:write"], write: true },
+  "notifications.unsubscribeFromSubjectUpdates": { path: "api/notifications/subject-update-subscription/unsubscribe", scopes: ["notifications:write"], write: true },
+  // Leaderboards use the public leaderboard routes (regular login auth, no
+  // build API token). args.boardKey selects the board; remaining args are
+  // query params (get) or the POST body (submit).
+  "leaderboards.get": { special: "leaderboardGet" },
+  "leaderboards.submit": { special: "leaderboardSubmit", write: true },
+  // userDb (the viewer's private SQLite) lives at /viewer-db/*, which uses
+  // session auth directly — no build API token. query reads, exec mutates.
+  // Body is { sql, params }. The backend's query route accepts any
+  // row-returning statement, including INSERT/UPDATE/DELETE ... RETURNING,
+  // so SQL that mutates is gated behind --allow-write here too.
+  "userDb.query": { special: "userDbQuery", writeWhen: (args) => sqlMutates(args.sql) },
+  "userDb.exec": { special: "userDbExec", write: true },
+};
+
+// Heuristic write-detection for raw SQL. SELECT/EXPLAIN/VALUES cannot mutate;
+// a WITH (CTE) can wrap DML; everything else is treated as write-capable.
+// Errs toward over-gating (safe) rather than under-gating.
+function sqlMutates(sql) {
+  const normalized = String(sql || "")
+    .trim()
+    .replace(/^\(+/, "");
+  const leadingKeyword = (normalized.match(/^\s*([a-z]+)/i)?.[1] || "").toUpperCase();
+  if (
+    leadingKeyword === "SELECT" ||
+    leadingKeyword === "EXPLAIN" ||
+    leadingKeyword === "VALUES"
+  ) {
+    return false;
+  }
+  if (leadingKeyword === "WITH") {
+    return /\b(INSERT|UPDATE|DELETE|REPLACE)\b/i.test(normalized);
+  }
+  return true;
+}
+
+// Reverse index of curated endpoint paths -> method name(s). Used to reject
+// raw --path calls to curated endpoints: --path is for endpoints not in the
+// list, and routing a curated endpoint through --path would strip its
+// write/writeWhen/mapArgs safety handling (e.g. api/reminders/due defaults
+// autoAcknowledge to true and mutates under a read scope).
+const SDK_CLI_METHOD_NAMES_BY_PATH = (() => {
+  const byPath = new Map();
+  for (const [name, entry] of Object.entries(SDK_CLI_METHODS)) {
+    if (!entry.path) continue;
+    if (!byPath.has(entry.path)) byPath.set(entry.path, []);
+    byPath.get(entry.path).push(name);
+  }
+  return byPath;
+})();
+
+// Default token scopes for --path calls. Never fall through to the server's
+// default scope set: it includes write/emit scopes, which must not be minted
+// without --allow-write.
+const SDK_CLI_READ_SCOPES = [
+  "files:read",
+  "user:read",
+  "users:read",
+  "dailyReflections:read",
+  "content:read",
+  "sharedDb:read",
+  "privateDb:read",
+  "chat:read",
+  "notifications:read",
+  "reminders:read",
+];
+
+function isWriteCapableScope(scope) {
+  return /:(write|emit)$/.test(String(scope));
+}
+
+async function sdkCommand(options) {
+  const subcommand = String(options.positional[0] || "list");
+  if (subcommand === "list") {
+    printSdkMethodList();
+    return;
+  }
+  if (subcommand !== "call") {
+    throw new Error(
+      'Usage: lumine sdk list | lumine sdk call <namespace.method> [jsonArgs]',
+    );
+  }
+  await sdkCall(options);
+}
+
+function printSdkMethodList() {
+  console.log(
+    "Callable Build endpoints (args JSON = request body). Prints the raw\n" +
+      "endpoint response, which can differ from the SDK return shape (*).\n",
+  );
+  const byNamespace = new Map();
+  for (const [name, entry] of Object.entries(SDK_CLI_METHODS)) {
+    const namespace = name.split(".")[0];
+    if (!byNamespace.has(namespace)) byNamespace.set(namespace, []);
+    byNamespace.get(namespace).push({ name, entry });
+  }
+  for (const [namespace, methods] of byNamespace) {
+    console.log(`  ${namespace}`);
+    for (const { name, entry } of methods) {
+      const writeTag = entry.write ? "  [write: needs --allow-write]" : "";
+      const reshapeTag = entry.sdkReshape ? "  *" : "";
+      const pathText = entry.path || `(${entry.special})`;
+      console.log(
+        `    ${name.padEnd(44)} ${pathText}${writeTag}${reshapeTag}`,
+      );
+    }
+  }
+  console.log(`
+Usage:
+  lumine sdk call aiStories.chapters '{"limit": 5}'
+  lumine sdk call privateDb.set '{"key": "k", "value": {"a": 1}}' --allow-write
+  lumine sdk call leaderboards.get '{"boardKey": "default", "limit": 10}'
+  lumine sdk call aiStories.list '{"difficulty": 1}' --repeat 5 --build 1374
+  lumine sdk call userDb.query '{"sql": "SELECT * FROM sqlite_master"}'
+
+Request-body (args) shapes follow TWINKLE_BUILD_SDK.md. Output is the raw
+endpoint response; (*) methods are reshaped by their Twinkle.* SDK wrapper, so
+check TWINKLE_BUILD_SDK.md for the real SDK return shape. Add --repeat <n> for
+latency stats, --build <id> to target a build outside the current workspace.
+Use --path api/<endpoint> only for endpoints not listed above.`);
+}
+
+async function sdkCall(options) {
+  const usingRawPath = Boolean(options.sdkPath);
+  const methodName = usingRawPath ? "" : String(options.positional[1] || "");
+  const argsText = String(
+    (usingRawPath ? options.positional[1] : options.positional[2]) || "",
+  ).trim();
+
+  let args = {};
+  if (argsText) {
+    try {
+      args = JSON.parse(argsText);
+    } catch (error) {
+      throw new Error(`Args must be valid JSON: ${error.message}`);
+    }
+    if (!args || typeof args !== "object" || Array.isArray(args)) {
+      throw new Error("Args must be a JSON object, e.g. '{\"limit\": 5}'.");
+    }
+  }
+
+  let endpoint;
+  if (usingRawPath) {
+    let normalizedPath = String(options.sdkPath).replace(/^\/+/, "");
+    if (!/^api\/[a-zA-Z0-9/_-]+$/.test(normalizedPath)) {
+      throw new Error("--path must look like api/<endpoint> (no query string).");
+    }
+    // Normalize the way Express routes (case-insensitive, non-strict, slashes
+    // collapsed) so route-equivalent variants like api/Token or
+    // api/reminders/due/ cannot dodge the guards below. Guard and call the
+    // same normalized path so the checked string is the executed string.
+    normalizedPath = normalizedPath
+      .toLowerCase()
+      .replace(/\/{2,}/g, "/")
+      .replace(/\/+$/, "");
+    // api/token is control-plane: the CLI mints the build API token itself,
+    // and that endpoint's response is a token whose scopes come from the
+    // request body, not from the CLI mint — so the write gate cannot see
+    // them. Calling it as a data endpoint would hand back a write-capable
+    // token without --allow-write. It is not a data method; reject it.
+    if (/^api\/token(\/|$)/.test(normalizedPath)) {
+      throw new Error(
+        "api/token is not a callable SDK endpoint. The CLI mints build API " +
+          "tokens internally for sdk calls.",
+      );
+    }
+    // --path is for endpoints not in the curated list. Reject curated paths
+    // so their read/write safety handling cannot be bypassed via --path.
+    const curatedMethodNames = SDK_CLI_METHOD_NAMES_BY_PATH.get(normalizedPath);
+    if (curatedMethodNames) {
+      throw new Error(
+        `${normalizedPath} is a curated SDK endpoint. Call it as ` +
+          `${curatedMethodNames.join(" or ")} (applies the correct read/` +
+          "write handling). --path is only for endpoints not in `lumine sdk list`.",
+      );
+    }
+    endpoint = { path: normalizedPath, scopes: SDK_CLI_READ_SCOPES };
+  } else {
+    if (!methodName) {
+      throw new Error(
+        'Usage: lumine sdk call <namespace.method> [jsonArgs]. Run `lumine sdk list`.',
+      );
+    }
+    endpoint = SDK_CLI_METHODS[methodName];
+    if (!endpoint) {
+      throw new Error(
+        `Unknown SDK method "${methodName}". Run \`lumine sdk list\`, or call ` +
+          "the endpoint directly with --path api/<endpoint>.",
+      );
+    }
+  }
+
+  // Token-capability gate: a write-capable build API token must never be
+  // minted (and write-tagged methods never called) without --allow-write,
+  // regardless of whether the call came from the curated table, --path, or a
+  // --scopes override.
+  const requestedScopes = options.sdkScopes.length
+    ? options.sdkScopes
+    : endpoint.scopes || [];
+  const writeScopes = requestedScopes.filter(isWriteCapableScope);
+  // writeWhen covers endpoints that mutate under a read scope depending on
+  // their args (e.g. reminders.getDue acknowledging due reminders).
+  const writeByArgs =
+    typeof endpoint.writeWhen === "function" && endpoint.writeWhen(args);
+  const writeCapable =
+    Boolean(endpoint.write) || writeScopes.length > 0 || writeByArgs;
+  if (writeCapable && !options.allowWrite) {
+    const reason = writeScopes.length
+      ? `write scopes: ${writeScopes.join(", ")}`
+      : "this call writes app data";
+    throw new Error(
+      `${methodName || endpoint.path} can mutate real app data ` +
+        `(${reason}). Re-run with --allow-write.`,
+    );
+  }
+
+  // Resolve the build target (local-only: --build or workspace metadata)
+  // before any auth side effects, so invalid local input fails immediately
+  // instead of after starting the device-login flow.
+  const buildId = await resolveSdkBuildId(options);
+  const auth = await ensureAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:sdk" });
+  const attempts = [];
+  let lastResult = null;
+
+  if (endpoint.special === "leaderboardGet" || endpoint.special === "leaderboardSubmit") {
+    const boardKey = String(args.boardKey || "default");
+    const rest = { ...args };
+    delete rest.boardKey;
+    for (let attempt = 0; attempt < options.repeat; attempt += 1) {
+      if (endpoint.special === "leaderboardGet") {
+        const url = new URL(
+          `${options.apiUrl}/build/${buildId}/leaderboards/${encodeURIComponent(boardKey)}`,
+        );
+        for (const [key, value] of Object.entries(rest)) {
+          if (value !== null && value !== undefined) {
+            url.searchParams.set(key, String(value));
+          }
+        }
+        lastResult = await executeSdkHttpCall({
+          options,
+          method: "GET",
+          url: url.toString(),
+          authToken: auth.token,
+        });
+      } else {
+        lastResult = await executeSdkHttpCall({
+          options,
+          method: "POST",
+          url: `${options.apiUrl}/build/${buildId}/leaderboards/${encodeURIComponent(boardKey)}/submit`,
+          authToken: auth.token,
+          body: rest,
+        });
+      }
+      attempts.push(lastResult);
+      printSdkAttemptLine(attempts.length, lastResult);
+    }
+  } else if (
+    endpoint.special === "userDbQuery" ||
+    endpoint.special === "userDbExec"
+  ) {
+    // viewer-db uses session auth (no build API token). Body is { sql, params }.
+    const route = endpoint.special === "userDbExec" ? "exec" : "query";
+    const body = { sql: args.sql, params: args.params };
+    for (let attempt = 0; attempt < options.repeat; attempt += 1) {
+      lastResult = await executeSdkHttpCall({
+        options,
+        method: "POST",
+        url: `${options.apiUrl}/build/${buildId}/viewer-db/${route}`,
+        authToken: auth.token,
+        body,
+      });
+      attempts.push(lastResult);
+      printSdkAttemptLine(attempts.length, lastResult);
+    }
+  } else {
+    // Always request explicit scopes: an empty scopes body makes the server
+    // fall back to its default scope set, which is write-capable.
+    const scopes = requestedScopes.length
+      ? requestedScopes
+      : SDK_CLI_READ_SCOPES;
+    const tokenStartedAt = Date.now();
+    const tokenResult = await requestJson({
+      method: "POST",
+      url: `${options.apiUrl}/build/${buildId}/api/token`,
+      authToken: auth.token,
+      body: { scopes },
+      timeoutMs: options.timeoutMs,
+    });
+    console.error(
+      `token minted in ${Date.now() - tokenStartedAt}ms (scopes: ${
+        (tokenResult.scopes || []).join(", ") || "default"
+      })`,
+    );
+    const body = endpoint.mapArgs ? endpoint.mapArgs(args) : args;
+    for (let attempt = 0; attempt < options.repeat; attempt += 1) {
+      lastResult = await executeSdkHttpCall({
+        options,
+        method: "POST",
+        url: `${options.apiUrl}/build/${buildId}/${endpoint.path}`,
+        authToken: auth.token,
+        body,
+        buildApiToken: tokenResult.token,
+      });
+      attempts.push(lastResult);
+      printSdkAttemptLine(attempts.length, lastResult);
+    }
+  }
+
+  if (options.repeat > 1) {
+    const timings = attempts.map((entry) => entry.ms);
+    const total = timings.reduce((sum, ms) => sum + ms, 0);
+    console.error(
+      `latency over ${timings.length} calls: min ${Math.min(...timings)}ms · ` +
+        `avg ${Math.round(total / timings.length)}ms · max ${Math.max(...timings)}ms`,
+    );
+  }
+
+  // The printed JSON is the raw endpoint response. Some SDK wrappers reshape
+  // it, so warn precisely where the SDK return shape differs.
+  if (endpoint && endpoint.sdkReshape) {
+    console.error(
+      `note: raw endpoint response below — ${methodName}'s SDK wrapper ` +
+        `reshapes it (${endpoint.sdkReshape}). See TWINKLE_BUILD_SDK.md.`,
+    );
+  }
+  if (lastResult) {
+    console.log(JSON.stringify(lastResult.data ?? lastResult.text, null, 2));
+  }
+  if (lastResult && !lastResult.ok) {
+    process.exitCode = 1;
+  }
+}
+
+function printSdkAttemptLine(attemptNumber, result) {
+  console.error(
+    `#${attemptNumber} ${result.status}${result.ok ? " OK" : ""} · ` +
+      `${result.bytes.toLocaleString()} bytes · ${result.ms}ms`,
+  );
+}
+
+async function executeSdkHttpCall({
+  options,
+  method,
+  url,
+  authToken,
+  body,
+  buildApiToken,
+}) {
+  const startedAt = Date.now();
+  const response = await request({
+    method,
+    url,
+    authToken,
+    body,
+    timeoutMs: options.timeoutMs,
+    headers: buildApiToken ? { "x-build-api-token": buildApiToken } : {},
+  });
+  const text = await response.text();
+  return {
+    ok: response.ok,
+    status: response.status,
+    ms: Date.now() - startedAt,
+    bytes: Buffer.byteLength(text),
+    data: parseJson(text),
+    text,
+  };
+}
+
+async function resolveSdkBuildId(options) {
+  if (options.buildIdFlag) {
+    const buildId = resolveBuildId(options.buildIdFlag);
+    if (buildId > 0) return buildId;
+    throw new Error(`Invalid --build value: ${options.buildIdFlag}`);
+  }
+  const localProject = await findLocalProjectMetadata(
+    options.dir ? path.resolve(options.dir) : process.cwd(),
+  );
+  const buildId = Number(localProject?.metadata?.buildId || 0);
+  if (buildId > 0) return buildId;
+  throw new Error(
+    "No build workspace found. Run from a pulled workspace, pass --dir, or pass --build <id>.",
+  );
+}
+
 async function listBuilds({ options, auth }) {
   const url = new URL(`${options.apiUrl}/cli/builds`);
   url.searchParams.set("limit", String(options.limit));
@@ -980,7 +1481,7 @@ async function assertAuthScope({ options, auth, scope }) {
   const scopes = Array.isArray(session.scopes) ? session.scopes : [];
   if (!scopes.includes(scope)) {
     throw new Error(
-      `Saved login is missing ${scope}. Run \`lumine login\` again to approve file saves.`,
+      `Saved login is missing ${scope}. Run \`lumine login\` again to grant it.`,
     );
   }
 }
@@ -1769,7 +2270,14 @@ async function probeUrl({ url, authToken, timeoutMs }) {
   };
 }
 
-async function request({ method = "GET", url, authToken, body, timeoutMs }) {
+async function request({
+  method = "GET",
+  url,
+  authToken,
+  body,
+  timeoutMs,
+  headers = {},
+}) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), timeoutMs);
   try {
@@ -1778,6 +2286,7 @@ async function request({ method = "GET", url, authToken, body, timeoutMs }) {
       headers: {
         ...(authToken ? { authorization: authorizationHeader(authToken) } : {}),
         ...(body ? { "content-type": "application/json" } : {}),
+        ...headers,
       },
       body: body ? JSON.stringify(body) : undefined,
       signal: controller.signal,
@@ -1919,6 +2428,7 @@ function parseArgs(args) {
     "publish",
     "save",
     "noUpdateCheck",
+    "allowWrite",
   ]);
 
   for (let i = 0; i < rest.length; i += 1) {
@@ -1945,6 +2455,15 @@ function parseArgs(args) {
 
   return {
     command,
+    positional,
+    repeat: Math.min(Math.max(Math.floor(Number(raw.repeat) || 1), 1), 20),
+    allowWrite: parseBoolean(raw.allowWrite, false),
+    sdkPath: raw.path ? String(raw.path) : "",
+    sdkScopes: String(raw.scopes || "")
+      .split(",")
+      .map((scope) => scope.trim())
+      .filter(Boolean),
+    buildIdFlag: raw.build ? String(raw.build) : "",
     target: raw.url || raw.target || positional[0] || "",
     title:
       String(
@@ -2279,6 +2798,8 @@ function printHelp() {
   lumine save
   lumine check [twinkle-build-url]
   lumine launch [twinkle-build-url]
+  lumine sdk list
+  lumine sdk call <namespace.method> [jsonArgs]
 
 Examples:
   npx @stage5/lumine@latest
@@ -2295,6 +2816,9 @@ Examples:
   npx @stage5/lumine@latest save --publish
   npx @stage5/lumine@latest launch --save
   npx @stage5/lumine@latest launch https://www.twin-kle.com/app/123
+  npx @stage5/lumine@latest sdk call aiStories.chapters '{"limit": 5}'
+  npx @stage5/lumine@latest sdk call privateDb.get '{"key": "prefs"}' --build 1374
+  npx @stage5/lumine@latest sdk call aiStories.list '{"difficulty": 1}' --repeat 5
 
 Options:
   --api-url <url>       Twinkle API origin
@@ -2313,5 +2837,10 @@ Options:
   --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
+  --build <id>          Build id for sdk calls outside a workspace
+  --repeat <n>          Repeat an sdk call (1-20) and print latency stats
+  --allow-write         Permit sdk methods that mutate app data
+  --path <api/...>      Call an sdk endpoint not in the curated list
+  --scopes <a,b>        Override requested build API token scopes
 `);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "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.1
-Updated: 2026-06-08
-Generated: 2026-06-08T05:37:13.752Z
+Version: 1.26.2
+Updated: 2026-06-09
+Generated: 2026-06-09T01:00:18.637Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -17,7 +17,7 @@ Generated: 2026-06-08T05:37:13.752Z
 - 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.
+- 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.
 - 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.
 
@@ -316,6 +316,28 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Example: const world = await Twinkle.world.join({ roomKey: 'town-square', presence: { x: 0, y: 0, z: 0, facing: 'south' }, player: { name: avatarName } });
 world.subscribe((event) => updateRemotePlayers(event.players));
 world.updatePresence({ x, y, z, facing });
+- isRecoverableSessionError(error) | scopes: none
+  - Returns: boolean
+  - Return true when a world request error is expected to be handled by app code instead of crashing.
+  - Example: try {
+  await world.updatePresence({ x, y, z, facing });
+} catch (error) {
+  if (Twinkle.world.isSessionEndedError(error)) {
+    world = null;
+    scheduleReconnect();
+  } else if (Twinkle.world.isRecoverableSessionError(error)) {
+    // Drop this transient presence update and keep the current handle.
+  } else {
+    throw error;
+  }
+}
+- isSessionEndedError(error) | scopes: none
+  - Returns: boolean
+  - Return true when a world request error means the current session handle is stale and app code should reconnect with a fresh Twinkle.world.join call.
+  - Example: if (Twinkle.world.isSessionEndedError(error)) {
+  world = null;
+  scheduleReconnect();
+}
 - leaveAll() | scopes: none
   - Returns: void
   - Leave every active world session in the current iframe.
@@ -542,27 +564,64 @@ await Twinkle.chat.sendMessage('lobby', 'hello');
 ```
 
 ### Realtime MMO town room
-Use Twinkle.world for live avatar presence and lightweight room actions, while durable state like inventory and quests stays in sharedDb/privateDb.
+Use Twinkle.world for live avatar presence and lightweight room actions, recover stale session handles, and keep durable state like inventory and quests in sharedDb/privateDb.
 Keywords: multiplayer, mmo, town, presence, avatars, movement, three.js, realtime
 
 ```js
-const world = await Twinkle.world.join({
-  worldKey: 'town',
-  roomKey: 'square',
-  presence: { x: 0, y: 0, z: 0, facing: 'south', animation: 'idle' },
-  player: { name: avatarName }
-});
+let world = null;
+let reconnectTimer = 0;
+
+async function connectWorld() {
+  if (world) return world;
+  world = await Twinkle.world.join({
+    worldKey: 'town',
+    roomKey: 'square',
+    presence: { x: 0, y: 0, z: 0, facing: 'south', animation: 'idle' },
+    player: { name: avatarName }
+  });
+
+  world.subscribe((event) => {
+    renderPlayers(event.players);
+    if (event.type === 'session.ended') {
+      handleWorldDrop();
+    }
+    if (event.type === 'action.received' && event.action?.type === 'emote') {
+      showEmote(event.sessionId, event.action.data.emote);
+    }
+  });
+  return world;
+}
 
-world.subscribe((event) => {
-  renderPlayers(event.players);
-  if (event.type === 'action.received' && event.action?.type === 'emote') {
-    showEmote(event.sessionId, event.action.data.emote);
+function handleWorldDrop() {
+  world = null;
+  if (!reconnectTimer) {
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = 0;
+      connectWorld().catch(handleWorldDrop);
+    }, 1000);
   }
-});
+}
+
+async function syncPresence() {
+  try {
+    const session = await connectWorld();
+    // Throttle this in the game loop, for example 5-15 times per second.
+    await session.updatePresence({ x: player.x, y: player.y, z: player.z, facing });
+  } catch (error) {
+    if (Twinkle.world.isSessionEndedError(error)) {
+      handleWorldDrop();
+      return;
+    }
+    if (Twinkle.world.isRecoverableSessionError(error)) {
+      // Drop this transient presence update and keep the current handle.
+      return;
+    }
+    throw error;
+  }
+}
 
-// Throttle this in the game loop, for example 5-15 times per second.
-await world.updatePresence({ x: player.x, y: player.y, z: player.z, facing });
-await world.send('emote', { emote: 'wave' });
+await connectWorld();
+await syncPresence();
 ```
 
 ### Play chess against the computer