@stage5/lumine 0.2.15 → 0.2.16

package/README.md

@@ -10,6 +10,7 @@ npx @stage5/lumine@latest new --title "Daily Reflection App" --description "Priv
 npx @stage5/lumine@latest rename "My New Build Title"
 npx @stage5/lumine@latest rename "New Title" --target 123
 npx @stage5/lumine@latest projects
+npx @stage5/lumine@latest branches 884
 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
@@ -35,6 +36,10 @@ 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
 can merge or replace main from Twinkle.
 
+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 explore` to list public open-source Build apps that can be used as
 examples or starting points. It supports `--search` and `--sort forks`,
 `--sort popular`, or `--sort recent`. Use `lumine reference <build-url-or-id>`

package/lib/api.js

@@ -30,6 +30,21 @@ export async function listOpenSourceBuilds({ options, auth }) {
   return Array.isArray(result.builds) ? result.builds : [];
 }
 
+export async function listContributionBranches({
+  options,
+  auth,
+  buildId,
+  limit,
+}) {
+  const url = new URL(`${options.apiUrl}/build/${buildId}/contributions`);
+  url.searchParams.set("limit", String(limit));
+  return await requestJson({
+    url: url.toString(),
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
 export async function loadBuildMetadata({ options, auth, buildId }) {
   const result = await loadBuildFiles({
     options,

package/lib/commands.js

@@ -31,6 +31,7 @@ import {
   loadBuildVersionFiles,
   loadBuildVersions,
   loadContributionDiff,
+  listContributionBranches,
   loadLumineCliVersionInfo,
   loadOpenSourceBuildFiles,
   maybeCheckForLumineCliUpdate,
@@ -76,6 +77,7 @@ import {
   collectProjectLimitFindings,
   findLocalProjectMetadata,
   isIndexHtmlPath,
+  isReadOnlyProjectMetadata,
   isReadOnlyReferenceMetadata,
   removeLocalProjectFilesNotIn,
   stashLocalProjectFilesBeforePull,
@@ -130,6 +132,10 @@ export async function main() {
     await projects(options);
     return;
   }
+  if (options.command === "branches") {
+    await branches(options);
+    return;
+  }
   if (options.command === "explore") {
     await explore(options);
     return;
@@ -263,7 +269,8 @@ export async function renameBuild(options) {
   await saveSelectedBuild({ options, auth, build: updatedBuild });
   if (
     localProject?.rootDir &&
-    Number(localProject.metadata?.buildId || 0) === buildId
+    Number(localProject.metadata?.buildId || 0) === buildId &&
+    !isReadOnlyProjectMetadata(localProject.metadata)
   ) {
     await writeProjectMetadata({
       dir: localProject.rootDir,
@@ -303,6 +310,33 @@ export async function projects(options) {
   printBuildList(builds);
 }
 
+export async function branches(options) {
+  const auth = await resolveAuth(options);
+  const requestedBuildId = await resolveRequiredBuildIdOrSelected(
+    options,
+    auth,
+  );
+  const requestedBuild = await loadBuildMetadata({
+    options,
+    auth,
+    buildId: requestedBuildId,
+  });
+  const rootBuildId =
+    Number(requestedBuild.contributionRootBuildId || 0) ||
+    Number(requestedBuild.id || 0);
+  const rootBuild =
+    rootBuildId === Number(requestedBuild.id || 0)
+      ? requestedBuild
+      : await loadBuildMetadata({ options, auth, buildId: rootBuildId });
+  const result = await listContributionBranches({
+    options,
+    auth,
+    buildId: rootBuildId,
+    limit: options.limit,
+  });
+  printContributionBranches({ result, rootBuild, options });
+}
+
 export async function explore(options) {
   const auth = await resolveAuth(options);
   const builds = await listOpenSourceBuilds({ options, auth });
@@ -1618,6 +1652,34 @@ export function printContributionDiff({ result, build }) {
   }
 }
 
+export function printContributionBranches({ result, rootBuild, options }) {
+  const contributions = Array.isArray(result?.contributions)
+    ? result.contributions
+    : [];
+  console.log(`Branches for ${formatBuildTitle(rootBuild)}:`);
+  if (!contributions.length) {
+    console.log("No contribution branches.");
+    return;
+  }
+  for (const [index, contribution] of contributions.entries()) {
+    const branchNumber = Number(contribution.contributionBranchNumber || 0);
+    const branchLabel = branchNumber
+      ? `branch ${branchNumber}`
+      : `branch #${contribution.id}`;
+    const title = String(contribution.title || "Untitled branch").trim();
+    const contributor = String(contribution.username || "unknown").trim();
+    const status = String(contribution.contributionStatus || "draft").trim();
+    console.log(
+      `${index + 1}. ${title} - ${contributor} - ${branchLabel} (${status})`,
+    );
+    if (branchNumber) {
+      console.log(
+        `   ${options.siteUrl}/build/${Number(rootBuild.id)}/${branchNumber}`,
+      );
+    }
+  }
+}
+
 export function printUpdateFromMainResult({ result, build, dir, mergedFiles }) {
   const branchNumber = Number(build?.contributionBranchNumber || 0) || 0;
   const branchLabel = branchNumber
@@ -1981,6 +2043,7 @@ export function printHelp() {
   lumine new [title]
   lumine rename [title] [--target <twinkle-build-url-or-id>]
   lumine projects
+  lumine branches [twinkle-build-url-or-id] [--limit <n>]
   lumine explore [search terms]
   lumine select [twinkle-build-url]
   lumine pull [twinkle-build-url]
@@ -2016,6 +2079,7 @@ Examples:
   npx @stage5/lumine@latest rename "My New Build Title"
   npx @stage5/lumine@latest rename "New Title" --target 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 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

package/lib/constants.js

@@ -308,6 +308,7 @@ export const AGENT_INSTRUCTION_FILES = ["AGENTS.md", "CLAUDE.md"];
 export const MAIN_CHECKOUT_READONLY_COMMANDS = new Set([
   "pull",
   "check",
+  "branches",
   "diff",
   "sdk",
   "select",
@@ -326,6 +327,7 @@ export const COMMANDS = new Set([
   "new",
   "rename",
   "projects",
+  "branches",
   "explore",
   "select",
   "pull",

package/lib/workspace.js

@@ -779,14 +779,15 @@ export function resolveProjectDirForSave({ options, localProject }) {
 export function assertLocalProjectCanBeSaved(localProject) {
   const metadata = localProject?.metadata;
   if (!metadata) return;
-  if (metadata.mainCheckout === true) {
+  const readOnlyKind = readOnlyProjectMetadataKind(metadata);
+  if (readOnlyKind === "main") {
     const rootBuildId =
       Number(metadata.buildId || 0) || Number(metadata.build?.id || 0) || 0;
     throw new Error(
       `This is a read-only checkout of main${rootBuildId ? ` for Build ${rootBuildId}` : ""}. Make edits in your branch workspace (\`lumine pull${rootBuildId ? ` ${rootBuildId}` : ""}\`), and run \`lumine update-from-main\` there to bring main's changes into it.`,
     );
   }
-  if (metadata.versionCheckout === true) {
+  if (readOnlyKind === "version") {
     const checkoutBuildId =
       Number(metadata.buildId || 0) || Number(metadata.build?.id || 0) || 0;
     const checkoutVersion = Number(metadata.checkoutVersion || 0) || 0;
@@ -794,7 +795,7 @@ export function assertLocalProjectCanBeSaved(localProject) {
       `This is a read-only checkout of a previous save${checkoutVersion ? ` (v${checkoutVersion})` : ""}${checkoutBuildId ? ` for Build ${checkoutBuildId}` : ""}. To bring this save back, run \`lumine restore${checkoutVersion ? ` ${checkoutVersion}` : " <n>"}\` from the editable workspace, then \`lumine save\`.`,
     );
   }
-  if (isReadOnlyReferenceMetadata(metadata)) {
+  if (readOnlyKind === "reference") {
     const sourceBuildId =
       Number(metadata.reference?.sourceBuildId || 0) ||
       Number(metadata.buildId || 0) ||
@@ -804,7 +805,7 @@ export 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) {
+  if (readOnlyKind === "server") {
     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.",
     );
@@ -819,6 +820,18 @@ export function isReadOnlyReferenceMetadata(metadata) {
   );
 }
 
+export function isReadOnlyProjectMetadata(metadata) {
+  return readOnlyProjectMetadataKind(metadata) !== null;
+}
+
+export function readOnlyProjectMetadataKind(metadata) {
+  if (metadata?.mainCheckout === true) return "main";
+  if (metadata?.versionCheckout === true) return "version";
+  if (isReadOnlyReferenceMetadata(metadata)) return "reference";
+  if (metadata?.build?.canWrite === false) return "server";
+  return null;
+}
+
 export function resolveLocalProjectFilePath({ rootDir, projectPath }) {
   const relativePath = projectPathToRelativePath(projectPath);
   const root = path.resolve(rootDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.15",
+  "version": "0.2.16",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {