@hiveku-apps/sync 0.3.6 → 0.5.0

package/src/push.mjs

@@ -13,6 +13,13 @@
  *   pull-env  project_secrets_list → .env.local with the same _DEV/_PROD/
  *             _STAGING resolution the preview machine uses.
  *
+ * After a push whose files all landed, push saves them as ONE version of Your
+ * site (or of the branch it pushed to): project_vcs_commit with NO files and
+ * NO deletedFiles (versions.mjs versionAfterPush). --no-version skips it. Exit
+ * codes: 1 when files failed or the push was refused (no version, no deploy),
+ * 2 when every file IS saved but the version was not, 3 when the files (and
+ * the version) ARE saved and only the deploy failed.
+ *
  * Why not just project_commit (the old push)? project_commit is the GitHub
  * path (needs a connected repo) AND sends every file in one unbatched call.
  * bulk_save works on every project, batches for transport reliability, and —
@@ -35,6 +42,33 @@ import {
   writeProjectsManifest,
 } from './projects.mjs';
 import { writeFileAtomic, readEnv, loadDotenv } from './util.mjs';
+import {
+  branchLabel,
+  checkedVersionName,
+  chooseVersionName,
+  commitRetryCommand,
+  describeChosenName,
+  EXIT_DEPLOY_FAILED,
+  EXIT_FAILED,
+  EXIT_VERSION_FAILED,
+  normalizeBranch,
+  reportVersion,
+  resolvePushBranch,
+  saveVersion,
+  statusWithOwnChanges,
+  tryReadVersionStatus,
+  versionAfterPush,
+} from './versions.mjs';
+import { saveCodeFiles } from './saveFiles.mjs';
+import {
+  branchMovedSafeNote,
+  branchMovedSincePull,
+  deletablePaths,
+  deployTargetNote,
+  pathsAtRisk,
+  reportBranchMoved,
+  sharedAssetsNote,
+} from './pushGuards.mjs';
 
 const PROJECTS_DIR = 'projects';
 
