@stage5/lumine 0.2.13 → 0.2.14

package/README.md

@@ -40,7 +40,14 @@ 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
+After editing pulled files, run `lumine save` from that folder. Workspaces record
+a `filesHash` in `.twinkle/lumine-project.json` when you pull or save; the next
+save sends that hash so the server can reject a stale checkout instead of
+silently overwriting newer files. Saves from a folder with no `filesHash` are
+refused unless you pass `--force` (intentional overwrite). Prefer
+`lumine pull` to resync before saving if the folder might be out of date.
+
+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
 unpublished changes. For projects you own, run `lumine launch` to publish the

package/lib/api.js

@@ -139,6 +139,7 @@ export async function saveProjectFiles({
   files,
   summary,
   baseFilesHash,
+  force = false,
 }) {
   return await requestJson({
     method: "PUT",
@@ -152,6 +153,9 @@ export async function saveProjectFiles({
       // reject it instead of silently rewinding newer state (e.g. a branch
       // merged into main after our pull).
       ...(baseFilesHash ? { baseFilesHash } : {}),
+      // Intentional overwrite of a non-empty project without a base claim.
+      // Required when the workspace has no filesHash (old/stale checkout).
+      ...(force ? { force: true } : {}),
     },
     timeoutMs: options.timeoutMs,
   });

package/lib/commands.js

@@ -509,13 +509,36 @@ export async function save(options) {
   const files = await collectProjectFiles(dir);
   assertProjectFilesWithinLimits(files);
   // Only claim a base snapshot when this workspace was pulled from the same
-  // build we are saving to; otherwise the save stays unguarded (old behavior).
+  // build we are saving to. Missing filesHash used to mean "unguarded save",
+  // which let stale checkouts silently rewind newer server versions — refuse
+  // that path unless --force is explicit.
+  const metadataBuildId = Number(localProject?.metadata?.buildId || 0);
+  const metadataFilesHash =
+    typeof localProject?.metadata?.filesHash === "string" &&
+    localProject.metadata.filesHash.trim()
+      ? localProject.metadata.filesHash.trim()
+      : null;
   const baseFilesHash =
-    !options.force &&
-    Number(localProject?.metadata?.buildId || 0) === Number(buildId) &&
-    typeof localProject?.metadata?.filesHash === "string"
-      ? localProject.metadata.filesHash
+    !options.force && metadataBuildId === Number(buildId) && metadataFilesHash
+      ? metadataFilesHash
       : null;
+  if (!options.force && !baseFilesHash) {
+    throw new Error(
+      [
+        "Save refused: this workspace has no filesHash (server snapshot token).",
+        "That usually means an old or stale checkout that never recorded what",
+        "it was based on — saving it would overwrite the server without a guard.",
+        "Run `lumine pull` to sync with the server (local edits are preserved),",
+        "then save again. To intentionally overwrite the server with these",
+        "local files, re-run with --force.",
+      ].join("\n"),
+    );
+  }
+  if (options.force && !baseFilesHash) {
+    console.error(
+      "lumine: warning — saving with --force and no filesHash; this overwrites the server project with local files and skips the stale-workspace guard.",
+    );
+  }
   let result;
   try {
     result = await saveProjectFiles({
@@ -525,6 +548,7 @@ export async function save(options) {
       files,
       summary: options.summary || DEFAULT_SAVE_SUMMARY,
       baseFilesHash,
+      force: Boolean(options.force),
     });
   } catch (error) {
     if (error?.data?.code === "build_project_files_stale") {
@@ -537,6 +561,17 @@ export async function save(options) {
         ].join("\n"),
       );
     }
+    if (error?.data?.code === "build_project_files_base_required") {
+      throw new Error(
+        [
+          "Save rejected: the server requires a filesHash base for this project",
+          "(non-empty projects cannot be saved from a workspace that never",
+          "recorded its server snapshot).",
+          "Run `lumine pull` to establish a base, then save again,",
+          "or re-run with --force to overwrite deliberately.",
+        ].join("\n"),
+      );
+    }
     throw error;
   }
   build = result.build ||
@@ -1954,7 +1989,7 @@ Options:
   --description <text>  Optional New Build description
   --no-description      Skip the New Build description prompt
   --summary <text>      Save summary
-  --force               Save even if the server files changed since this workspace was pulled
+  --force               Overwrite server files even if this workspace is stale or missing filesHash
   --search <text>       Search public open-source Builds
   --sort <sort>         Sort open-source Builds: forks, popular, recent
   --publish             Publish after saving

package/lib/constants.js

@@ -143,6 +143,12 @@ Lumine CLI as the source of truth for saving this workspace back to Twinkle.
 
 - Edit only project files in this workspace.
 - Keep /index.html or /index.htm as the entry file.
+- Before editing an existing project, confirm \`.twinkle/lumine-project.json\`
+  has a \`filesHash\` and matches the build you intend. If the folder may be
+  stale (old pull, missing files, fewer files than last known save), run
+  \`lumine pull\` first — never \`lumine save\` from a guessed/old checkout.
+  Saves without \`filesHash\` are refused (use \`--force\` only for deliberate
+  overwrites). A stale save can delete newer server files.
 - Run lumine save from this folder after edits, with a short summary:
 
 \`\`\`bash

package/lib/workspace.js

@@ -597,7 +597,8 @@ export async function writeProjectMetadata({
         lastSavedAt,
         // Server-issued hash of the project files this workspace is based on.
         // `lumine save` sends it back so a stale workspace cannot silently
-        // rewind newer server state; null means "unknown" (unguarded save).
+        // rewind newer server state. Missing/null refuses save unless --force
+        // (server also rejects unguarded saves onto non-empty projects).
         filesHash: typeof filesHash === "string" ? filesHash : null,
       },
       null,

package/package.json

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