@stage5/lumine 0.1.6 → 0.1.7

package/bin/lumine.js

@@ -125,6 +125,9 @@ const COMMANDS = new Set([
   "pull",
   "reference",
   "fork",
+  "diff",
+  "merge",
+  "replace-main",
   "save",
   "push",
   "check",
@@ -188,6 +191,18 @@ async function main() {
     await fork(options);
     return;
   }
+  if (options.command === "diff") {
+    await diff(options);
+    return;
+  }
+  if (options.command === "merge") {
+    await mergeBranch(options);
+    return;
+  }
+  if (options.command === "replace-main") {
+    await replaceMainWithBranch(options);
+    return;
+  }
   if (options.command === "save" || options.command === "push") {
     await save(options);
     return;
@@ -302,11 +317,7 @@ async function whoami(options) {
 async function workspace(options) {
   const auth = await ensureAuth(options);
   const selectedBuild = options.target
-    ? await loadBuildMetadata({
-        options,
-        auth,
-        buildId: resolveRequiredBuildId(options.target),
-      })
+    ? await loadTargetBuildMetadata({ options, auth })
     : await chooseProject({
         builds: await listBuilds({ options, auth }),
       });
@@ -337,11 +348,7 @@ async function explore(options) {
 async function selectProject(options) {
   const auth = await resolveAuth(options);
   const selectedBuild = options.target
-    ? await loadBuildMetadata({
-        options,
-        auth,
-        buildId: resolveRequiredBuildId(options.target),
-      })
+    ? await loadTargetBuildMetadata({ options, auth })
     : await chooseProject({
         builds: await listBuilds({ options, auth }),
       });
@@ -376,7 +383,7 @@ async function pull(options) {
 
 async function reference(options) {
   const auth = await resolveAuth(options);
-  const buildId = resolveRequiredBuildId(options.target);
+  const buildId = await resolveRequiredBuildIdOrSelected(options, auth);
   const result = await pullReferenceFiles({ options, auth, buildId });
   printReferenceResult(result);
 }
@@ -384,7 +391,7 @@ async function reference(options) {
 async function fork(options) {
   const auth = await resolveAuth(options);
   await assertAuthScope({ options, auth, scope: "build:write" });
-  const buildId = resolveRequiredBuildId(options.target);
+  const buildId = await resolveRequiredBuildIdOrSelected(options, auth);
   const forkResult = await forkBuild({ options, auth, buildId });
   const forkedBuildId = Number(forkResult.build?.id || 0);
   if (!forkedBuildId) {
@@ -399,6 +406,60 @@ async function fork(options) {
   printForkResult({ forkResult, pullResult: result });
 }
 
+async function diff(options) {
+  const auth = await resolveAuth(options);
+  const build = await loadTargetBuildMetadata({ options, auth });
+  const { rootBuildId, contributionBuildId } =
+    resolveContributionActionBuildIds(build);
+  const result = await loadContributionDiff({
+    options,
+    auth,
+    rootBuildId,
+    contributionBuildId,
+  });
+  printContributionDiff({ result, build });
+}
+
+async function mergeBranch(options) {
+  const auth = await resolveAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:write" });
+  const build = await loadTargetBuildMetadata({ options, auth });
+  const { rootBuildId, contributionBuildId } =
+    resolveContributionActionBuildIds(build);
+  const result = await mergeContributionIntoMain({
+    options,
+    auth,
+    rootBuildId,
+    contributionBuildId,
+  });
+  printContributionActionResult({
+    action: "Merged",
+    result,
+    rootBuildId,
+    contributionBuildId,
+  });
+}
+
+async function replaceMainWithBranch(options) {
+  const auth = await resolveAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:write" });
+  const build = await loadTargetBuildMetadata({ options, auth });
+  const { rootBuildId, contributionBuildId } =
+    resolveContributionActionBuildIds(build);
+  const result = await replaceMainWithContribution({
+    options,
+    auth,
+    rootBuildId,
+    contributionBuildId,
+  });
+  printContributionActionResult({
+    action: "Replaced main with",
+    result,
+    rootBuildId,
+    contributionBuildId,
+  });
+}
+
 async function save(options) {
   const auth = await resolveAuth(options);
   await assertAuthScope({ options, auth, scope: "build:write" });
@@ -415,6 +476,11 @@ async function save(options) {
     buildId,
     localProject,
   });
+  if (build?.canWrite === false) {
+    throw new Error(
+      "This checkout is read-only for the current CLI login. Pull or diff it for review, then merge or replace main from the project owner workflow.",
+    );
+  }
   buildId = Number(build?.id || buildId);
   const dir = resolveProjectDirForSave({ options, localProject });
   const files = await collectProjectFiles(dir);
@@ -566,6 +632,11 @@ async function publishBuild({ options, buildId, auth }) {
 function printCheck(result) {
   const checks = result.checks || {};
   console.log(`Launch check: ${result.ok ? "ok" : "fail"}`);
+  if (checks.canonicalBuild) {
+    console.log(
+      `- canonical build: ${checks.canonicalBuild.ok ? "ok" : "fail"}`,
+    );
+  }
   console.log(
     `- project files: ${checks.projectFiles?.ok ? "ok" : "fail"} ` +
       `files=${checks.projectFiles?.fileCount ?? 0}`,
@@ -645,6 +716,11 @@ async function loadBuildMetadata({ options, auth, buildId }) {
   return result.build;
 }
 
+async function loadTargetBuildMetadata({ options, auth }) {
+  const buildId = await resolveRequiredBuildIdOrSelected(options, auth);
+  return await loadBuildMetadata({ options, auth, buildId });
+}
+
 async function loadOpenSourceBuildFiles({
   options,
   auth,
@@ -670,6 +746,24 @@ async function loadBuildFiles({ options, auth, buildId, includeContent }) {
   });
 }
 
+async function resolveBranchBuild({
+  options,
+  auth,
+  rootBuildId,
+  branchNumber,
+}) {
+  const result = await requestJson({
+    url: `${options.apiUrl}/cli/build/${rootBuildId}/branches/${branchNumber}`,
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+  const branchBuildId = Number(result.build?.id || 0);
+  if (!branchBuildId) {
+    throw new Error(`Branch ${branchNumber} for Build ${rootBuildId} could not be loaded.`);
+  }
+  return result.build;
+}
+
 async function forkBuild({ options, auth, buildId }) {
   return await requestJson({
     method: "POST",
@@ -694,6 +788,49 @@ async function saveProjectFiles({ options, auth, buildId, files, summary }) {
   });
 }
 
+async function loadContributionDiff({
+  options,
+  auth,
+  rootBuildId,
+  contributionBuildId,
+}) {
+  return await requestJson({
+    url: `${options.apiUrl}/build/${rootBuildId}/contributions/${contributionBuildId}`,
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+async function mergeContributionIntoMain({
+  options,
+  auth,
+  rootBuildId,
+  contributionBuildId,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/${rootBuildId}/contributions/${contributionBuildId}/merge`,
+    authToken: auth.token,
+    body: {},
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+async function replaceMainWithContribution({
+  options,
+  auth,
+  rootBuildId,
+  contributionBuildId,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/${rootBuildId}/contributions/${contributionBuildId}/replace-main`,
+    authToken: auth.token,
+    body: {},
+    timeoutMs: options.timeoutMs,
+  });
+}
+
 async function resolveBuildForSave({ options, auth, buildId, localProject }) {
   const localBuild = localProject?.metadata?.build;
   const localBuildId =
@@ -1226,6 +1363,11 @@ function assertLocalProjectCanBeSaved(localProject) {
       `This is a read-only Lumine reference${sourceBuildId ? ` for Build ${sourceBuildId}` : ""}. Run \`lumine fork${sourceBuildId ? ` ${sourceBuildId}` : ""}\` to create an editable workspace.`,
     );
   }
+  if (metadata.build?.canWrite === false) {
+    throw new Error(
+      "This Lumine checkout is read-only for the current CLI login. Pull or diff it for review; project-owner branch edits must go through merge or replace-main.",
+    );
+  }
 }
 
 function isReadOnlyReferenceMetadata(metadata) {
@@ -1344,6 +1486,17 @@ function isContributionBranch(build) {
   );
 }
 
+function resolveContributionActionBuildIds(build) {
+  const contributionBuildId = Number(build?.id || 0);
+  const rootBuildId = Number(build?.contributionRootBuildId || 0);
+  if (!contributionBuildId || !rootBuildId || !isContributionBranch(build)) {
+    throw new Error(
+      "Pass a branch URL such as https://www.twin-kle.com/build/884/4, or run this from a pulled branch workspace.",
+    );
+  }
+  return { rootBuildId, contributionBuildId };
+}
+
 function printPullResult(result) {
   const build = result.build || {};
   const entryPath = result.manifest?.entryPath || "unknown";
@@ -1356,6 +1509,12 @@ function printPullResult(result) {
   console.log(`Next: cd ${shellQuote(result.dir)}`);
   if (build.canWrite === false) {
     console.log("This checkout is read-only for the current CLI login.");
+    if (isContributionBranch(build)) {
+      console.log("Review changes: lumine diff");
+      if (build.role === "project_owner") {
+        console.log("Owner actions: lumine merge, or lumine replace-main");
+      }
+    }
     return;
   }
   console.log('Codex: codex "Read AGENTS.md, then make the requested change."');
@@ -1426,6 +1585,57 @@ function printSaveResult({ result, build, dir, files }) {
   }
 }
 
+function printContributionDiff({ result, build }) {
+  const summary = result.diff?.summary || {};
+  const files = Array.isArray(result.diff?.changedFiles)
+    ? result.diff.changedFiles
+    : [];
+  const branchNumber = Number(build.contributionBranchNumber || 0) || 0;
+  const branchLabel = branchNumber ? `branch ${branchNumber}` : `branch #${build.id}`;
+  console.log(`Diff for ${branchLabel}:`);
+  console.log(
+    `- total=${summary.total ?? files.length} added=${summary.added ?? 0} ` +
+      `updated=${summary.updated ?? 0} deleted=${summary.deleted ?? 0}`,
+  );
+  if (result.rootDrifted) {
+    console.log("- main changed after this branch was created");
+  }
+  if (!files.length) {
+    console.log("No file changes.");
+    return;
+  }
+  for (const file of files) {
+    const mergeStatus = file.mergeStatus ? ` (${file.mergeStatus})` : "";
+    console.log(`- ${file.status || "changed"} ${file.path}${mergeStatus}`);
+  }
+}
+
+function printContributionActionResult({
+  action,
+  result,
+  rootBuildId,
+  contributionBuildId,
+}) {
+  if (!result?.success) {
+    console.log(result?.error || "Branch action did not complete.");
+    process.exitCode = 1;
+    return;
+  }
+  const projectFiles = Array.isArray(result.projectFiles)
+    ? result.projectFiles
+    : [];
+  console.log(`${action} branch #${contributionBuildId} for Build #${rootBuildId}.`);
+  if (projectFiles.length > 0) {
+    console.log(
+      `Main now has ${projectFiles.length} project file${projectFiles.length === 1 ? "" : "s"}.`,
+    );
+  }
+  if (result.mergeConflictsWritten || result.conflicts?.length > 0) {
+    console.log("Merge wrote conflict markers. Resolve them in the Build workspace.");
+  }
+  console.log(`Main workspace: ${rootBuildId}`);
+}
+
 async function resolveAuth(options) {
   if (options.authToken) {
     return { token: options.authToken };
@@ -1745,8 +1955,14 @@ async function resolveRequiredBuildIdOrSelected(
   auth,
   { localProject = null } = {},
 ) {
-  const buildId = resolveBuildId(options.target);
-  if (buildId > 0) return buildId;
+  const targetReference = resolveBuildReference(options.target);
+  if (targetReference.buildId > 0) {
+    return await resolveBuildReferenceBuildId({
+      options,
+      auth,
+      reference: targetReference,
+    });
+  }
   const resolvedLocalProject =
     localProject ||
     (await findLocalProjectMetadata(
@@ -1775,7 +1991,7 @@ async function resolveRequiredBuildIdOrSelected(
 }
 
 function resolveRequiredBuildId(value) {
-  const buildId = resolveBuildId(value);
+  const buildId = resolveBuildReference(value).buildId;
   if (buildId > 0) return buildId;
   throw new Error(
     "Pass a Twinkle build URL, app URL, preview URL, or build id.",
@@ -1783,40 +1999,74 @@ function resolveRequiredBuildId(value) {
 }
 
 function resolveBuildId(value) {
+  return resolveBuildReference(value).buildId;
+}
+
+async function resolveBuildReferenceBuildId({ options, auth, reference }) {
+  if (reference.branchNumber > 0) {
+    const build = await resolveBranchBuild({
+      options,
+      auth,
+      rootBuildId: reference.buildId,
+      branchNumber: reference.branchNumber,
+    });
+    return Number(build.id || 0);
+  }
+  return Number(reference.buildId || 0);
+}
+
+function resolveBuildReference(value) {
   const rawValue = String(value || "").trim();
   const directId = Number(rawValue);
-  if (Number.isFinite(directId) && directId > 0) return directId;
-  if (!rawValue) return 0;
+  if (Number.isFinite(directId) && directId > 0) {
+    return { buildId: directId, branchNumber: 0 };
+  }
+  if (!rawValue) return { buildId: 0, branchNumber: 0 };
 
   try {
     const parsedUrl = new URL(rawValue);
     const host = parsedUrl.hostname.toLowerCase();
     const previewHost = host.match(/^b-(\d+)\.preview\.lumine\.app$/);
-    if (previewHost) return Number(previewHost[1]) || 0;
+    if (previewHost) {
+      return { buildId: Number(previewHost[1]) || 0, branchNumber: 0 };
+    }
 
     const parts = parsedUrl.pathname.split("/").filter(Boolean);
     const appIndex = parts.indexOf("app");
-    if (appIndex >= 0) return Number(parts[appIndex + 1]) || 0;
+    if (appIndex >= 0) {
+      return { buildId: Number(parts[appIndex + 1]) || 0, branchNumber: 0 };
+    }
 
     const buildIndex = parts.indexOf("build");
     if (buildIndex >= 0) {
       if (parts[buildIndex + 1] === "preview") {
         const nestedBuildIndex = parts.indexOf("build", buildIndex + 2);
-        return Number(parts[nestedBuildIndex + 1]) || 0;
+        return {
+          buildId: Number(parts[nestedBuildIndex + 1]) || 0,
+          branchNumber: 0,
+        };
       }
-      return Number(parts[buildIndex + 1]) || 0;
+      return {
+        buildId: Number(parts[buildIndex + 1]) || 0,
+        branchNumber: Number(parts[buildIndex + 2]) || 0,
+      };
     }
 
-    return (
-      Number(parsedUrl.searchParams.get("buildId")) ||
-      Number(parsedUrl.searchParams.get("build")) ||
-      0
-    );
+    return {
+      buildId:
+        Number(parsedUrl.searchParams.get("buildId")) ||
+        Number(parsedUrl.searchParams.get("build")) ||
+        0,
+      branchNumber: 0,
+    };
   } catch {
     const match = rawValue.match(
-      /(?:^|\/)(?:app|build)\/(?:preview\/build\/)?(\d+)(?:\/|$)/,
+      /(?:^|\/)(?:app|build)\/(?:preview\/build\/)?(\d+)(?:\/(\d+))?(?:\/|$)/,
     );
-    return Number(match?.[1] || 0) || 0;
+    return {
+      buildId: Number(match?.[1] || 0) || 0,
+      branchNumber: Number(match?.[2] || 0) || 0,
+    };
   }
 }
 
@@ -1926,6 +2176,9 @@ function printHelp() {
   lumine pull [twinkle-build-url]
   lumine reference <twinkle-build-url>
   lumine fork <twinkle-build-url>
+  lumine diff <twinkle-branch-url>
+  lumine merge <twinkle-branch-url>
+  lumine replace-main <twinkle-branch-url>
   lumine save
   lumine check [twinkle-build-url]
   lumine launch [twinkle-build-url]
@@ -1936,6 +2189,8 @@ Examples:
   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
+  npx @stage5/lumine@latest diff https://www.twin-kle.com/build/884/4
+  npx @stage5/lumine@latest merge https://www.twin-kle.com/build/884/4
   npx @stage5/lumine@latest pull
   npx @stage5/lumine@latest save
   npx @stage5/lumine@latest save --publish

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "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.0
+Version: 1.25.1
 Updated: 2026-05-28
-Generated: 2026-05-28T09:34:12.631Z
+Generated: 2026-05-28T10:24:18.784Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -203,15 +203,15 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
 
 ### 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 }
+  - Returns: { cards: [{ id, contentType, contentId, word, text, exampleText, prompt, level, wordLevel, quality, style, imagePath, imageUrl, isMysteryCard, isImageGenerating, 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 }
+  - Returns: { cards: [{ id, contentType, contentId, word, text, exampleText, prompt, level, wordLevel, quality, style, imagePath, imageUrl, isMysteryCard, isImageGenerating, 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 } }
+  - Returns: { card: { id, contentType, contentId, word, text, exampleText, prompt, level, wordLevel, quality, style, imagePath, imageUrl, isMysteryCard, isImageGenerating, 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);