@@ -158,7 +192,7 @@ async function remoteAssetMap(client, projectId) {
  * files, the code diff (one status call), the asset diff (assets_list), and a
  * summary plan.
  */
-export async function computePushPlan({ client, projectId, folder, includeDeletes = false, noAssets = false, assetsAll = false }) {
+export async function computePushPlan({ client, projectId, folder, includeDeletes = false, noAssets = false, assetsAll = false, branch = null }) {
   // 1. Read + lane-classify every local file.
   const rels = (await walkLocalFiles(folder)).map((abs) =>
     relative(folder, abs).split(sep).join('/'),
@@ -175,24 +209,24 @@ export async function computePushPlan({ client, projectId, folder, includeDelete
   //    computed against the whole manifest, so chunking produces phantom
   //    deletions — the exact gotcha the momentum session hit). Only CODE files
   //    are sent, so binary assets never show up as false only_local.
-  const diff = (
-    await client.callToolJson('project_files_status', {
-      project_id: projectId,
-      local: await localCodeManifest(codeAll),
-    })
-  ).data;
+  //    On a branch the diff is against the branch's working tree.
+  const statusArgs = { project_id: projectId, local: await localCodeManifest(codeAll) };
+  if (branch) statusArgs.target = `branch:${branch}`;
+  const diff = (await client.callToolJson('project_files_status', statusArgs)).data;
   const changedSet = new Set([
     ...(diff.changed || []).map((c) => c.path),
     ...(diff.only_local || []).map((c) => c.path),
   ]);
   const codeToSave = codeAll.filter((f) => changedSet.has(f.path));
   // only_remote = code-lane paths (builder_code_versions) missing locally —
-  // status never reports binary assets (those live in builder_project_assets),
-  // so every only_remote entry is a genuine code deletion. If a public/<subdir>/
-  // image DOES show up here, it's a stale code_versions duplicate (the VANISH
-  // cause) and deleting it is correct — project_file_delete only touches
-  // code_versions, never the CDN asset we just uploaded.
-  const codeToDelete = includeDeletes ? (diff.only_remote || []).map((c) => c.path) : [];
+  // status never reports binary assets (those live in builder_project_assets).
+  // If a public/<subdir>/ image DOES show up here, it's a stale code_versions
+  // duplicate (the VANISH cause) and deleting it is correct —
+  // project_file_delete only touches code_versions, never the CDN asset we
+  // just uploaded. Paths this folder never holds (dot files, build folders,
+  // files Hiveku manages) are not deletions (pushGuards.mjs).
+  const { deletable, notMirrored } = deletablePaths(diff.only_remote || []);
+  const codeToDelete = includeDeletes ? deletable : [];
 
   // 3. ASSET diff — asset-lane-aware, so unchanged images aren't re-sent.
   const assetToUpload = [];
@@ -221,7 +255,7 @@ export async function computePushPlan({ client, projectId, folder, includeDelete
     asset_unchanged: assetSkipped,
     asset_skipped_lane: noAssets ? assetAll.length : 0,
   };
-  return { codeAll, assetAll, diff, codeToSave, codeToDelete, assetToUpload, assetSkipped, plan };
+  return { codeAll, assetAll, diff, codeToSave, codeToDelete, remoteOnly: deletable, notMirrored, assetToUpload, assetSkipped, plan };
 }
 
 // Thin CLI wrapper: resolve the MCP client + project folder from cwd, then run
@@ -268,17 +302,40 @@ export async function pushProject({
   assetsAll = false,
   dryRun = false,
   branch,
+  noVersion = false,
+  force = false,
+  retryDelayMs,
 }) {
+  // These checks run before any tool call, so a refusal changes nothing.
+  // null = Your site (main).
+  const targetBranch = resolvePushBranch({ branch, info });
+  // A typed name is checked now: the builder keeps a hiveku-sync name as sent.
+  const typedName = noVersion ? undefined : checkedVersionName(commit);
+  const deployEnv = deploy ? checkedEnv(deploy) : null;
   const {
     codeAll,
     assetAll,
+    diff,
     codeToSave,
     codeToDelete,
     assetToUpload,
     assetSkipped,
     plan: basePlan,
-  } = await computePushPlan({ client, projectId, folder, includeDeletes, noAssets, assetsAll });
-  const plan = { project: resolvedSlug, ...basePlan };
+  } = await computePushPlan({ client, projectId, folder, includeDeletes, noAssets, assetsAll, branch: targetBranch });
+  const plan = { project: resolvedSlug, ...basePlan, branch: targetBranch || 'main' };
+  const changedPaths = new Set((diff?.changed || []).map((c) => c.path));
+  // What this push changes, for the version name when Hiveku cannot list what is waiting.
+  const ownChanges = (failedSet = new Set()) => ({
+    added: codeToSave.filter((f) => !changedPaths.has(f.path) && !failedSet.has(f.path)).map((f) => f.path),
+    modified: codeToSave.filter((f) => changedPaths.has(f.path) && !failedSet.has(f.path)).map((f) => f.path),
+    removed: codeToDelete,
+  });
+  // Someone saved on the branch since the pull: the files this push would
+  // overwrite or delete may hold their work.
+  const moved = branchMovedSincePull({ info, targetBranch, diff });
+  const atRisk = moved ? pathsAtRisk({ diff, codeToDelete }) : [];
+  const movedNote = moved && atRisk.length === 0 ? branchMovedSafeNote(targetBranch) : null;
+  const assetsNote = sharedAssetsNote(targetBranch, assetToUpload.length);
 
   if (dryRun) {
     console.log('[dry run] push plan:');
@@ -286,6 +343,24 @@ export async function pushProject({
     console.log(`  code delete:    ${plan.code_delete}${includeDeletes ? '' : ' (pass --include-deletes to apply)'}`);
     console.log(`  asset upload:   ${plan.asset_upload}`);
     console.log(`  asset skip:     ${plan.asset_unchanged} unchanged${noAssets ? `, ${assetAll.length} lane-skipped (--no-assets)` : ''}`);
+    console.log(`  saves to:       ${branchLabel(targetBranch)}`);
+    if (noVersion) {
+      console.log('  version:        none (--no-version)');
+    } else if (codeToSave.length === 0 && codeToDelete.length === 0 && !typedName) {
+      console.log('  version:        none (no project files change; images, fonts and videos are not part of versions)');
+    } else {
+      // A version holds everything waiting, not only this push: name it from both.
+      const status = typedName ? null : await tryReadVersionStatus({ client, projectId, branch: targetBranch });
+      const choice = chooseVersionName({ typedName, status: statusWithOwnChanges(status, ownChanges()), own: ownChanges() });
+      console.log(`  version:        ${describeChosenName(choice)} (after every file is saved)`);
+    }
+    if (assetsNote) console.log(`  ${assetsNote}`);
+    if (deployEnv) {
+      const note = deployTargetNote(targetBranch, deployEnv);
+      if (note) console.log(`  ${note}`);
+    }
+    if (atRisk.length) reportBranchMoved({ branch: targetBranch, slug: resolvedSlug, paths: atRisk, force, dryRun: true });
+    else if (movedNote) console.log(`  ${movedNote}`);
     if (codeToSave.length) {
       console.log('\n  files to save:');
       for (const f of codeToSave.slice(0, 30)) console.log(`    M  ${f.path}`);
@@ -296,63 +371,54 @@ export async function pushProject({
       for (const f of assetToUpload.slice(0, 20)) console.log(`    A  ${f.path}`);
       if (assetToUpload.length > 20) console.log(`    ... and ${assetToUpload.length - 20} more`);
     }
-    return { dryRun: true, plan };
+    return { dryRun: true, plan, ...(moved ? { branch_moved: moved, at_risk: atRisk } : {}) };
   }
 
-  if (codeToSave.length === 0 && codeToDelete.length === 0 && assetToUpload.length === 0) {
-    console.log('Nothing to push — local is in sync with the deploy source.');
-    if (deploy) return runDeployFor({ client, projectId, slug: resolvedSlug, environment: deploy, wait });
-    return { skipped: true, plan };
+  if (atRisk.length) {
+    reportBranchMoved({ branch: targetBranch, slug: resolvedSlug, paths: atRisk, force, dryRun: false });
+    if (!force) return { refused: 'branch_moved', plan, branch_moved: moved, at_risk: atRisk, exit_code: EXIT_FAILED };
+  } else if (movedNote) {
+    console.log(`  ${movedNote}`);
   }
+  const retryCommand = commitRetryCommand({ slug: resolvedSlug, branch: targetBranch, recordedBranch: info.branch, typedName });
 
-  const failedPaths = [];
-  let codeSaved = 0;
-
-  // ── Code lane: batched, per-batch-verified bulk_save ──────────────────────
-  const BATCH_FILES = 40;
-  const BATCH_BYTES = 4_000_000; // well under the server's 20MB cap; sized for MCP-transport reliability
-  let batch = [];
-  let batchBytes = 0;
-  let batchNo = 0;
-  const flush = async () => {
-    if (batch.length === 0) return;
-    batchNo += 1;
-    const files = batch.map((f) => ({ path: f.path, content: f.content, encoding: f.encoding }));
-    const label = batch;
-    batch = [];
-    batchBytes = 0;
-    for (let attempt = 1; attempt <= 2; attempt++) {
-      let r;
-      try {
-        r = (
-          await client.callToolJson('project_files_bulk_save', {
-            project_id: projectId,
-            files,
-            commit_message: commit || 'hiveku-sync: push local changes',
-          })
-        ).data;
-      } catch (e) {
-        if (attempt >= 2) failedPaths.push(...label.map((f) => f.path));
-        continue;
-      }
-      const succeeded = r?.summary?.succeeded ?? files.length;
-      codeSaved += succeeded;
-      if (succeeded === files.length) return;
-      const bad = (r?.results || []).filter((x) => x.ok === false).map((x) => x.path);
-      if (attempt >= 2) failedPaths.push(...(bad.length ? bad : label.map((f) => f.path)));
+  if (codeToSave.length === 0 && codeToDelete.length === 0 && assetToUpload.length === 0) {
+    console.log(`Nothing to push: this folder matches ${branchLabel(targetBranch)}.`);
+    // Nothing of this push to name; a typed name still saves what is waiting
+    // (e.g. after an earlier push whose version did not save).
+    let version = null;
+    if (typedName) {
+      version = await saveVersion({ client, projectId, branch: targetBranch, name: typedName, retryDelayMs });
+      reportVersion(version, { branch: targetBranch, filesSaved: false, retryCommand });
     }
-  };
-  for (const f of codeToSave) {
-    if (batch.length >= BATCH_FILES || (batchBytes > 0 && batchBytes + f.content.length > BATCH_BYTES)) {
-      await flush();
-      console.log(`  code ${codeSaved}/${codeToSave.length}`);
+    const exitCode = version?.outcome === 'failed' ? EXIT_VERSION_FAILED : 0;
+    if (deployEnv) {
+      const d = await deployAfterPush({ client, projectId, slug: resolvedSlug, environment: deployEnv, wait, branch: targetBranch });
+      return { ...d.result, skipped: true, plan, version, deploy: d.result, exit_code: d.failed && !exitCode ? EXIT_DEPLOY_FAILED : exitCode };
     }
-    batch.push(f);
-    batchBytes += f.content.length;
+    return { skipped: true, plan, version, exit_code: exitCode };
   }
-  await flush();
+
+  // Said before the first write, while --no-assets can still leave them out.
+  if (assetsNote) console.log(`  ${assetsNote}`);
+
+  // ── Code lane: batched bulk_save, each batch checked (saveFiles.mjs) ──────
+  const code = await saveCodeFiles({
+    client,
+    projectId,
+    files: codeToSave,
+    branch: targetBranch,
+    // A note on each file's row, never a version (the version is saved once, below).
+    note: commit || 'hiveku-sync: push local changes',
+    log: (line) => console.log(line),
+  });
+  const failedPaths = [...code.failed];
+  const codeSaved = code.saved;
+  // The branch tree this push leaves behind (every branch write answers it).
+  let branchEtag = code.workingTreeEtag;
 
   // ── Asset lane: assets_upload, bounded concurrency, retry once ────────────
+  // The asset store is project-wide: there is no per-branch copy.
   let assetDone = 0;
   await runLimited(assetToUpload, 5, async (f) => {
     for (let attempt = 1; attempt <= 2; attempt++) {
@@ -377,7 +443,13 @@ export async function pushProject({
   let deleted = 0;
   for (const p of codeToDelete) {
     try {
-      await client.callToolJson('project_file_delete', { project_id: projectId, file_path: p });
+      const answer = await client.callToolJson('project_file_delete', {
+        project_id: projectId,
+        file_path: p,
+        ...(targetBranch ? { branch: targetBranch } : {}),
+      });
+      const etag = answer?.working_tree_etag ?? answer?.data?.working_tree_etag;
+      if (typeof etag === 'string' && etag) branchEtag = etag;
       deleted += 1;
     } catch {
       failedPaths.push(p);
@@ -390,46 +462,106 @@ export async function pushProject({
       (deleted ? `, ${deleted} deletion${deleted !== 1 ? 's' : ''}` : '') +
       (assetSkipped ? ` (${assetSkipped} asset${assetSkipped !== 1 ? 's' : ''} unchanged)` : ''),
   );
+  const failedSet = new Set(failedPaths);
   if (failedPaths.length) {
-    console.log(`  ⚠ ${failedPaths.length} file(s) FAILED: ${failedPaths.slice(0, 10).join(', ')}${failedPaths.length > 10 ? '…' : ''}`);
+    console.log(
+      `  ${failedPaths.length} file${failedPaths.length !== 1 ? 's' : ''} did NOT save: ` +
+        `${failedPaths.slice(0, 10).join(', ')}${failedPaths.length > 10 ? '…' : ''}`,
+    );
+    console.log('  Every other file IS saved. Push again to retry the ones that failed.');
   }
 
-  // ── Optional: record a Hiveku-native main commit (version-history marker).
-  // Files are already saved via bulk_save; this snapshots the current state on
-  // `main` so `hiveku-sync` history shows the push. GitHub not required.
-  if (commit) {
-    try {
-      const c = (
-        await client.callToolJson('project_vcs_commit', {
-          project_id: projectId,
-          message: commit,
-          branch: branch || info.branch || undefined,
-          deletedFiles: codeToDelete.length ? codeToDelete : undefined,
-        })
-      ).data;
-      console.log(`  committed on ${c?.branch_name || branch || 'main'} (${c?.checkpoint_hash ? c.checkpoint_hash.slice(0, 12) : c?.id || 'recorded'})`);
-    } catch (e) {
-      console.log(`  ⚠ commit marker failed (files ARE saved): ${(e && e.message) || e}`);
-    }
+  // ── Version: ONE version for this push, only when every file landed ───────
+  // project_vcs_commit with NO files and NO deletedFiles: on Your site it
+  // saves everything not yet in a version (the deletions above are already
+  // applied, and re-sending them would delete again); on a branch it saves
+  // the branch's working tree. 409 nothing_to_commit is fine.
+  let version = null;
+  if (failedPaths.length) {
+    console.log('  Not saved as a version, because some files did not save.');
+  } else if (noVersion) {
+    console.log('  Not saved as a version (--no-version). `hiveku-sync commit` saves one when you are ready.');
+  } else if (codeSaved + deleted === 0 && !typedName) {
+    console.log('  Images, fonts and videos are not part of versions, so there was nothing to save as a version.');
+  } else {
+    // Named from everything waiting (other writers' changes too), not only this push.
+    version = await versionAfterPush({
+      client,
+      projectId,
+      branch: targetBranch,
+      typedName,
+      own: ownChanges(failedSet),
+      slug: resolvedSlug,
+      recordedBranch: info.branch,
+      retryDelayMs,
+    });
   }
 
-  // Update manifest timestamps.
+  // Update manifest timestamps, and on the folder's own branch the tree this
+  // push left (so the next push can tell whether someone saved since). A
+  // branch someone else saved on keeps the pull's etag until the folder is
+  // pulled again, unless --force said to overwrite their work.
   const manifest = await readProjectsManifest(baseDir);
   manifest.projects = manifest.projects || {};
+  const followsThisBranch = targetBranch && targetBranch === normalizeBranch(info.branch) && (!moved || force);
   manifest.projects[resolvedSlug] = {
     ...(manifest.projects[resolvedSlug] || { project_id: projectId }),
     last_push_at: new Date().toISOString(),
+    ...(version?.outcome === 'saved' && version.version?.id ? { last_version_id: version.version.id } : {}),
+    ...(followsThisBranch && branchEtag ? { working_tree_etag: branchEtag } : {}),
   };
   await writeProjectsManifest(baseDir, manifest);
 
-  const result = { plan, code_saved: codeSaved, assets_uploaded: assetDone, deleted, failed: failedPaths };
-  if (deploy) {
-    const d = await runDeployFor({ client, projectId, slug: resolvedSlug, environment: deploy, wait });
-    result.deploy = d;
+  const exitCode = failedPaths.length ? EXIT_FAILED : version?.outcome === 'failed' ? EXIT_VERSION_FAILED : 0;
+  const result = {
+    plan,
+    code_saved: codeSaved,
+    assets_uploaded: assetDone,
+    deleted,
+    failed: failedPaths,
+    version,
+    exit_code: exitCode,
+  };
+  if (deployEnv) {
+    if (failedPaths.length) {
+      console.log(`Not deploying to ${deployEnv}: publish only after every file has saved.`);
+    } else {
+      // The version (if any) is saved first, so the deploy ships a version.
+      const d = await deployAfterPush({ client, projectId, slug: resolvedSlug, environment: deployEnv, wait, branch: targetBranch });
+      result.deploy = d.result;
+      // A version that did not save (2) says more than a deploy that did not finish.
+      if (d.failed && !result.exit_code) result.exit_code = EXIT_DEPLOY_FAILED;
+    }
   }
   return result;
 }
 
+/** A --deploy tier, checked before anything is written (a typo must not wait until after the push). */
+function checkedEnv(environment) {
+  const env = normalizeEnv(environment);
+  if (!['development', 'staging', 'production'].includes(env)) {
+    throw new Error(`Invalid environment "${environment}": use development | staging | production. Nothing was changed.`);
+  }
+  return env;
+}
+
+/**
+ * The deploy at the end of a push. A failed deploy is not a failed push: the
+ * files (and the version) ARE saved, so it says so and exits 3, never 1
+ * (which means files did not save).
+ */
+async function deployAfterPush({ client, projectId, slug, environment, wait, branch }) {
+  const note = deployTargetNote(branch, environment);
+  if (note) console.log(`  ${note}`);
+  try {
+    return { result: await runDeployFor({ client, projectId, slug, environment, wait }), failed: false };
+  } catch (err) {
+    console.log(`  The deploy to ${environment} did not finish: ${err.message}.`);
+    console.log(`  Your files ARE saved on Hiveku (and the version, if one was saved). Deploy again with: hiveku-sync deploy ${environment} ${slug}${wait ? ' --wait' : ''}`);
+    return { result: { environment, ok: false, error: err.message, ...(err.deploy || {}) }, failed: true };
+  }
+}
+
 // ── Deploy ──────────────────────────────────────────────────────────────────
 
 const DEPLOY_SUCCESS = new Set(['completed', 'ready', 'succeeded', 'success', 'deployed', 'live']);
@@ -456,13 +588,17 @@ async function runDeployFor({ client, projectId, slug, environment, wait }) {
   const startUrl = started?.url || started?.preview_url;
   console.log(`  deployment_id: ${deploymentId || '(none returned)'}`);
   if (startUrl) console.log(`  url: ${startUrl}`);
+  // Which version this deploy ships, in the server's own plain words (a
+  // deploy of Your site saves waiting changes as a version first).
+  if (typeof started?.note === 'string' && started.note.trim()) console.log(`  ${started.note.trim()}`);
+  const shipped = started?.vcs_commit_id ? { version_id: started.vcs_commit_id } : {};
 
   if (!wait) {
     console.log('  (not waiting — pass --wait to poll to completion)');
-    return { deployment_id: deploymentId, environment: env, url: startUrl, waited: false };
+    return { deployment_id: deploymentId, environment: env, url: startUrl, waited: false, ...shipped };
   }
   if (!deploymentId) {
-    console.log('  ⚠ no deployment_id to poll — check deploy_status manually.');
+    console.log('  No deployment id came back to follow: check it with `deploy_status`.');
     return { environment: env, waited: false };
   }
 
@@ -486,11 +622,11 @@ async function runDeployFor({ client, projectId, slug, environment, wait }) {
     }
     if (DEPLOY_SUCCESS.has(status)) {
       const url = dep?.url || dep?.preview_url || startUrl;
-      console.log(`  ✓ deployed: ${url || '(url pending)'}`);
-      return { deployment_id: deploymentId, environment: env, status, url, waited: true, ok: true };
+      console.log(`  Deployed: ${url || '(address not ready yet)'}`);
+      return { deployment_id: deploymentId, environment: env, status, url, waited: true, ok: true, ...shipped };
     }
     if (DEPLOY_FAILURE.has(status)) {
-      console.log(`  ✗ deploy ${status}${dep?.error ? `: ${dep.error}` : ''}`);
+      console.log(`  Deploy ${status}${dep?.error ? `: ${dep.error}` : ''}`);
       if (dep?.build_logs) {
         const tail = String(dep.build_logs).split('\n').slice(-15).join('\n');
         console.log('  --- build log (tail) ---\n' + tail);
@@ -500,7 +636,7 @@ async function runDeployFor({ client, projectId, slug, environment, wait }) {
       throw err;
     }
   }
-  console.log(`  ⚠ still ${last || 'pending'} after ${Math.round(MAX_MS / 60000)}min — check deploy_status.`);
+  console.log(`  Still ${last || 'pending'} after ${Math.round(MAX_MS / 60000)} min: check it with \`deploy_status\`.`);
   return { deployment_id: deploymentId, environment: env, status: last, waited: true, ok: false };
 }
 

package/src/pushGuards.mjs

@@ -0,0 +1,100 @@
+/**
+ * Checks a push makes before it writes anything, and the notes it prints
+ * where a person can still act on them.
+ *
+ *   - deletablePaths: `--include-deletes` deletes only files this folder
+ *     could hold. The local walk never lists dot files (.gitignore,
+ *     .eslintrc.json, .ai/memory.md), build and tool folders, or the pulled
+ *     account memory, and a pull does not bring down the files Hiveku manages
+ *     itself (soul.md, connected_tools.md, data/marketing/...). Those always
+ *     read as "only on Hiveku", which is not a deletion.
+ *   - branchMovedSincePull: on a branch, the working_tree_etag recorded at
+ *     pull time against the one project_files_status reports now. When they
+ *     differ, someone saved on the branch since the pull, and a push would
+ *     overwrite their files with this folder's older copies.
+ *   - sharedAssetsNote / deployTargetNote: images, fonts and videos are one
+ *     store shared by Your site and every branch, and deploy_site publishes
+ *     what a tier is set to publish (Your site unless the tier is bound to a
+ *     branch), not the branch just pushed.
+ */
+
+import { localWalkCanList } from './projects.mjs';
+import { branchLabel, normalizeBranch } from './versions.mjs';
+import { isServerManagedFile } from './versionName.mjs';
+
+/** Split only_remote paths into the ones a push may delete and the ones this folder never holds. */
+export function deletablePaths(onlyRemote = []) {
+  const deletable = [];
+  const notMirrored = [];
+  for (const entry of onlyRemote) {
+    const path = typeof entry === 'string' ? entry : entry?.path;
+    if (typeof path !== 'string' || !path) continue;
+    if (localWalkCanList(path) && !isServerManagedFile(path.replace(/^\/+/, ''))) deletable.push(path);
+    else notMirrored.push(path);
+  }
+  return { deletable, notMirrored };
+}
+
+/**
+ * Null when the branch is where the pull left it (or it cannot be told);
+ * else { recorded, current }. Only for a push to the branch the folder was
+ * pulled from: another branch's etag says nothing about this one.
+ */
+export function branchMovedSincePull({ info = {}, targetBranch, diff }) {
+  if (!targetBranch || normalizeBranch(info.branch) !== targetBranch) return null;
+  const recorded = typeof info.working_tree_etag === 'string' && info.working_tree_etag ? info.working_tree_etag : null;
+  const current = typeof diff?.basis?.working_tree_etag === 'string' && diff.basis.working_tree_etag ? diff.basis.working_tree_etag : null;
+  if (!recorded || !current || recorded === current) return null;
+  return { recorded, current };
+}
+
+/** The files a push would overwrite or delete on a branch someone else saved on. */
+export function pathsAtRisk({ diff, codeToDelete = [] }) {
+  return [...(diff?.changed || []).map((c) => c.path), ...codeToDelete];
+}
+
+/** Print why a push to a moved branch is refused (or, with --force, goes ahead). */
+export function reportBranchMoved({ branch, slug, paths, force, dryRun }) {
+  const shown = paths.slice(0, 15);
+  console.log(
+    `Someone saved on ${branchLabel(branch)} since this folder was pulled, so these files may hold their work` +
+      (paths.length ? ':' : '.'),
+  );
+  for (const path of shown) console.log(`    ${path}`);
+  if (paths.length > shown.length) console.log(`    ... and ${paths.length - shown.length} more`);
+  if (force) {
+    console.log(`  --force: ${dryRun ? 'the push would overwrite' : 'overwriting'} them with this folder's copies.`);
+    return;
+  }
+  console.log(
+    `${dryRun ? 'A push would be refused' : 'Nothing was changed'}. To keep their work, copy your edits somewhere safe, pull again ` +
+      `(hiveku-sync pull-project ${slug} --branch ${branch}; it replaces this folder's copies), then make your edits again ` +
+      "and push. To overwrite their work with this folder's copies, push with --force.",
+  );
+}
+
+/** Said when the branch moved but this push changes none of the files that differ from it. */
+export function branchMovedSafeNote(branch) {
+  return (
+    `Note: someone saved on ${branchLabel(branch)} since this folder was pulled. This push changes none of the files ` +
+    'that differ from it; pull again to get their work.'
+  );
+}
+
+/** Said before anything is written (and in a dry run) when a branch push uploads images, fonts or videos. */
+export function sharedAssetsNote(branch, count) {
+  if (!branch || !count) return null;
+  return (
+    `Note: images, fonts and videos are shared by Your site and every branch, so the ${count} this push uploads ` +
+    `change them everywhere, not only on ${branchLabel(branch)}. Pass --no-assets to leave them out.`
+  );
+}
+
+/** Said when a branch push also deploys: the tier publishes what it is set to publish. */
+export function deployTargetNote(branch, environment) {
+  if (!branch) return null;
+  return (
+    `Note: deploying to ${environment} publishes what ${environment} is set to publish: Your site, unless ` +
+    `${environment} is bound to ${branchLabel(branch)}. It does not publish the branch just because this push went to it.`
+  );
+}