@stage5/lumine 0.1.3 → 0.1.5

package/README.md

@@ -6,6 +6,9 @@ Launch Twinkle Lumine builds from any terminal.
 npx @stage5/lumine@latest
 npx @stage5/lumine@latest login
 npx @stage5/lumine@latest projects
+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 pull
 npx @stage5/lumine@latest save
 npx @stage5/lumine@latest save --publish
@@ -21,6 +24,13 @@ 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 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>`
+to pull source files into a read-only reference folder, or
+`lumine fork <build-url-or-id>` to create your own editable fork and pull it
+locally.
+
 After editing pulled files, run `lumine save` from that folder. The CLI saves
 through Twinkle's normal workspace project-file route, creates a project artifact
 version, records the same save metadata, and marks public builds as having
@@ -35,6 +45,16 @@ uploaded by `lumine save`. Build apps run in sandboxed iframes without native
 form submission, so use JavaScript-handled inputs and buttons instead of
 `<form>` elements.
 
+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";
@@ -29,10 +31,13 @@ const EXCLUDED_UPLOAD_FILES = new Set([
 const LUMINE_AGENT_INSTRUCTIONS_MARKER =
   "<!-- Lumine CLI Agent Instructions -->";
 const LUMINE_SDK_REFERENCE_MARKER = "<!-- Lumine CLI SDK Reference -->";
+const LUMINE_REFERENCE_INSTRUCTIONS_MARKER =
+  "<!-- Lumine CLI Reference Instructions -->";
 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
 
@@ -59,6 +64,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.
@@ -90,6 +96,21 @@ lumine save --summary "Describe the change"
 Report the changed files, any SDK methods used, the lumine save result, the
 build or branch id, and whether the result is published or unpublished changes.
 `;
