@stage5/lumine 0.2.12 → 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

@@ -132,7 +132,15 @@ export async function createBuild({ options, auth, title, description }) {
   });
 }
 
-export async function saveProjectFiles({ options, auth, buildId, files, summary }) {
+export async function saveProjectFiles({
+  options,
+  auth,
+  buildId,
+  files,
+  summary,
+  baseFilesHash,
+  force = false,
+}) {
   return await requestJson({
     method: "PUT",
     url: `${options.apiUrl}/build/${buildId}/project-files`,
@@ -141,6 +149,13 @@ export async function saveProjectFiles({ options, auth, buildId, files, summary
       files,
       createVersion: true,
       summary,
+      // Proves this save is based on the snapshot we pulled so the server can
+      // 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

@@ -77,6 +77,7 @@ import {
   isIndexHtmlPath,
   isReadOnlyReferenceMetadata,
   removeLocalProjectFilesNotIn,
+  stashLocalProjectFilesBeforePull,
   resolveProjectDirForSave,
   writeAgentInstructions,
   writeInstructionFiles,
@@ -331,17 +332,41 @@ export async function updateBranchFromMain(options) {
   }
   let dir = null;
   let projectFiles = null;
+  let baseFilesHash = null;
   if (Number(localProject?.metadata?.buildId || 0) === contributionBuildId) {
     dir = resolveProjectDirForSave({ options, localProject });
     projectFiles = await collectProjectFiles(dir);
+    baseFilesHash =
+      typeof localProject?.metadata?.filesHash === "string" &&
+      localProject.metadata.filesHash.trim()
+        ? localProject.metadata.filesHash.trim()
+        : null;
+    if (!baseFilesHash) {
+      throw new Error(
+        "This branch workspace has no verified server file base. Run `lumine pull` before `lumine update-from-main` so local edits cannot overwrite newer branch work.",
+      );
+    }
+  }
+  let result;
+  try {
+    result = await requestJson({
+      method: "POST",
+      url: `${options.apiUrl}/build/${rootBuildId}/contributions/${contributionBuildId}/update-from-main`,
+      authToken: auth.token,
+      body: projectFiles ? { projectFiles, baseFilesHash } : {},
+      timeoutMs: options.timeoutMs,
+    });
+  } catch (error) {
+    if (error?.data?.code === "build_project_files_stale") {
+      throw new Error(
+        [
+          "Update from main rejected: this branch changed on the server after the workspace was loaded.",
+          "Run `lumine pull` to load the canonical branch first, then reapply the backed-up local edits and retry.",
+        ].join("\n"),
+      );
+    }
+    throw error;
   }
-  const result = await requestJson({
-    method: "POST",
-    url: `${options.apiUrl}/build/${rootBuildId}/contributions/${contributionBuildId}/update-from-main`,
-    authToken: auth.token,
-    body: projectFiles ? { projectFiles } : {},
-    timeoutMs: options.timeoutMs,
-  });
   const mergedFiles = Array.isArray(result.projectFiles)
     ? result.projectFiles
     : [];
@@ -353,15 +378,28 @@ export async function updateBranchFromMain(options) {
       auth,
       buildId: contributionBuildId,
     }).catch(() => null);
-    if (refreshed) {
-      await writeProjectMetadata({
-        dir,
-        options,
-        build: refreshed,
-        manifest: localProject?.metadata?.manifest || null,
-        pulledAt: new Date().toISOString(),
-      });
-    }
+    const returnedContribution =
+      Number(result?.contribution?.id || 0) === contributionBuildId
+        ? result.contribution
+        : null;
+    // The sync response has already committed these files and their hash. A
+    // transient follow-up metadata failure must not leave the workspace with
+    // its pre-merge base hash, or its next legitimate save will be rejected.
+    // Preserve CLI permission fields from the confirmed pre-sync load when
+    // falling back to the canonical contribution returned by the mutation.
+    const metadataBuild = refreshed || {
+      ...build,
+      ...(returnedContribution || {}),
+      id: contributionBuildId,
+    };
+    await writeProjectMetadata({
+      dir,
+      options,
+      build: metadataBuild,
+      manifest: localProject?.metadata?.manifest || null,
+      pulledAt: new Date().toISOString(),
+      filesHash: typeof result.filesHash === "string" ? result.filesHash : null,
+    });
   }
   printUpdateFromMainResult({ result, build, dir, mergedFiles });
 }
@@ -470,13 +508,72 @@ export async function save(options) {
   const dir = resolveProjectDirForSave({ options, localProject });
   const files = await collectProjectFiles(dir);
   assertProjectFilesWithinLimits(files);
-  const result = await saveProjectFiles({
-    options,
-    auth,
-    buildId,
-    files,
-    summary: options.summary || DEFAULT_SAVE_SUMMARY,
-  });
+  // Only claim a base snapshot when this workspace was pulled from the same
+  // 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 && 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({
+      options,
+      auth,
+      buildId,
+      files,
+      summary: options.summary || DEFAULT_SAVE_SUMMARY,
+      baseFilesHash,
+      force: Boolean(options.force),
+    });
+  } catch (error) {
+    if (error?.data?.code === "build_project_files_stale") {
+      throw new Error(
+        [
+          "Save rejected: the project changed on the server since this workspace was pulled",
+          "(for example a merged branch or a save from another session).",
+          "Run `lumine pull` to sync the canonical server files first,",
+          "or re-run with --force to overwrite the server's current files anyway.",
+        ].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 ||
     build ||
     (await loadBuildMetadata({ options, auth, buildId }).catch(() => null)) || {
@@ -490,6 +587,7 @@ export async function save(options) {
     build,
     manifest: result.projectManifest || null,
     lastSavedAt: new Date().toISOString(),
+    filesHash: typeof result.filesHash === "string" ? result.filesHash : null,
   });
   printSaveResult({ result, build, dir, files });
 
@@ -663,11 +761,15 @@ export async function loadTargetBuildMetadata({ options, auth }) {
   return await loadBuildMetadata({ options, auth, buildId });
 }
 
-export async function resolveBuildForSave({ options, auth, buildId, localProject }) {
+export async function resolveBuildForSave({
+  options,
+  auth,
+  buildId,
+  localProject,
+}) {
   const localBuild = localProject?.metadata?.build;
   const localBuildId =
-    Number(localBuild?.id || 0) ||
-    Number(localProject?.metadata?.buildId || 0);
+    Number(localBuild?.id || 0) || Number(localProject?.metadata?.buildId || 0);
   const build =
     localBuild && localBuildId === Number(buildId)
       ? { ...localBuild, id: buildId }
@@ -722,7 +824,11 @@ export function isCollaboratorMainBuild(build) {
   );
 }
 
-export async function ensureDefaultContributionBranch({ options, auth, build }) {
+export async function ensureDefaultContributionBranch({
+  options,
+  auth,
+  build,
+}) {
   const rootBuildId =
     Number(build?.contributionRootBuildId || 0) || Number(build?.id || 0);
   if (!rootBuildId) {
@@ -817,7 +923,29 @@ export async function pullBuildFiles({ options, auth, buildId }) {
   const build = result.build || { id: buildId, title: `Build ${buildId}` };
   const files = Array.isArray(result.projectFiles) ? result.projectFiles : [];
   const dir = path.resolve(options.dir || defaultWorkspaceDir(build));
+  // Preserve local work BEFORE server files land: pull is the recommended
+  // stale-save recovery step, and the edits that triggered the rejection are
+  // usually in files the server snapshot also contains — writing first would
+  // destroy them. Extras (paths not in the snapshot) are moved out so the
+  // pulled hash's claim that this workspace matches the server stays true;
+  // modified tracked files are copied so the pre-pull content stays
+  // recoverable after the overwrite.
+  const { movedPaths, backedUpPaths } = await stashLocalProjectFilesBeforePull({
+    dir,
+    files,
+  });
   await writeProjectFiles({ dir, files });
+  const stashDirLabel = path.join(PROJECT_METADATA_DIR, "removed");
+  if (movedPaths.length > 0) {
+    console.log(
+      `Moved ${movedPaths.length} local file${movedPaths.length === 1 ? "" : "s"} not in the server project to ${stashDirLabel}/: ${movedPaths.join(", ")}`,
+    );
+  }
+  if (backedUpPaths.length > 0) {
+    console.log(
+      `Backed up ${backedUpPaths.length} locally modified file${backedUpPaths.length === 1 ? "" : "s"} to ${stashDirLabel}/ before overwriting with the server version: ${backedUpPaths.join(", ")}`,
+    );
+  }
   await writeAgentInstructions({ dir });
   await writeSdkReference({ dir });
   await writeProjectMetadata({
@@ -826,6 +954,7 @@ export async function pullBuildFiles({ options, auth, buildId }) {
     build,
     manifest: result.projectManifest || null,
     pulledAt: new Date().toISOString(),
+    filesHash: typeof result.filesHash === "string" ? result.filesHash : null,
   });
   // Best-effort asset manifest so terminal agents know what media already
   // exists (the workspace UI gives Lumine the same context). Never fail the
@@ -916,7 +1045,10 @@ export async function pullMainBuildFiles({ options, auth, build }) {
     buildId: rootBuildId,
     includeContent: true,
   });
-  const rootBuild = result.build || { id: rootBuildId, title: `Build ${rootBuildId}` };
+  const rootBuild = result.build || {
+    id: rootBuildId,
+    title: `Build ${rootBuildId}`,
+  };
   const files = Array.isArray(result.projectFiles) ? result.projectFiles : [];
   // Never nest a main checkout inside another Lumine workspace (a later save
   // there would upload it as project files) — default to a sibling instead.
@@ -933,7 +1065,10 @@ export async function pullMainBuildFiles({ options, auth, build }) {
       (enclosingIsThisMain
         ? enclosing.rootDir
         : enclosing
-          ? path.join(path.dirname(enclosing.rootDir), defaultMainCheckoutDir(rootBuild))
+          ? path.join(
+              path.dirname(enclosing.rootDir),
+              defaultMainCheckoutDir(rootBuild),
+            )
           : defaultMainCheckoutDir(rootBuild)),
   );
   await writeProjectFiles({ dir, files });
@@ -954,7 +1089,9 @@ export async function pullMainBuildFiles({ options, auth, build }) {
     pulledAt: new Date().toISOString(),
   });
   console.log(`Pulled main for ${formatBuildTitle(rootBuild)} (read-only).`);
-  console.log(`Pulled ${files.length} file${files.length === 1 ? "" : "s"} to ${dir}`);
+  console.log(
+    `Pulled ${files.length} file${files.length === 1 ? "" : "s"} to ${dir}`,
+  );
   console.log(
     `Edits belong on your branch: \`lumine pull ${rootBuildId}\`, and \`lumine update-from-main\` brings main's changes into it.`,
   );
@@ -1096,9 +1233,7 @@ export function printVersionList({ result }) {
     console.log(`No previous saves found for ${formatBuildTitle(build)}.`);
     return;
   }
-  console.log(
-    `Previous saves for ${formatBuildTitle(build)} (newest first):`,
-  );
+  console.log(`Previous saves for ${formatBuildTitle(build)} (newest first):`);
   for (const version of versions) {
     const author =
       version.createdByUsername ||
@@ -1321,7 +1456,9 @@ export function printPullResult(result) {
     return;
   }
   if (result.fileCount === 0) {
-    console.log("No project files yet. Create /index.html before your first save.");
+    console.log(
+      "No project files yet. Create /index.html before your first save.",
+    );
   }
   console.log('Codex: codex "Read AGENTS.md, then make the requested change."');
   console.log(
@@ -1403,7 +1540,9 @@ export function printContributionDiff({ result, build }) {
     ? result.diff.changedFiles
     : [];
   const branchNumber = Number(build.contributionBranchNumber || 0) || 0;
-  const branchLabel = branchNumber ? `branch ${branchNumber}` : `branch #${build.id}`;
+  const branchLabel = branchNumber
+    ? `branch ${branchNumber}`
+    : `branch #${build.id}`;
   console.log(`Diff for ${branchLabel}:`);
   console.log(
     `- total=${summary.total ?? files.length} added=${summary.added ?? 0} ` +
@@ -1470,14 +1609,18 @@ export function printContributionActionResult({
   const projectFiles = Array.isArray(result.projectFiles)
     ? result.projectFiles
     : [];
-  console.log(`${action} branch #${contributionBuildId} for Build #${rootBuildId}.`);
+  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(
+      "Merge wrote conflict markers. Resolve them in the Build workspace.",
+    );
   }
   console.log(`Main workspace: ${rootBuildId}`);
 }
@@ -1502,6 +1645,7 @@ export function parseArgs(args) {
     "noDescription",
     "publish",
     "save",
+    "force",
     "noUpdateCheck",
     "allowWrite",
     "main",
@@ -1552,13 +1696,11 @@ export function parseArgs(args) {
     target: raw.url || raw.target || positional[0] || "",
     title:
       String(
-        raw.title ||
-          (command === "new" ? positional.join(" ") : ""),
+        raw.title || (command === "new" ? positional.join(" ") : ""),
       ).trim() || "",
-    description:
-      Object.prototype.hasOwnProperty.call(raw, "description")
-        ? String(raw.description || "").trim()
-        : null,
+    description: Object.prototype.hasOwnProperty.call(raw, "description")
+      ? String(raw.description || "").trim()
+      : null,
     descriptionProvided: Object.prototype.hasOwnProperty.call(
       raw,
       "description",
@@ -1608,6 +1750,7 @@ export function parseArgs(args) {
       : 0,
     summary: raw.summary ? String(raw.summary) : "",
     publish: parseBoolean(raw.publish, false),
+    force: parseBoolean(raw.force, false),
     saveFirst: parseBoolean(raw.save, false),
     limit: Math.min(
       Math.max(
@@ -1709,7 +1852,9 @@ export async function resolveNewBuildTitle(options) {
   const title = String(options.title || "").trim();
   if (title) return title;
   if (!input.isTTY || !output.isTTY) {
-    throw new Error('Pass a title: `lumine new "My Build"` or `lumine new --title "My Build"`.');
+    throw new Error(
+      'Pass a title: `lumine new "My Build"` or `lumine new --title "My Build"`.',
+    );
   }
   const rl = readline.createInterface({ input, output });
   try {
@@ -1739,7 +1884,11 @@ export async function resolveNewBuildDescription(options) {
   }
 }
 
-export async function resolveBuildReferenceBuildId({ options, auth, reference }) {
+export async function resolveBuildReferenceBuildId({
+  options,
+  auth,
+  reference,
+}) {
   if (reference.branchNumber > 0) {
     const build = await resolveBranchBuild({
       options,
@@ -1840,6 +1989,7 @@ Options:
   --description <text>  Optional New Build description
   --no-description      Skip the New Build description prompt
   --summary <text>      Save summary
+  --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

@@ -105,11 +105,24 @@ export async function collectWorkspaceTextFilesLenient(dir) {
   return files;
 }
 
-export async function collectProjectFilesFromDir({ root, dir, files, lenient = false }) {
+async function walkWorkspaceProjectEntries({
+  root,
+  dir,
+  onEntry,
+  onDirectory,
+  allowMissingRoot = false,
+}) {
   let entries = [];
   try {
     entries = await fs.readdir(dir, { withFileTypes: true });
   } catch (error) {
+    if (
+      allowMissingRoot &&
+      error.code === "ENOENT" &&
+      path.resolve(dir) === path.resolve(root)
+    ) {
+      return;
+    }
     if (error.code === "ENOENT") {
       throw new Error(`Project directory does not exist: ${dir}`);
     }
@@ -117,10 +130,10 @@ export async function collectProjectFilesFromDir({ root, dir, files, lenient = f
   }
 
   for (const entry of entries) {
-    if (entry.isDirectory() && EXCLUDED_UPLOAD_DIRS.has(entry.name)) continue;
-    if (entry.isFile() && EXCLUDED_UPLOAD_FILES.has(entry.name)) continue;
     const fullPath = path.join(dir, entry.name);
     if (entry.isDirectory()) {
+      await onDirectory?.({ entry, fullPath });
+      if (EXCLUDED_UPLOAD_DIRS.has(entry.name)) continue;
       // A nested Lumine checkout (its own .twinkle metadata) is another
       // project that happens to sit here — never upload it as project files.
       if (await isNestedLumineCheckout(fullPath)) {
@@ -129,34 +142,85 @@ export async function collectProjectFilesFromDir({ root, dir, files, lenient = f
         );
         continue;
       }
-      await collectProjectFilesFromDir({ root, dir: fullPath, files, lenient });
-      continue;
-    }
-    if (!entry.isFile()) continue;
-    const buffer = await fs.readFile(fullPath);
-    const encodingIssue = detectProjectFileEncodingIssue(buffer);
-    if (encodingIssue) {
-      if (lenient) continue;
-      const relativePath = localFilePathToProjectPath({
+      await walkWorkspaceProjectEntries({
         root,
-        filePath: fullPath,
+        dir: fullPath,
+        onEntry,
+        onDirectory,
       });
-      if (encodingIssue === "utf16") {
+      continue;
+    }
+    if (entry.isFile() && EXCLUDED_UPLOAD_FILES.has(entry.name)) continue;
+    await onEntry({ entry, fullPath });
+  }
+}
+
+export async function collectProjectFilesFromDir({
+  root,
+  dir,
+  files,
+  lenient = false,
+}) {
+  await walkWorkspaceProjectEntries({
+    root,
+    dir,
+    async onEntry({ entry, fullPath }) {
+      if (!entry.isFile()) return;
+      const buffer = await fs.readFile(fullPath);
+      const encodingIssue = detectProjectFileEncodingIssue(buffer);
+      if (encodingIssue) {
+        if (lenient) return;
+        const relativePath = localFilePathToProjectPath({
+          root,
+          filePath: fullPath,
+        });
+        if (encodingIssue === "utf16") {
+          throw new Error(
+            `Cannot save ${relativePath}: it is UTF-16 encoded. Twinkle project files must be UTF-8 text — re-save the file as UTF-8 and retry.`,
+          );
+        }
         throw new Error(
-          `Cannot save ${relativePath}: it is UTF-16 encoded. Twinkle project files must be UTF-8 text — re-save the file as UTF-8 and retry.`,
+          `Cannot save binary file ${relativePath}. Twinkle project files must be text files. ` +
+            `Upload media as a build asset instead: move the file out of this workspace, run ` +
+            "`lumine assets upload <path-to-file>`, and reference the printed URL from your code.",
         );
       }
-      throw new Error(
-        `Cannot save binary file ${relativePath}. Twinkle project files must be text files. ` +
-          `Upload media as a build asset instead: move the file out of this workspace, run ` +
-          "`lumine assets upload <path-to-file>`, and reference the printed URL from your code.",
+      files.push({
+        path: localFilePathToProjectPath({ root, filePath: fullPath }),
+        content: buffer.toString("utf8"),
+      });
+    },
+  });
+}
+
+// Pull preservation needs a lossless inventory, not the upload-oriented text
+// collector above. Binary/UTF-16 files are still local work, and special
+// entries such as symlinks must be relocated before writeProjectFiles can
+// follow or replace their server-owned paths. Any scan/read error other than a
+// missing fresh-pull root aborts the pull before local state is touched.
+async function collectWorkspaceEntriesBeforePull(dir) {
+  const root = path.resolve(dir);
+  const entries = [];
+  const directories = [];
+  await walkWorkspaceProjectEntries({
+    root,
+    dir: root,
+    allowMissingRoot: true,
+    onDirectory({ fullPath }) {
+      directories.push(
+        localFilePathToProjectPath({ root, filePath: fullPath }),
       );
-    }
-    files.push({
-      path: localFilePathToProjectPath({ root, filePath: fullPath }),
-      content: buffer.toString("utf8"),
-    });
-  }
+    },
+    async onEntry({ entry, fullPath }) {
+      const isRegularFile = entry.isFile();
+      entries.push({
+        path: localFilePathToProjectPath({ root, filePath: fullPath }),
+        isRegularFile,
+        content: isRegularFile ? await fs.readFile(fullPath) : null,
+      });
+    },
+  });
+  return { entries, directories };
 }
 
 // UTF-16 BOMs get their own error (the file is text, just mis-encoded); NUL
@@ -180,7 +244,9 @@ export function detectProjectFileEncodingIssue(buffer) {
 
 export async function isNestedLumineCheckout(dir) {
   try {
-    await fs.access(path.join(dir, PROJECT_METADATA_DIR, PROJECT_METADATA_FILE));
+    await fs.access(
+      path.join(dir, PROJECT_METADATA_DIR, PROJECT_METADATA_FILE),
+    );
     return true;
   } catch {
     return false;
@@ -268,7 +334,10 @@ export function countEffectiveLines(value) {
     .reduce(
       (total, line) =>
         total +
-        Math.max(1, Math.ceil(line.length / PROJECT_EFFECTIVE_LINE_MAX_COLUMNS)),
+        Math.max(
+          1,
+          Math.ceil(line.length / PROJECT_EFFECTIVE_LINE_MAX_COLUMNS),
+        ),
       0,
     );
 }
@@ -296,7 +365,8 @@ export function collectProjectLimitFindings(files) {
     }
   }
   const totalBytes = files.reduce(
-    (total, file) => total + Buffer.byteLength(String(file.content || ""), "utf8"),
+    (total, file) =>
+      total + Buffer.byteLength(String(file.content || ""), "utf8"),
     0,
   );
   if (totalBytes > PROJECT_MAX_TOTAL_BYTES_DEFAULT) {
@@ -356,6 +426,129 @@ export async function removeLocalProjectFilesNotIn({ dir, files }) {
   }
 }
 
+// Non-destructive local-work preservation for `lumine pull` into an existing
+// workspace. Pull is the recommended recovery step after a stale-save
+// rejection, so it must never destroy unsaved local work — and that work is
+// usually edits to files the server snapshot ALSO contains, which is why this
+// must run BEFORE the server files are written over them:
+// - local files absent from the server snapshot may be server-side deletions
+//   or brand-new unsaved work: MOVE them into .twinkle/removed/<timestamp>/
+//   (excluded from uploads) so a leftover file cannot pass the stale guard on
+//   the next save and silently resurrect itself
+// - local files whose content differs from the incoming server copy are about
+//   to be overwritten: COPY them into the same stash so the pre-pull edits
+//   remain recoverable
+// Returns { movedPaths, backedUpPaths } of stashed project paths.
+export async function stashLocalProjectFilesBeforePull({ dir, files }) {
+  const serverContentByPath = new Map(
+    files.map((file) => [String(file.path), String(file.content || "")]),
+  );
+  const {
+    entries: localFiles,
+    directories: localDirectoryPaths,
+  } = await collectWorkspaceEntriesBeforePull(dir);
+  const movedPaths = new Set();
+  const backedUpPaths = new Set();
+  let stashRoot = null;
+  const ensureStashRoot = () => {
+    if (!stashRoot) {
+      const stampedDirName = new Date().toISOString().replace(/[:.]/g, "-");
+      stashRoot = path.join(
+        dir,
+        PROJECT_METADATA_DIR,
+        "removed",
+        stampedDirName,
+      );
+    }
+    return stashRoot;
+  };
+  const stashPathFor = (projectPath) =>
+    path.join(
+      ensureStashRoot(),
+      ...projectPath.split("/").filter(Boolean),
+    );
+
+  // Resolve directory -> file transitions before processing individual local
+  // entries. Moving descendants first would leave their empty parent behind,
+  // and writeProjectFiles would then fail with EISDIR when the server snapshot
+  // writes a regular file at that path. Moving the directory as one unit also
+  // preserves excluded or nested-workspace content that the inventory skips.
+  const stashedDirectoryPaths = [];
+  const localDirectoryPathSet = new Set(localDirectoryPaths);
+  const incomingProjectPaths = [...serverContentByPath.keys()].sort(
+    (a, b) => a.split("/").length - b.split("/").length,
+  );
+  for (const projectPath of incomingProjectPaths) {
+    if (
+      stashedDirectoryPaths.some((directoryPath) =>
+        projectPath.startsWith(`${directoryPath}/`),
+      )
+    ) {
+      continue;
+    }
+    if (!localDirectoryPathSet.has(projectPath)) continue;
+
+    const sourcePath = resolveLocalProjectFilePath({
+      rootDir: dir,
+      projectPath,
+    });
+    const stashPath = stashPathFor(projectPath);
+    await fs.mkdir(path.dirname(stashPath), { recursive: true });
+    await fs.rename(sourcePath, stashPath);
+    stashedDirectoryPaths.push(projectPath);
+    for (const localFile of localFiles) {
+      if (!localFile.path.startsWith(`${projectPath}/`)) continue;
+      if (serverContentByPath.has(localFile.path)) {
+        backedUpPaths.add(localFile.path);
+      } else {
+        movedPaths.add(localFile.path);
+      }
+    }
+  }
+
+  for (const file of localFiles) {
+    if (
+      stashedDirectoryPaths.some((directoryPath) =>
+        file.path.startsWith(`${directoryPath}/`),
+      )
+    ) {
+      continue;
+    }
+    const serverContent = serverContentByPath.get(file.path);
+    const isTracked = serverContent !== undefined;
+    if (
+      isTracked &&
+      file.isRegularFile &&
+      file.content.equals(Buffer.from(serverContent, "utf8"))
+    ) {
+      continue;
+    }
+    const sourcePath = resolveLocalProjectFilePath({
+      rootDir: dir,
+      projectPath: file.path,
+    });
+    const stashPath = stashPathFor(file.path);
+    await fs.mkdir(path.dirname(stashPath), { recursive: true });
+    if (isTracked && file.isRegularFile) {
+      await fs.copyFile(sourcePath, stashPath);
+      backedUpPaths.add(file.path);
+    } else {
+      // Non-regular entries must move even when tracked: leaving a symlink at
+      // the server path would let writeProjectFiles overwrite its target.
+      await fs.rename(sourcePath, stashPath);
+      if (isTracked) {
+        backedUpPaths.add(file.path);
+      } else {
+        movedPaths.add(file.path);
+      }
+    }
+  }
+  return {
+    movedPaths: [...movedPaths],
+    backedUpPaths: [...backedUpPaths],
+  };
+}
+
 export async function writeProjectMetadata({
   dir,
   options,
@@ -363,6 +556,7 @@ export async function writeProjectMetadata({
   manifest,
   pulledAt,
   lastSavedAt,
+  filesHash,
 }) {
   const metadataDir = path.join(dir, PROJECT_METADATA_DIR);
   await fs.mkdir(metadataDir, { recursive: true });
@@ -401,6 +595,11 @@ export async function writeProjectMetadata({
         manifest,
         pulledAt,
         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. Missing/null refuses save unless --force
+        // (server also rejects unguarded saves onto non-empty projects).
+        filesHash: typeof filesHash === "string" ? filesHash : null,
       },
       null,
       2,
@@ -432,11 +631,14 @@ export async function writeReferenceMetadata({
           readOnly: true,
           forkable: true,
           sourceBuildId,
-          sourceAppUrl: sourceBuildId ? `${options.siteUrl}/app/${sourceBuildId}` : null,
+          sourceAppUrl: sourceBuildId
+            ? `${options.siteUrl}/app/${sourceBuildId}`
+            : null,
         },
         build: {
           id: sourceBuildId,
-          title: build?.title || (sourceBuildId ? `Build ${sourceBuildId}` : ""),
+          title:
+            build?.title || (sourceBuildId ? `Build ${sourceBuildId}` : ""),
           role: "reference",
           ownerUsername: build?.ownerUsername || null,
           collaborationMode: build?.collaborationMode || "open_source",

package/package.json

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