@stage5/lumine 0.1.3 → 0.1.4

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,10 @@ 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.
+
 After pulling a project, run an agent from the pulled folder:
 
 ```bash

package/bin/lumine.js

@@ -29,6 +29,8 @@ 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,
@@ -90,6 +92,20 @@ 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 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 +113,11 @@ const COMMANDS = new Set([
   "logout",
   "whoami",
   "projects",
+  "explore",
   "select",
   "pull",
+  "reference",
+  "fork",
   "save",
   "push",
   "check",
@@ -138,6 +157,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 +169,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 +317,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 +363,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 +606,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 +634,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 +659,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 +857,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 +906,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 {
@@ -976,6 +1128,52 @@ 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,
+        manifest,
+        pulledAt,
+      },
+      null,
+      2,
+    ),
+    "utf8",
+  );
+}
+
 async function findLocalProjectMetadata(startDir) {
   let current = path.resolve(startDir || process.cwd());
   while (true) {
@@ -1002,6 +1200,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);
@@ -1048,6 +1269,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 +1295,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 +1343,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
@@ -1263,6 +1544,13 @@ 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),
     ),
@@ -1312,6 +1600,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 +1704,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 +1744,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 +1769,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 +1781,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,6 +1797,8 @@ 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

package/package.json

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