@hiveku-apps/sync 0.3.6 → 0.4.0

package/src/versions.mjs

@@ -0,0 +1,811 @@
+/**
+ * Versions of a Hiveku site project, from the terminal.
+ *
+ * "Your site" (the branch named main) keeps versions: a save is live in the
+ * preview and is what a deploy ships, but it is not a version until
+ * project_vcs_commit runs with NO files, which saves everything not yet in a
+ * version as ONE version (a "promote"). A branch works the same way on its
+ * working tree. Rolling back is append-only: it writes a NEW version equal to
+ * an older one, so it can itself be undone, and it never publishes anything.
+ *
+ * This module holds:
+ *   - saveVersion: the promote every writer here uses (push, commit), with
+ *     source 'sync_cli' and never any files or deletedFiles (re-sending
+ *     deletions on main would delete again);
+ *   - chooseVersionName / versionAfterPush: the name of a version covers
+ *     everything waiting (project_vcs_status), never one run's own files, and
+ *     Hiveku names the first version over a legacy head itself;
+ *   - commitRetryCommand: the exact command that saves a version that failed;
+ *   - runVersionCommit: `hiveku-sync commit` (a promote, named by -m or from
+ *     what is waiting);
+ *   - runVersions: `hiveku-sync versions` (the history, newest first);
+ *   - runRollback: `hiveku-sync rollback <version>` (dry run unless --apply,
+ *     and --apply needs the id the dry run printed, --confirm).
+ *
+ * Builder contract (hiveku_builder feature/versions-core): POST vcs/commit,
+ * GET vcs/status, POST vcs/rollback, GET vcs/history, reached through the MCP
+ * tools project_vcs_commit, project_vcs_status, project_vcs_rollback and
+ * project_vcs_history. Anything a person reads here says "version" and calls
+ * main "Your site".
+ */
+
+import { sep } from 'node:path';
+
+import {
+  clientFromCwd,
+  findProjectFolder,
+  refuseExternal,
+  resolveProject,
+} from './projects.mjs';
+import { describeChanges, versionNameProblem } from './versionName.mjs';
+
+export const VERSION_SOURCE = 'sync_cli';
+/** Exit code when files ARE saved but the version was not. */
+export const EXIT_VERSION_FAILED = 2;
+/** Exit code when something the command set out to do failed. */
+export const EXIT_FAILED = 1;
+/** Exit code when a push's files (and version) ARE saved and only its deploy failed. */
+export const EXIT_DEPLOY_FAILED = 3;
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const EXAMPLE_NAME = 'Updated the pricing section on the Home page';
+
+// ── Small shared helpers ─────────────────────────────────────────────────────
+
+/** A branch name as the tools take it: null for Your site (main, blank, absent). */
+export function normalizeBranch(branch) {
+  if (typeof branch !== 'string') return null;
+  const trimmed = branch.trim();
+  return trimmed && trimmed !== 'main' ? trimmed : null;
+}
+
+/**
+ * The --branch flag as given: undefined when absent, else the branch (null for
+ * Your site). A bare --branch with no name is refused, never read as Your site.
+ */
+export function branchFlag(branch) {
+  if (branch === undefined || branch === null) return undefined;
+  if (typeof branch !== 'string' || !branch.trim()) {
+    throw new Error('Pass a branch name: --branch <name> (or --branch main for Your site).');
+  }
+  return normalizeBranch(branch);
+}
+
+/** How a person reads the branch: "Your site" or branch "x". */
+export function branchLabel(branch) {
+  return branch ? `branch "${branch}"` : 'Your site';
+}
+
+/**
+ * Read a failed MCP tool call. HivekuMcpClient.callTool throws
+ * `Tool <name> errored: <json>`, where the JSON is the proxy's envelope
+ * { error, status, details: <the route's body, with its code>, ... }, or
+ * { error: "Unknown tool: <name>" } from a server that lacks the tool.
+ */
+export function readToolError(err) {
+  const message = String((err && err.message) || err || '');
+  const at = message.indexOf('errored: ');
+  let envelope = null;
+  if (at !== -1) {
+    try {
+      envelope = JSON.parse(message.slice(at + 'errored: '.length));
+    } catch {
+      envelope = null;
+    }
+  }
+  const details = envelope && typeof envelope.details === 'object' && envelope.details ? envelope.details : {};
+  const status = typeof envelope?.status === 'number' ? envelope.status : null;
+  const text = String(details.error || envelope?.error || message);
+  let code = typeof details.code === 'string' ? details.code : typeof envelope?.code === 'string' ? envelope.code : null;
+  if (!code && /^Unknown tool:/.test(String(envelope?.error || ''))) code = 'unknown_tool';
+  if (!code && /not in this connection's tool profile/i.test(message)) code = 'unknown_tool';
+  // No route on this builder yet: Next answers its own HTML 404 page.
+  if (!code && status === 404 && /text\/html/i.test(String(envelope?.content_type || ''))) code = 'route_unavailable';
+  if (!code && status === 404 && /project not found/i.test(text)) code = 'project_missing';
+  if (!code && /did not respond within the tool timeout/i.test(text)) code = 'timeout';
+  return { status, code, text, details, raw: message };
+}
+
+function sleep(ms) {
+  return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+}
+
+/**
+ * The name typed with -m, checked. Undefined when none was typed. Throws when
+ * it is not a plain version name: the builder keeps a hiveku-sync name
+ * exactly as sent, so this is the only check it gets.
+ */
+export function checkedVersionName(name) {
+  if (name === undefined || name === null) return undefined;
+  const trimmed = String(name).trim();
+  const problem = versionNameProblem(trimmed);
+  if (problem) {
+    throw new Error(
+      `"${trimmed}" can't be used as a version name: ${problem}. ` +
+        'The site owner reads version names, so describe what changed for visitors in plain words, ' +
+        `for example "${EXAMPLE_NAME}". Nothing was changed.`,
+    );
+  }
+  return trimmed;
+}
+
+// ── Saving a version (the promote) ───────────────────────────────────────────
+
+/** Answers that go away on their own; the promote is tried once more. */
+const RETRY_CODES = new Set(['branch_busy', 'branch_changed', 'idempotency_pending', 'branch_tree_unavailable']);
+
+/** Why a version could not be saved, in words for a person. */
+function versionFailureReason(error, branch) {
+  switch (error.code) {
+    case 'unknown_tool':
+      return 'this Hiveku connection does not offer versions yet';
+    case 'route_unavailable':
+      return 'versions are not available on Hiveku yet (the platform is updating)';
+    case 'branch_busy':
+    case 'idempotency_pending':
+      return 'someone else was saving at the same moment';
+    case 'branch_changed':
+      return `${branchLabel(branch)} changed while the version was being saved`;
+    case 'branch_tree_unavailable':
+      return 'Hiveku could not read the files for a moment';
+    case 'branch_missing':
+      return `there is no ${branchLabel(branch)} on this project`;
+    case 'timeout':
+      return 'Hiveku did not answer in time (it may still have saved it: check with `hiveku-sync versions` before trying again)';
+    default:
+      break;
+  }
+  // A builder from before versions of Your site refuses a save with no files.
+  if (error.status === 400 && /at least one file|message is required/i.test(error.text)) {
+    return `this Hiveku server cannot save versions of ${branchLabel(branch)} yet (the platform is updating)`;
+  }
+  return `Hiveku answered: ${error.text}`;
+}
+
+/**
+ * The name a branch version gets when no name was given and the server is
+ * one that requires a name (production before versions of Your site names a
+ * branch version only when it is given one).
+ */
+export const BRANCH_FALLBACK_NAME = 'Saved the latest changes on this branch';
+
+/**
+ * Save everything on Hiveku that is not in a version yet as ONE version
+ * (project_vcs_commit with no files and no deletedFiles). Never throws for a
+ * refusal: returns
+ *   { outcome: 'saved', version, name }          a new version,
+ *   { outcome: 'nothing_new', latest_version }  every change already is one,
+ *   { outcome: 'failed', reason, error }        not saved (files untouched).
+ * `name` undefined lets the server name it from what changed.
+ */
+export async function saveVersion({ client, projectId, branch = null, name, retryDelayMs = 2000 }) {
+  const args = { project_id: projectId, source: VERSION_SOURCE };
+  if (name) args.message = name;
+  if (branch) args.branch = branch;
+  let lastError = null;
+  let namedForOldServer = false;
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    try {
+      const body = await client.callToolJson('project_vcs_commit', args);
+      const data = body && typeof body === 'object' ? body.data : null;
+      if (data === null && body?.clean === true) {
+        return { outcome: 'nothing_new', latest_version: body.latest_version ?? null };
+      }
+      if (!data || typeof data !== 'object') {
+        lastError = { code: null, status: null, text: 'the answer had no version in it', details: {} };
+        break;
+      }
+      return { outcome: 'saved', version: data, name: data.message || name || null };
+    } catch (err) {
+      const error = readToolError(err);
+      if (error.code === 'nothing_to_commit') {
+        return { outcome: 'nothing_new', latest_version: error.details.latest_version ?? null };
+      }
+      lastError = error;
+      // An older server names no branch version itself: give it a plain one, once.
+      if (branch && !args.message && !namedForOldServer && error.status === 400 && /message is required/i.test(error.text)) {
+        namedForOldServer = true;
+        args.message = BRANCH_FALLBACK_NAME;
+        attempt -= 1;
+        continue;
+      }
+      if (attempt < 2 && RETRY_CODES.has(error.code)) {
+        await sleep(retryDelayMs);
+        continue;
+      }
+      break;
+    }
+  }
+  return { outcome: 'failed', reason: versionFailureReason(lastError, branch), error: lastError };
+}
+
+/**
+ * Print what saveVersion did, for a person. `filesSaved` says whether this run
+ * saved files, so a failure says plainly that they ARE saved. `retryCommand`
+ * is the exact command that saves the version again (commitRetryCommand).
+ */
+export function reportVersion(result, { branch = null, filesSaved = false, retryCommand = 'hiveku-sync commit' } = {}) {
+  if (result.outcome === 'saved') {
+    const shown = result.name ? `"${result.name}"` : 'a new version';
+    console.log(`  Saved as a version of ${branchLabel(branch)}: ${shown}`);
+    const saved = result.version?.saved_before;
+    if (saved && saved.name) console.log(`  Changes that were waiting first were saved as their own version: "${saved.name}"`);
+    return;
+  }
+  if (result.outcome === 'nothing_new') {
+    const latest = result.latest_version?.message;
+    console.log(
+      `  Nothing new to save as a version: every change on ${branchLabel(branch)} is already in one` +
+        (latest ? ` (latest: "${latest}").` : '.'),
+    );
+    return;
+  }
+  const lead = filesSaved
+    ? 'Your files ARE saved on Hiveku, but they were not saved as a version'
+    : 'The version was not saved (your files on Hiveku are unchanged)';
+  console.log(`  ${lead}: ${result.reason}.`);
+  console.log(`  To try saving the version again, run: ${retryCommand}`);
+}
+
+/** One shell argument, always quoted (a version name). */
+export function quotedArg(text) {
+  const value = String(text);
+  if (!/["$`\\!]/.test(value)) return `"${value}"`;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/** One shell argument, quoted only when it needs to be (a slug, a branch). */
+export function shellArg(text) {
+  const value = String(text);
+  return /^[A-Za-z0-9._/:=@-]+$/.test(value) ? value : quotedArg(value);
+}
+
+/**
+ * The exact `hiveku-sync commit` that saves the version a push did not: the
+ * project by name (so it works from the account folder too), the branch the
+ * push wrote to (--branch main when the folder follows a branch but the push
+ * went to Your site), and the name typed with -m. A name the push made up is
+ * left out: commit names the version from everything that is waiting.
+ */
+export function commitRetryCommand({ slug, branch = null, recordedBranch = null, typedName } = {}) {
+  const parts = ['hiveku-sync commit'];
+  if (slug) parts.push(shellArg(slug));
+  if (branch) parts.push(`--branch ${shellArg(branch)}`);
+  else if (normalizeBranch(recordedBranch)) parts.push('--branch main');
+  if (typedName) parts.push(`-m ${quotedArg(typedName)}`);
+  return parts.join(' ');
+}
+
+/**
+ * Which branch a push writes to: --branch when given (main = Your site),
+ * else the branch the folder was pulled from. A folder pulled from a branch
+ * by hiveku-sync 0.3.x holds Your site's files (that version never read
+ * branches) and has no working_tree_etag recorded; pushing it to the branch
+ * would overwrite the branch's own work, so that needs --branch said out loud.
+ */
+export function resolvePushBranch({ branch, info = {} }) {
+  const flagged = branchFlag(branch);
+  if (flagged !== undefined) return flagged;
+  const recorded = normalizeBranch(info.branch);
+  if (recorded && !Object.prototype.hasOwnProperty.call(info, 'working_tree_etag')) {
+    throw new Error(
+      `This folder was pulled for branch "${recorded}" by an older hiveku-sync, which downloaded Your site's files ` +
+        `instead of the branch's. Pushing it to the branch could overwrite work saved there. Pull it again with ` +
+        `\`hiveku-sync pull-project <slug> --branch ${recorded}\`, or pass --branch ${recorded} to push anyway ` +
+        '(or --branch main for Your site). Nothing was changed.',
+    );
+  }
+  return recorded;
+}
+
+// ── Project resolution for commit / versions / rollback ──────────────────────
+
+function accountBaseDir(cwd = process.cwd()) {
+  const idx = cwd.indexOf(`${sep}projects${sep}`);
+  return idx > -1 ? cwd.slice(0, idx) : cwd;
+}
+
+/**
+ * The project a command acts on: the pulled folder (by slug, or the one cwd
+ * is in) first, else a slug or id resolved on the account. External sites
+ * are refused.
+ */
+async function resolveTarget({ slugOrId, client, baseDir }) {
+  let found = null;
+  try {
+    found = await findProjectFolder({ slug: slugOrId, baseDir });
+  } catch {
+    found = null;
+  }
+  if (found) {
+    refuseExternal(found.info);
+    return { projectId: found.info.project_id, slug: found.slug, info: found.info };
+  }
+  if (!slugOrId) {
+    throw new Error('No project folder detected: cd into ./projects/<slug>/ or pass a project slug or id.');
+  }
+  const project = await resolveProject(client, slugOrId);
+  refuseExternal(project);
+  return { projectId: project.id, slug: project.slug || project.name || project.id, info: { project_type: project.project_type } };
+}
+
+async function clientAndBase({ client, profile, baseDir }) {
+  const base = baseDir || accountBaseDir();
+  if (client) return { client, baseDir: base };
+  const resolved = await clientFromCwd({ profileOverride: profile });
+  return { client: resolved.client, baseDir: base };
+}
+
+/** project_vcs_status, or null when this server or connection cannot answer it. */
+export async function readVersionStatus({ client, projectId, branch = null, detail = true }) {
+  const args = { project_id: projectId };
+  if (branch) args.branch = branch;
+  if (detail) args.detail = 'files';
+  try {
+    const body = await client.callToolJson('project_vcs_status', args);
+    return body?.data && typeof body.data === 'object' ? body.data : null;
+  } catch (err) {
+    const error = readToolError(err);
+    if (error.code === 'branch_missing') throw new Error(`There is no ${branchLabel(branch)} on this project.`);
+    return null;
+  }
+}
+
+/** A name for what is waiting, from status' changed_files; undefined when unknown. */
+export function nameFromStatus(status) {
+  const files = Array.isArray(status?.changed_files) ? status.changed_files : null;
+  if (!files || files.length === 0) return undefined;
+  const lists = { added: [], modified: [], removed: [] };
+  for (const entry of files) {
+    if (!entry || typeof entry.path !== 'string') continue;
+    if (entry.status === 'added') lists.added.push(entry.path);
+    else if (entry.status === 'removed') lists.removed.push(entry.path);
+    else lists.modified.push(entry.path);
+  }
+  const name = describeChanges(lists);
+  return name === 'No changes' ? undefined : name;
+}
+
+/**
+ * Why status cannot name what is waiting, so Hiveku names the version:
+ *   legacy_head    Your site's last version predates versions; the first one
+ *                  after it holds the whole site and is named "Your site up to
+ *                  <date>" by the server, never after one page;
+ *   no_version_yet Your site has no version at all (the same honest name);
+ *   unknown        Hiveku could not measure what is waiting.
+ */
+const SERVER_NAMES_IT = new Set(['legacy_head', 'no_version_yet', 'unknown']);
+
+/**
+ * The name to send when saving what is waiting as a version. A version saves
+ * EVERYTHING waiting on Your site (or the branch), from every writer: the
+ * Hiveku AI, the editor, other tools. So a name comes from the whole list
+ * project_vcs_status reports (read after this run's files landed), never from
+ * one run's own files. `status` null means this server cannot report it (an
+ * older one): then `own` ({ added, modified, removed }), the files this run
+ * changed, names it. Returns { name, basis: 'typed'|'waiting'|'own'|'server' };
+ * name undefined lets Hiveku name it.
+ */
+export function chooseVersionName({ typedName, status = null, own = null } = {}) {
+  if (typedName) return { name: typedName, basis: 'typed' };
+  if (!status) {
+    const name = own ? describeChanges(own) : undefined;
+    return name && name !== 'No changes' ? { name, basis: 'own' } : { name: undefined, basis: 'server' };
+  }
+  if (SERVER_NAMES_IT.has(status.uncommitted_reason)) return { name: undefined, basis: 'server' };
+  const name = nameFromStatus(status);
+  return name ? { name, basis: 'waiting' } : { name: undefined, basis: 'server' };
+}
+
+/**
+ * Status as it will read after this run's own changes land (for a dry run):
+ * its changed_files plus the run's own, the run's own status winning. A list
+ * Hiveku could not report (null) stays unknown.
+ */
+export function statusWithOwnChanges(status, own = {}) {
+  if (!status || !Array.isArray(status.changed_files)) return status;
+  const byPath = new Map(status.changed_files.filter((f) => f && typeof f.path === 'string').map((f) => [f.path, f.status]));
+  for (const path of own.added || []) byPath.set(path, byPath.get(path) === 'removed' ? 'modified' : 'added');
+  for (const path of own.modified || []) byPath.set(path, byPath.get(path) === 'added' ? 'added' : 'modified');
+  for (const path of own.removed || []) byPath.set(path, 'removed');
+  const changedFiles = [...byPath].map(([path, fileStatus]) => ({ path, status: fileStatus }));
+  const reason = status.uncommitted_reason || (changedFiles.length ? 'changed' : null);
+  return { ...status, uncommitted_reason: reason, changed_files: changedFiles };
+}
+
+/** project_vcs_status that never throws (null when it cannot be read). */
+export async function tryReadVersionStatus(args) {
+  try {
+    return await readVersionStatus(args);
+  } catch {
+    return null;
+  }
+}
+
+/** What a person reads about the name a version will get. */
+export function describeChosenName(choice) {
+  if (choice.name) return `"${choice.name}"`;
+  return 'named by Hiveku from everything it holds';
+}
+
+/**
+ * Save the version a push ends with, after every file landed: read what is
+ * waiting (so the name covers other writers' changes too), save, and report
+ * with the exact retry command. `own` is what this push changed.
+ */
+export async function versionAfterPush({ client, projectId, branch = null, typedName, own, slug, recordedBranch, retryDelayMs }) {
+  const status = typedName ? null : await tryReadVersionStatus({ client, projectId, branch });
+  const choice = chooseVersionName({ typedName, status, own });
+  const result = await saveVersion({ client, projectId, branch, name: choice.name, retryDelayMs });
+  reportVersion(result, {
+    branch,
+    filesSaved: true,
+    retryCommand: commitRetryCommand({ slug, branch, recordedBranch, typedName }),
+  });
+  return result;
+}
+
+// ── hiveku-sync commit ───────────────────────────────────────────────────────
+
+/**
+ * `hiveku-sync commit [<slug>] [-m "name"] [--branch <name>] [--dry-run]`:
+ * save what is on Hiveku and not in a version yet as one version. It sends no
+ * files: local edits that were not pushed are not in it.
+ */
+export async function runVersionCommit({ slug, name, branch, profile, dryRun = false, client: injectedClient, baseDir: baseDirOverride } = {}) {
+  const typedName = checkedVersionName(name);
+  const flagged = branchFlag(branch);
+  const { client, baseDir } = await clientAndBase({ client: injectedClient, profile, baseDir: baseDirOverride });
+  const target = await resolveTarget({ slugOrId: slug, client, baseDir });
+  const targetBranch = flagged !== undefined ? flagged : normalizeBranch(target.info.branch);
+
+  let status = null;
+  if (!typedName || dryRun) {
+    status = await readVersionStatus({ client, projectId: target.projectId, branch: targetBranch });
+  }
+  const versionName = chooseVersionName({ typedName, status }).name;
+
+  if (dryRun) {
+    console.log(`[dry run] ${branchLabel(targetBranch)} (${target.slug}):`);
+    if (status && status.uncommitted === false && status.uncommitted_reason !== 'unknown') {
+      console.log('  Nothing is waiting: every change is already in a version.');
+    } else if (status) {
+      const files = status.latest_changes?.files;
+      console.log(`  Waiting to be saved as a version${typeof files === 'number' ? `: ${files} file${files === 1 ? '' : 's'}` : ''}.`);
+    } else {
+      console.log('  Hiveku could not say what is waiting (this server does not report it yet).');
+    }
+    console.log(`  Name: ${versionName ? `"${versionName}"` : 'chosen by Hiveku from what changed'}`);
+    return { dryRun: true, name: versionName ?? null, status, exit_code: 0 };
+  }
+
+  const result = await saveVersion({ client, projectId: target.projectId, branch: targetBranch, name: versionName });
+  console.log(`${target.slug}:`);
+  reportVersion(result, {
+    branch: targetBranch,
+    filesSaved: false,
+    retryCommand: commitRetryCommand({ slug: target.slug, branch: targetBranch, recordedBranch: target.info.branch, typedName }),
+  });
+  if (result.outcome !== 'failed') {
+    console.log('  Only what is already on Hiveku is included: run `hiveku-sync push` first to send local edits.');
+  }
+  return { ...result, exit_code: result.outcome === 'failed' ? EXIT_VERSION_FAILED : 0 };
+}
+
+// ── hiveku-sync versions ─────────────────────────────────────────────────────
+
+const SOURCE_LABEL = {
+  ai_turn: 'Hiveku AI',
+  editor_idle: 'saved automatically',
+  deploy: 'saved when published',
+  mcp: 'AI assistant or API key',
+  vscode: 'VS Code',
+  sync_cli: 'hiveku-sync',
+  rollback: 'rollback',
+  merge: 'branch merged in',
+  manual: 'dashboard',
+  github: 'GitHub',
+};
+
+function formatWhen(iso) {
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return String(iso || '');
+  return date.toISOString().slice(0, 16).replace('T', ' ');
+}
+
+/** Every entry of project_vcs_history up to `limit`: one branch (Your site when null), or with allBranches every branch. */
+async function readHistory({ client, projectId, branch, limit, allBranches = false }) {
+  const args = { project_id: projectId, limit };
+  if (!allBranches) args.branch = branch || 'main';
+  const body = await client.callToolJson('project_vcs_history', args);
+  return Array.isArray(body?.data) ? body.data : [];
+}
+
+/**
+ * `hiveku-sync versions [<slug>] [--branch <name>] [--limit N] [--json]`:
+ * the versions of Your site (or a branch), newest first, and what is waiting.
+ */
+export async function runVersions({ slug, branch, limit = 20, json = false, profile, client: injectedClient, baseDir: baseDirOverride } = {}) {
+  const flagged = branchFlag(branch);
+  const { client, baseDir } = await clientAndBase({ client: injectedClient, profile, baseDir: baseDirOverride });
+  const target = await resolveTarget({ slugOrId: slug, client, baseDir });
+  const targetBranch = flagged !== undefined ? flagged : normalizeBranch(target.info.branch);
+  const count = Math.min(500, Math.max(1, Number.parseInt(limit, 10) || 20));
+
+  const [status, entries] = await Promise.all([
+    readVersionStatus({ client, projectId: target.projectId, branch: targetBranch }),
+    readHistory({ client, projectId: target.projectId, branch: targetBranch, limit: count }),
+  ]);
+
+  if (json) {
+    console.log(JSON.stringify({ project_id: target.projectId, branch: targetBranch || 'main', status, versions: entries }, null, 2));
+    return { status, versions: entries, exit_code: 0 };
+  }
+
+  console.log(`Versions of ${branchLabel(targetBranch)} (${target.slug}), newest first:`);
+  if (status && status.uncommitted === true) {
+    const files = status.latest_changes?.files;
+    const summary = nameFromStatus(status) || status.latest_changes?.summary;
+    console.log(
+      `  Not saved as a version yet${typeof files === 'number' ? `: ${files} file${files === 1 ? '' : 's'}` : ''}` +
+        (summary ? ` (${summary})` : '') +
+        '. `hiveku-sync commit` saves them.',
+    );
+  }
+  if (entries.length === 0) {
+    console.log('  No versions yet.');
+    return { status, versions: entries, exit_code: 0 };
+  }
+  for (const entry of entries) {
+    const who = entry.actor?.label || SOURCE_LABEL[entry.source] || '';
+    const how = entry.source && SOURCE_LABEL[entry.source] && SOURCE_LABEL[entry.source] !== who ? SOURCE_LABEL[entry.source] : '';
+    const by = [who, how].filter(Boolean).join(', ');
+    const live = Array.isArray(entry.live_on) && entry.live_on.length ? `  [live on ${entry.live_on.join(', ')}]` : '';
+    console.log(`  ${formatWhen(entry.created_at)}  ${entry.message || '(no name)'}${by ? `  (${by})` : ''}${live}`);
+    console.log(`      id ${entry.id}`);
+  }
+  console.log('\nTo go back to one: hiveku-sync rollback <id>   (shows what would change; nothing changes until you --apply)');
+  return { status, versions: entries, exit_code: 0 };
+}
+
+// ── hiveku-sync rollback ─────────────────────────────────────────────────────
+
+/** A full version id from a full id or an unambiguous prefix (8+ characters) found in the history. */
+async function resolveVersionId({ client, projectId, branch, versionId }) {
+  const wanted = String(versionId || '').trim().toLowerCase();
+  if (UUID_RE.test(wanted)) return wanted;
+  if (wanted.length < 8 || !/^[0-9a-f-]+$/.test(wanted)) {
+    throw new Error('Give the version id from `hiveku-sync versions` (the whole id, or at least its first 8 characters).');
+  }
+  const matching = (entries) => entries.filter((entry) => String(entry.id || '').toLowerCase().startsWith(wanted));
+  let matches = matching(await readHistory({ client, projectId, branch, limit: 500 }));
+  // A rollback target can also be a version saved on another branch (one
+  // merged in, or the one this branch started from): look at every branch.
+  if (matches.length === 0) matches = matching(await readHistory({ client, projectId, branch: null, allBranches: true, limit: 500 }));
+  if (matches.length === 1) return matches[0].id;
+  if (matches.length === 0) {
+    throw new Error(`No version starting with ${wanted} in the last 500 versions. Give the whole id from \`hiveku-sync versions\`.`);
+  }
+  throw new Error(`More than one version starts with ${wanted}: give more of the id.`);
+}
+
+/**
+ * The dry-run command for a version, as a person would type it again. It
+ * says --branch main when the folder follows a branch but the rollback is of
+ * Your site, or the command would act on the folder's branch.
+ */
+function dryRunCommand({ versionId, slug, branch, recordedBranch }) {
+  const parts = ['hiveku-sync rollback', versionId];
+  if (slug) parts.push(shellArg(slug));
+  if (branch) parts.push(`--branch ${shellArg(branch)}`);
+  else if (normalizeBranch(recordedBranch)) parts.push('--branch main');
+  return parts.join(' ');
+}
+
+/**
+ * 409 rollback_incomplete: files WERE written, so never "nothing was
+ * changed", and never "run the same command": when changes that were waiting
+ * were saved first, or the rollback was not recorded, the site's version
+ * moved and the old --confirm id is refused.
+ */
+function rollbackIncompleteText(error, { branch, versionId, slug, recordedBranch }) {
+  const details = error.details || {};
+  const applied = Array.isArray(details.applied) ? details.applied.length : 0;
+  const failed = Array.isArray(details.failed) ? details.failed : [];
+  const lines = [];
+  if (failed.length === 0) {
+    lines.push(
+      `Every file is back as it was in that version${applied ? ` (${applied} file${applied === 1 ? '' : 's'})` : ''}, ` +
+        'but the rollback was not saved as a new version. Nothing was lost.',
+    );
+  } else {
+    const total = applied + failed.length;
+    const shown = failed.slice(0, 5).join(', ') + (failed.length > 5 ? ` and ${failed.length - 5} more` : '');
+    lines.push(
+      `The rollback did not finish: ${failed.length} of ${total} file${total === 1 ? '' : 's'} could not be put back (${shown}). ` +
+        `Some files WERE changed: ${applied} ${applied === 1 ? 'is' : 'are'} already back as ${applied === 1 ? 'it was' : 'they were'}.`,
+    );
+  }
+  if (details.saved_before && details.saved_before.name) {
+    lines.push(`Changes that were waiting were first saved as their own version: "${details.saved_before.name}".`);
+  }
+  const again = dryRunCommand({ versionId, slug, branch, recordedBranch });
+  if (failed.length === 0) {
+    lines.push(
+      `To save it as a version, run the dry run again (${again}), then the --apply command it prints; if it says there is ` +
+        `nothing to roll back, save it with \`${commitRetryCommand({ slug, branch, recordedBranch })}\` instead.`,
+    );
+  } else {
+    lines.push(`To finish, run the dry run again: ${again}, then the --apply command it prints.`);
+  }
+  return lines.join('\n');
+}
+
+function rollbackFailure(error, { branch, versionId, slug, recordedBranch }) {
+  switch (error.code) {
+    case 'branch_changed':
+      return `Someone changed ${branchLabel(branch)} since the dry run. Nothing was changed. Run the dry run again: ${dryRunCommand({ versionId, slug, branch, recordedBranch })}`;
+    case 'ai_turn_running':
+      return 'The Hiveku AI is working on this site right now. Nothing was changed. Try again when it has finished.';
+    case 'rollback_incomplete':
+      return rollbackIncompleteText(error, { branch, versionId, slug, recordedBranch });
+    case 'content_unavailable':
+      return "That version's files can no longer be read. Nothing was changed. It may still be restorable from Project history in the dashboard.";
+    case 'not_in_history':
+      return `That version is not part of the history of ${branchLabel(branch)}. Nothing was changed.`;
+    case 'commit_not_found':
+      return 'There is no version with that id on this project. Nothing was changed.';
+    case 'expected_head_required':
+      return 'Hiveku needs the id the dry run printed (--confirm). Nothing was changed.';
+    case 'stash_branch_readonly':
+      return 'That branch holds set-aside changes and cannot be rolled back. Nothing was changed.';
+    case 'branch_busy':
+      return 'Someone else is saving at this moment. Nothing was changed. Try again shortly.';
+    case 'branch_missing':
+      return `There is no ${branchLabel(branch)} on this project. Nothing was changed.`;
+    case 'content_too_large':
+      return 'This site is too large to roll back in one step here. Nothing was changed.';
+    case 'unknown_tool':
+    case 'route_unavailable':
+      return 'Rolling back is not available on this Hiveku connection yet (the platform is updating). Nothing was changed.';
+    case 'timeout':
+      return 'Hiveku did not answer in time. It may still be working: check `hiveku-sync versions` before trying again.';
+    default:
+      return `Hiveku could not roll back: ${error.text}`;
+  }
+}
+
+function countLine(files = {}) {
+  const parts = [];
+  if (files.changed) parts.push(`${files.changed} file${files.changed === 1 ? '' : 's'} go back to how they were`);
+  if (files.removed) parts.push(`${files.removed} added since then ${files.removed === 1 ? 'is' : 'are'} removed`);
+  if (files.added_back) parts.push(`${files.added_back} removed since then ${files.added_back === 1 ? 'comes' : 'come'} back`);
+  return parts.length ? parts.join(', ') : 'no files change';
+}
+
+function applyCommand({ versionId, slug, branch, recordedBranch, head, fingerprint, name }) {
+  const parts = [dryRunCommand({ versionId, slug, branch, recordedBranch })];
+  parts.push('--apply', `--confirm ${head}`);
+  if (fingerprint) parts.push(`--fingerprint ${fingerprint}`);
+  if (name) parts.push(`-m ${quotedArg(name)}`);
+  return parts.join(' ');
+}
+
+/**
+ * `hiveku-sync rollback <version> [<slug>] [--branch <name>]` shows what going
+ * back to that version would change (a dry run; nothing changes).
+ * `... --apply --confirm <id> [--fingerprint <fp>]` applies it, only while
+ * Your site (or the branch) is still where the dry run saw it. It never
+ * publishes: `hiveku-sync deploy` is a separate step.
+ */
+export async function runRollback({
+  versionId,
+  slug,
+  branch,
+  apply = false,
+  head,
+  fingerprint,
+  name,
+  profile,
+  client: injectedClient,
+  baseDir: baseDirOverride,
+} = {}) {
+  if (!versionId) throw new Error('Usage: hiveku-sync rollback <version id> [<slug>] (see `hiveku-sync versions`)');
+  const typedName = checkedVersionName(name);
+  const flagged = branchFlag(branch);
+  if (apply && (typeof head !== 'string' || !UUID_RE.test(head.trim()))) {
+    throw new Error(
+      'Rolling back needs the dry run first. Run `hiveku-sync rollback <version id>` without --apply, check what it will ' +
+        'change, then run the --apply command it prints (it carries --confirm <id>). Nothing was changed.',
+    );
+  }
+  const { client, baseDir } = await clientAndBase({ client: injectedClient, profile, baseDir: baseDirOverride });
+  const target = await resolveTarget({ slugOrId: slug, client, baseDir });
+  const targetBranch = flagged !== undefined ? flagged : normalizeBranch(target.info.branch);
+  const fullId = await resolveVersionId({ client, projectId: target.projectId, branch: targetBranch, versionId });
+
+  const args = { project_id: target.projectId, commit_id: fullId, dry_run: !apply };
+  if (targetBranch) args.branch = targetBranch;
+  if (apply) {
+    args.expected_head_commit_id = head.trim().toLowerCase();
+    if (typeof fingerprint === 'string' && fingerprint.trim()) args.expected_live_fingerprint = fingerprint.trim().toLowerCase();
+    if (typedName) args.message = typedName;
+  }
+
+  let data;
+  try {
+    data = (await client.callToolJson('project_vcs_rollback', args))?.data;
+  } catch (err) {
+    const error = readToolError(err);
+    console.log(rollbackFailure(error, { branch: targetBranch, versionId, slug: slug || null, recordedBranch: target.info.branch }));
+    return { outcome: 'failed', error, exit_code: EXIT_FAILED };
+  }
+  if (!data || typeof data !== 'object') {
+    console.log('Hiveku gave no answer about the rollback. Check `hiveku-sync versions` before trying again.');
+    return { outcome: 'failed', exit_code: EXIT_FAILED };
+  }
+
+  const targetName = data.target?.name ? `"${data.target.name}"` : `version ${fullId}`;
+  const where = branchLabel(targetBranch);
+
+  if (!apply) {
+    console.log(`Roll ${where} back to ${targetName}${data.target?.created_at ? ` (${formatWhen(data.target.created_at)} UTC)` : ''}:`);
+    if (data.noop) {
+      console.log(`  ${where} already matches that version. There is nothing to roll back.`);
+      return { outcome: 'dry_run', dry_run: data, exit_code: 0 };
+    }
+    console.log(`  ${countLine(data.changes?.files)}.`);
+    const pages = Array.isArray(data.changes?.pages) ? data.changes.pages.map((page) => page.label).filter(Boolean) : [];
+    if (pages.length) console.log(`  Pages: ${pages.slice(0, 6).join(', ')}${pages.length > 6 ? ` and ${pages.length - 6} more` : ''}.`);
+    const undone = data.versions_undone;
+    if (undone && undone.count) {
+      const newest = undone.newest?.[0]?.name;
+      console.log(`  Undoes ${undone.count} newer version${undone.count === 1 ? '' : 's'}${newest ? `, the newest "${newest}"` : ''}. They stay in the history, so this can be undone too.`);
+    }
+    if (data.auto_version?.will_create) {
+      console.log(`  Changes not saved as a version yet are saved first, as "${data.auto_version.name || 'Saved before rollback'}".`);
+    }
+    if (data.assets_affected) console.log('  Images, fonts and videos in the shared asset store do not roll back.');
+    if (data.ai_turn_running) console.log('  The Hiveku AI is working on this site right now: wait for it to finish before applying.');
+    if (data.live_includes_undone_work) {
+      console.log('  Your live site still shows the newer work. Rolling back does not change it; publish afterwards with `hiveku-sync deploy production`.');
+    }
+    console.log('\nThis was a dry run: nothing was changed.');
+    if (typeof data.head_commit_id !== 'string' || !data.head_commit_id) {
+      console.log(`${where} has no version to roll back from yet, so this cannot be applied.`);
+      return { outcome: 'dry_run', dry_run: data, exit_code: 0 };
+    }
+    console.log('To roll back, run:');
+    console.log(
+      `  ${applyCommand({
+        versionId: fullId,
+        slug: slug || null,
+        branch: targetBranch,
+        recordedBranch: target.info.branch,
+        head: data.head_commit_id,
+        fingerprint: data.live_fingerprint,
+        name: typedName,
+      })}`,
+    );
+    return { outcome: 'dry_run', dry_run: data, exit_code: 0 };
+  }
+
+  if (data.dry_run !== false) {
+    // The apply did not reach Hiveku as one (only a dry run came back).
+    console.log('Hiveku only showed what would change; nothing was rolled back. Check `hiveku-sync versions`.');
+    return { outcome: 'failed', result: data, exit_code: EXIT_FAILED };
+  }
+  if (data.noop) {
+    console.log(`${where} already matches ${targetName}. Nothing was changed.`);
+    return { outcome: 'noop', result: data, exit_code: 0 };
+  }
+  const newName = data.version?.name ? ` The new version is "${data.version.name}".` : '';
+  console.log(`Rolled ${where} back to ${targetName}.${newName}`);
+  if (data.auto_version?.name) console.log(`  Changes that were not saved as a version were saved first, as "${data.auto_version.name}".`);
+  if (Array.isArray(data.concurrent_edits) && data.concurrent_edits.length) {
+    console.log(`  ${data.concurrent_edits.length} file${data.concurrent_edits.length === 1 ? ' was' : 's were'} edited by someone else while this ran; check them.`);
+  }
+  console.log('  No published site changed. To publish this version: hiveku-sync deploy <development|staging|production>');
+  console.log(`  To bring these files into your local folder: hiveku-sync pull-project ${target.slug}${targetBranch ? ` --branch ${targetBranch}` : ''}`);
+  return { outcome: 'rolled_back', result: data, exit_code: 0 };
+}