+const LUMINE_REFERENCE_INSTRUCTIONS = `${LUMINE_REFERENCE_INSTRUCTIONS_MARKER}
+# Lumine Reference Guide
+
+This directory contains read-only reference files pulled from a public
+open-source Twinkle Build. Use it for inspection and borrowing patterns, not as
+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.
+`;
 const AGENT_INSTRUCTION_FILES = ["AGENTS.md", "CLAUDE.md"];
 const COMMANDS = new Set([
   "workspace",
@@ -97,8 +118,11 @@ const COMMANDS = new Set([
   "logout",
   "whoami",
   "projects",
+  "explore",
   "select",
   "pull",
+  "reference",
+  "fork",
   "save",
   "push",
   "check",
@@ -113,10 +137,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);
@@ -138,6 +166,10 @@ async function main() {
     await projects(options);
     return;
   }
+  if (options.command === "explore") {
+    await explore(options);
+    return;
+  }
   if (options.command === "select") {
     await selectProject(options);
     return;
@@ -146,6 +178,14 @@ async function main() {
     await pull(options);
     return;
   }
+  if (options.command === "reference") {
+    await reference(options);
+    return;
+  }
+  if (options.command === "fork") {
+    await fork(options);
+    return;
+  }
   if (options.command === "save" || options.command === "push") {
     await save(options);
     return;
@@ -286,6 +326,12 @@ async function projects(options) {
   printBuildList(builds);
 }
 
+async function explore(options) {
+  const auth = await resolveAuth(options);
+  const builds = await listOpenSourceBuilds({ options, auth });
+  printOpenSourceBuildList(builds, options);
+}
+
 async function selectProject(options) {
   const auth = await resolveAuth(options);
   const selectedBuild = options.target
@@ -326,12 +372,38 @@ async function pull(options) {
   printPullResult(result);
 }
 
+async function reference(options) {
+  const auth = await resolveAuth(options);
+  const buildId = resolveRequiredBuildId(options.target);
+  const result = await pullReferenceFiles({ options, auth, buildId });
+  printReferenceResult(result);
+}
+
+async function fork(options) {
+  const auth = await resolveAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:write" });
+  const buildId = resolveRequiredBuildId(options.target);
+  const forkResult = await forkBuild({ options, auth, buildId });
+  const forkedBuildId = Number(forkResult.build?.id || 0);
+  if (!forkedBuildId) {
+    throw new Error("Twinkle did not return a forked Build.");
+  }
+  const result = await pullBuildFiles({
+    options,
+    auth,
+    buildId: forkedBuildId,
+  });
+  await saveSelectedBuild({ options, auth, build: result.build });
+  printForkResult({ forkResult, pullResult: result });
+}
+
 async function save(options) {
   const auth = await resolveAuth(options);
   await assertAuthScope({ options, auth, scope: "build:write" });
   const localProject = await findLocalProjectMetadata(
     path.resolve(options.dir || process.cwd()),
   );
+  assertLocalProjectCanBeSaved(localProject);
   let buildId = await resolveRequiredBuildIdOrSelected(options, auth, {
     localProject,
   });
@@ -543,6 +615,21 @@ async function listBuilds({ options, auth }) {
   return Array.isArray(result.builds) ? result.builds : [];
 }
 
+async function listOpenSourceBuilds({ options, auth }) {
+  const url = new URL(`${options.apiUrl}/cli/open-source-builds`);
+  url.searchParams.set("limit", String(options.limit));
+  url.searchParams.set("sort", options.sort);
+  if (options.searchQuery) {
+    url.searchParams.set("search", options.searchQuery);
+  }
+  const result = await requestJson({
+    url: url.toString(),
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+  return Array.isArray(result.builds) ? result.builds : [];
+}
+
 async function loadBuildMetadata({ options, auth, buildId }) {
   const result = await loadBuildFiles({
     options,
@@ -556,6 +643,21 @@ async function loadBuildMetadata({ options, auth, buildId }) {
   return result.build;
 }
 
+async function loadOpenSourceBuildFiles({
+  options,
+  auth,
+  buildId,
+  includeContent,
+}) {
+  const url = new URL(`${options.apiUrl}/cli/build/${buildId}/open-source-files`);
+  if (!includeContent) url.searchParams.set("includeContent", "0");
+  return await requestJson({
+    url: url.toString(),
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
 async function loadBuildFiles({ options, auth, buildId, includeContent }) {
   const url = new URL(`${options.apiUrl}/cli/build/${buildId}/files`);
   if (!includeContent) url.searchParams.set("includeContent", "0");
@@ -566,6 +668,16 @@ async function loadBuildFiles({ options, auth, buildId, includeContent }) {
   });
 }
 
+async function forkBuild({ options, auth, buildId }) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/${buildId}/fork`,
+    authToken: auth.token,
+    body: {},
+    timeoutMs: options.timeoutMs,
+  });
+}
+
 async function saveProjectFiles({ options, auth, buildId, files, summary }) {
   return await requestJson({
     method: "PUT",
@@ -754,6 +866,40 @@ async function pullBuildFiles({ options, auth, buildId }) {
   };
 }
 
+async function pullReferenceFiles({ options, auth, buildId }) {
+  const result = await loadOpenSourceBuildFiles({
+    options,
+    auth,
+    buildId,
+    includeContent: true,
+  });
+  const build = result.build || { id: buildId, title: `Build ${buildId}` };
+  const files = Array.isArray(result.projectFiles) ? result.projectFiles : [];
+  const dir = path.resolve(options.dir || defaultReferenceDir(build));
+  await writeProjectFiles({ dir, files });
+  await writeReferenceInstructions({ dir });
+  await writeSdkReference({ dir });
+  await writeReferenceMetadata({
+    dir,
+    options,
+    build,
+    manifest: result.projectManifest || null,
+    reference: result.reference || {
+      readOnly: true,
+      forkable: true,
+      sourceBuildId: Number(build.id || buildId),
+    },
+    pulledAt: new Date().toISOString(),
+  });
+  return {
+    build,
+    dir,
+    fileCount: files.length,
+    manifest: result.projectManifest || null,
+    reference: result.reference || null,
+  };
+}
+
 async function writeAgentInstructions({ dir }) {
   for (const fileName of AGENT_INSTRUCTION_FILES) {
     const filePath = path.join(dir, fileName);
@@ -769,6 +915,21 @@ async function writeAgentInstructions({ dir }) {
   }
 }
 
+async function writeReferenceInstructions({ dir }) {
+  for (const fileName of AGENT_INSTRUCTION_FILES) {
+    const filePath = path.join(dir, fileName);
+    try {
+      const existing = await fs.readFile(filePath, "utf8");
+      if (!existing.includes(LUMINE_REFERENCE_INSTRUCTIONS_MARKER)) {
+        continue;
+      }
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    await fs.writeFile(filePath, LUMINE_REFERENCE_INSTRUCTIONS, "utf8");
+  }
+}
+
 async function writeSdkReference({ dir }) {
   const filePath = path.join(dir, SDK_REFERENCE_FILE);
   try {
@@ -965,6 +1126,7 @@ async function writeProjectMetadata({
           : null,
         apiUrl: options.apiUrl,
         siteUrl: options.siteUrl,
+        lumineCli: serializeLumineCliMetadata(options),
         manifest,
         pulledAt,
         lastSavedAt,
@@ -976,6 +1138,53 @@ async function writeProjectMetadata({
   );
 }
 
+async function writeReferenceMetadata({
+  dir,
+  options,
+  build,
+  manifest,
+  reference,
+  pulledAt,
+}) {
+  const metadataDir = path.join(dir, PROJECT_METADATA_DIR);
+  await fs.mkdir(metadataDir, { recursive: true });
+  const sourceBuildId =
+    Number(reference?.sourceBuildId || 0) || Number(build?.id || 0) || null;
+  await fs.writeFile(
+    path.join(metadataDir, PROJECT_METADATA_FILE),
+    JSON.stringify(
+      {
+        schemaVersion: 1,
+        buildId: sourceBuildId,
+        readOnly: true,
+        reference: {
+          readOnly: true,
+          forkable: true,
+          sourceBuildId,
+          sourceAppUrl: sourceBuildId ? `${options.siteUrl}/app/${sourceBuildId}` : null,
+        },
+        build: {
+          id: sourceBuildId,
+          title: build?.title || (sourceBuildId ? `Build ${sourceBuildId}` : ""),
+          role: "reference",
+          ownerUsername: build?.ownerUsername || null,
+          collaborationMode: build?.collaborationMode || "open_source",
+          canWrite: false,
+          canPublish: false,
+        },
+        apiUrl: options.apiUrl,
+        siteUrl: options.siteUrl,
+        lumineCli: serializeLumineCliMetadata(options),
+        manifest,
+        pulledAt,
+      },
+      null,
+      2,
+    ),
+    "utf8",
+  );
+}
+
 async function findLocalProjectMetadata(startDir) {
   let current = path.resolve(startDir || process.cwd());
   while (true) {
@@ -1002,6 +1211,29 @@ function resolveProjectDirForSave({ options, localProject }) {
   return process.cwd();
 }
 
+function assertLocalProjectCanBeSaved(localProject) {
+  const metadata = localProject?.metadata;
+  if (!metadata) return;
+  if (isReadOnlyReferenceMetadata(metadata)) {
+    const sourceBuildId =
+      Number(metadata.reference?.sourceBuildId || 0) ||
+      Number(metadata.buildId || 0) ||
+      Number(metadata.build?.id || 0) ||
+      0;
+    throw new Error(
+      `This is a read-only Lumine reference${sourceBuildId ? ` for Build ${sourceBuildId}` : ""}. Run \`lumine fork${sourceBuildId ? ` ${sourceBuildId}` : ""}\` to create an editable workspace.`,
+    );
+  }
+}
+
+function isReadOnlyReferenceMetadata(metadata) {
+  return (
+    metadata?.readOnly === true ||
+    metadata?.reference?.readOnly === true ||
+    metadata?.build?.role === "reference"
+  );
+}
+
 function resolveLocalProjectFilePath({ rootDir, projectPath }) {
   const relativePath = projectPathToRelativePath(projectPath);
   const root = path.resolve(rootDir);
@@ -1037,6 +1269,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.");
@@ -1048,6 +1294,23 @@ function printBuildList(builds) {
   });
 }
 
+function printOpenSourceBuildList(builds, options) {
+  if (!builds.length) {
+    const searchText = options.searchQuery
+      ? ` matching "${options.searchQuery}"`
+      : "";
+    console.log(`No public open-source Twinkle builds found${searchText}.`);
+    return;
+  }
+  const searchText = options.searchQuery ? ` for "${options.searchQuery}"` : "";
+  console.log(`Public open-source Twinkle builds${searchText}:`);
+  builds.forEach((build, index) => {
+    console.log(`${index + 1}. ${formatOpenSourceBuildListItem(build)}`);
+  });
+  console.log("Reference: lumine reference <build-id>");
+  console.log("Fork: lumine fork <build-id>");
+}
+
 function formatBuildListItem(build) {
   const role =
     build.role === "owner"
@@ -1057,6 +1320,16 @@ function formatBuildListItem(build) {
   return `${formatBuildTitle(build)} - ${role}, ${published}`;
 }
 
+function formatOpenSourceBuildListItem(build) {
+  const owner = build.ownerUsername ? ` by ${build.ownerUsername}` : "";
+  const stats = [
+    `${Math.max(0, Number(build.forkCount || 0))} forks`,
+    `${Math.max(0, Number(build.viewCount || 0))} views`,
+  ].join(", ");
+  const appUrl = build.appUrl ? ` - ${build.appUrl}` : "";
+  return `${formatBuildTitle(build)}${owner} - ${stats}${appUrl}`;
+}
+
 function formatBuildTitle(build) {
   return `${build.title || `Build ${build.id}`} (#${build.id})`;
 }
@@ -1095,6 +1368,39 @@ function printPullResult(result) {
   }
 }
 
+function printReferenceResult(result) {
+  const build = result.build || {};
+  const sourceBuildId =
+    Number(result.reference?.sourceBuildId || 0) || Number(build.id || 0);
+  const entryPath = result.manifest?.entryPath || "unknown";
+  console.log(`Referenced ${formatBuildTitle(build)}.`);
+  console.log(
+    `Pulled ${result.fileCount} file${result.fileCount === 1 ? "" : "s"} to ${result.dir}`,
+  );
+  console.log(`Entry: ${entryPath}`);
+  console.log("Mode: read-only reference");
+  console.log(`Next: cd ${shellQuote(result.dir)}`);
+  if (sourceBuildId) {
+    console.log(`Start from this app: lumine fork ${sourceBuildId}`);
+  }
+}
+
+function printForkResult({ forkResult, pullResult }) {
+  const build = pullResult.build || forkResult.build || {};
+  const sourceBuildId =
+    Number(forkResult.sourceBuild?.id || 0) ||
+    Number(forkResult.sourceBuild?.contentId || 0) ||
+    0;
+  console.log(
+    forkResult.alreadyExists
+      ? `Using your existing fork ${formatBuildTitle(build)}.`
+      : `Forked Build ${sourceBuildId || "source"} into ${formatBuildTitle(
+          build,
+        )}.`,
+  );
+  printPullResult(pullResult);
+}
+
 function printSaveResult({ result, build, dir, files }) {
   const entryPath = result.projectManifest?.entryPath || "unknown";
   const version = result.artifactVersion?.versionNumber
@@ -1222,6 +1528,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 =
@@ -1236,7 +1653,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];
@@ -1263,12 +1686,26 @@ function parseArgs(args) {
   return {
     command,
     target: raw.url || raw.target || positional[0] || "",
+    searchQuery:
+      String(
+        raw.search ||
+          raw.query ||
+          (command === "explore" ? positional.join(" ") : ""),
+      ).trim() || "",
+    sort: normalizeOpenSourceSort(raw.sort),
     apiUrl: trimTrailingSlash(
       String(raw.apiUrl || process.env.TWINKLE_API_URL || DEFAULT_API_URL),
     ),
     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,
     ),
@@ -1291,6 +1728,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,
@@ -1312,6 +1750,19 @@ async function resolveRequiredBuildIdOrSelected(
     (await findLocalProjectMetadata(
       path.resolve(options.dir || process.cwd()),
     ));
+  if (
+    resolvedLocalProject?.metadata &&
+    isReadOnlyReferenceMetadata(resolvedLocalProject.metadata)
+  ) {
+    const sourceBuildId =
+      Number(resolvedLocalProject.metadata.reference?.sourceBuildId || 0) ||
+      Number(resolvedLocalProject.metadata.buildId || 0) ||
+      Number(resolvedLocalProject.metadata.build?.id || 0) ||
+      0;
+    throw new Error(
+      `This is a read-only Lumine reference${sourceBuildId ? ` for Build ${sourceBuildId}` : ""}. Run \`lumine fork${sourceBuildId ? ` ${sourceBuildId}` : ""}\` to create an editable workspace, or pass an explicit Build URL.`,
+    );
+  }
   const localBuildId = Number(resolvedLocalProject?.metadata?.buildId || 0);
   if (localBuildId > 0) return localBuildId;
   const selectedBuildId = Number(auth?.selectedBuildId || 0);
@@ -1403,6 +1854,14 @@ function parseBoolean(value, fallback) {
   return fallback;
 }
 
+function normalizeOpenSourceSort(value) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (["recent", "popular", "forks"].includes(normalized)) return normalized;
+  return "forks";
+}
+
 async function openBrowser(url) {
   const command =
     process.platform === "darwin"
@@ -1435,6 +1894,12 @@ function defaultWorkspaceDir(build) {
   return `twinkle-${titleSlug || "build"}-${buildId}`;
 }
 
+function defaultReferenceDir(build) {
+  const titleSlug = slugify(build?.title || "");
+  const buildId = Number(build?.id || 0) || "build";
+  return `twinkle-reference-${titleSlug || "build"}-${buildId}`;
+}
+
 function slugify(value) {
   return String(value || "")
     .toLowerCase()
@@ -1454,8 +1919,11 @@ function printHelp() {
   lumine whoami
   lumine logout
   lumine projects
+  lumine explore [search terms]
   lumine select [twinkle-build-url]
   lumine pull [twinkle-build-url]
+  lumine reference <twinkle-build-url>
+  lumine fork <twinkle-build-url>
   lumine save
   lumine check [twinkle-build-url]
   lumine launch [twinkle-build-url]
@@ -1463,6 +1931,9 @@ function printHelp() {
 Examples:
   npx @stage5/lumine@latest
   npx @stage5/lumine@latest login
+  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 pull
   npx @stage5/lumine@latest save
   npx @stage5/lumine@latest save --publish
@@ -1476,9 +1947,12 @@ Options:
   --auth-token <token>  Override saved login
   --dir <path>          Directory for pulled project files
   --summary <text>      Save summary
+  --search <text>       Search public open-source Builds
+  --sort <sort>         Sort open-source Builds: forks, popular, recent
   --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.3",
+  "version": "0.1.5",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {