@hiveku-apps/sync 0.3.5 → 0.4.0

package/src/versionName.mjs

@@ -0,0 +1,569 @@
+/**
+ * Plain-language version names: a port of the builder's naming module.
+ *
+ * Source of truth: hiveku_builder src/lib/vcs/version-naming.ts, with the two
+ * pure modules it depends on (src/lib/deployment/file-to-route.ts and
+ * src/lib/vcs/customer-visible-path.ts, which reads
+ * src/lib/builder/server-managed-files.ts and
+ * src/lib/builder/project-memory-path-policy.ts). The builder, the Python
+ * agent fallback (version_name.py) and the VS Code extension (versionName.ts)
+ * are tested against one table, test/fixtures/version-naming-cases.json (a
+ * copy of src/lib/vcs/__fixtures__/version-naming-cases.json); this port runs
+ * every row of it. Change a rule there first, copy the table, then re-port.
+ *
+ * What hiveku-sync uses it for:
+ *   - describeChanges: the name of the version a push saves when the person
+ *     gave none ("Edited the Home page", never a file path);
+ *   - isPlainVersionName: the check on a name typed with -m. The builder keeps
+ *     a hiveku-sync name exactly as sent (source sync_cli), so the CLI checks
+ *     it itself before anything is written.
+ *
+ * Every sort compares plain character codes (never locale order), as the
+ * builder does, so the ports agree.
+ */
+
+// ── server-managed-files.ts ──────────────────────────────────────────────────
+
+const SERVER_MANAGED_PATHS = new Set([
+  'soul.md',
+  'connected_tools.md',
+  '.mcp.json',
+  '.claude/settings.json',
+  '.claude/commands/generate-image.md',
+  '.claude/commands/scrape.md',
+  '.claude/commands/search.md',
+]);
+const SERVER_MANAGED_PREFIXES = ['.claude/skills/', '.claude/rules/', 'data/marketing/'];
+
+/** Files the server writes into every project (never the customer's work). */
+export function isServerManagedFile(filePath) {
+  if (SERVER_MANAGED_PATHS.has(filePath)) return true;
+  return SERVER_MANAGED_PREFIXES.some((prefix) => filePath.startsWith(prefix));
+}
+
+// ── project-memory-path-policy.ts ────────────────────────────────────────────
+
+const WRITABLE_MEMORY_FILES = ['CLAUDE.md', 'CLAUDE.local.md', '.ai/memory.md'];
+const COMMANDS_PREFIX = '.claude/commands/';
+
+// ── customer-visible-path.ts ─────────────────────────────────────────────────
+
+const NOTES_FILE_NAMES = ['CLAUDE.md', 'CLAUDE.local.md'];
+const NOTES_DIR_NAMES = ['.ai', '.claude', '.hiveku'];
+
+/** Strip `./` and leading slashes so `/CLAUDE.md` and `./.ai/x` classify like `CLAUDE.md` and `.ai/x`. */
+export function normalizeVersionPath(path) {
+  let p = String(path ?? '').trim();
+  for (;;) {
+    if (p.startsWith('./')) p = p.slice(2);
+    else if (p.startsWith('/')) p = p.slice(1);
+    else break;
+  }
+  return p;
+}
+
+/** The assistant's notes (versioned, never shown): .ai/*, CLAUDE.md, .claude/**, .hiveku/*, at any depth. */
+export function isAssistantNotesPath(path) {
+  const p = normalizeVersionPath(path);
+  if (!p) return false;
+  if (WRITABLE_MEMORY_FILES.includes(p)) return true;
+  if (p.startsWith(COMMANDS_PREFIX)) return true;
+  const segments = p.split('/').filter((segment) => segment.length > 0);
+  const base = segments[segments.length - 1] ?? '';
+  if (NOTES_FILE_NAMES.includes(base)) return true;
+  return segments.slice(0, -1).some((segment) => NOTES_DIR_NAMES.includes(segment));
+}
+
+/** Should a customer see this path in a version name or change list? */
+export function isCustomerVisiblePath(path) {
+  const p = normalizeVersionPath(path);
+  if (!p) return false;
+  if (isAssistantNotesPath(p)) return false;
+  if (isServerManagedFile(p)) return false;
+  return true;
+}
+
+// ── file-to-route.ts ─────────────────────────────────────────────────────────
+
+const ROUTE_FILE_RE = /(^|\/)(page|route|layout|template|loading|error|not-found|default)\.(tsx?|jsx?|mdx?)$/;
+
+/** Map an app/ (or pages/) file to its route + kind, or null for a file that defines no route. */
+export function fileToRoute(filePath) {
+  const clean = filePath.replace(/^\//, '');
+  if (clean === 'src/middleware.ts' || clean === 'middleware.ts') {
+    return { route: '(middleware)', kind: 'middleware' };
+  }
+
+  let m = clean.match(/^(?:src\/)?app\/(.*)$/);
+  if (m) {
+    const rest = m[1];
+    if (!ROUTE_FILE_RE.test('/' + rest)) return null;
+    const fileBase = rest.split('/').pop() || '';
+    const kind = fileBase.startsWith('route.')
+      ? 'api'
+      : fileBase.startsWith('layout.') || fileBase.startsWith('template.')
+        ? 'layout'
+        : 'page';
+    const segs = rest
+      .split('/')
+      .slice(0, -1)
+      .filter((s) => !(s.startsWith('(') && s.endsWith(')')))
+      .filter((s) => !s.startsWith('@'));
+    const route = '/' + segs.join('/');
+    return { route: route === '/' ? '/' : route.replace(/\/$/, ''), kind };
+  }
+
+  m = clean.match(/^(?:src\/)?pages\/(.*)\.(tsx?|jsx?|mdx?)$/);
+  if (m) {
+    let p = m[1];
+    if (p === 'index' || p.endsWith('/index')) p = p.replace(/\/?index$/, '');
+    if (p.startsWith('api/')) return { route: '/' + p, kind: 'api' };
+    return { route: '/' + p || '/', kind: 'page' };
+  }
+
+  return null;
+}
+
+// ── version-naming.ts ────────────────────────────────────────────────────────
+
+export const MAX_VERSION_NAME_LENGTH = 80;
+/** Page and part names are cut to this many characters (29 + "…"). */
+export const MAX_THING_NAME_LENGTH = 30;
+
+const LABEL = {
+  styles: 'Site styles',
+  layout: 'Site layout',
+  images: 'Images',
+  logic: 'Forms and site logic',
+  settings: 'Site settings',
+  content: 'Blog content',
+  notes: "Assistant's notes",
+  other: 'Other files',
+};
+
+const PHRASE = {
+  styles: 'site styles',
+  layout: 'the site layout',
+  images: 'images',
+  logic: 'forms and site logic',
+  settings: 'site settings',
+  content: 'blog content',
+  notes: "the assistant's notes",
+  other: 'other files',
+};
+
+const KIND_ORDER = ['page', 'part', 'layout', 'styles', 'content', 'images', 'logic', 'settings', 'other', 'notes'];
+
+const SETTINGS_FILE_RE =
+  /^(package\.json|package-lock\.json|yarn\.lock|pnpm-lock\.yaml|pnpm-workspace\.yaml|bun\.lockb?|tsconfig([.-][\w.-]+)?\.json|jsconfig\.json|next\.config\.[cm]?[jt]s|next-env\.d\.ts|vercel\.json|netlify\.toml|components\.json|hiveku\.cms\.json|instrumentation\.[jt]s|\.env(\..*)?|\.gitignore|\.npmrc|\.nvmrc|\.node-version|\.eslintrc(\..*)?|eslint\.config\.[cm]?[jt]s|\.prettierrc(\..*)?|prettier\.config\.[cm]?[jt]s|vite\.config\.[cm]?[jt]s|astro\.config\.[cm]?[jt]s)$/;
+const SITE_FILE_RE =
+  /^(robots\.(txt|ts|js)|sitemap([-_.][\w-]+)?\.(xml|ts|js)|manifest\.(json|ts|js|webmanifest)|site\.webmanifest|ads\.txt|llms\.txt)$/;
+const STYLE_CONFIG_RE = /^(tailwind|postcss)\.config\.[cm]?[jt]s$/;
+const APP_IMAGE_RE = /^(opengraph-image|twitter-image|icon|apple-icon)(\.alt)?\.(tsx?|jsx?|txt)$/;
+const SPA_SHELL_RE = /^(App|main)\.(tsx|jsx|vue|svelte)$/;
+const TEST_FILE_RE = /\.(test|spec|stories)\.[cm]?[jt]sx?$/;
+
+const STYLE_EXTS = ['css', 'scss', 'sass', 'less', 'styl'];
+const FONT_EXTS = ['woff', 'woff2', 'ttf', 'otf', 'eot'];
+const MEDIA_EXTS = [
+  'png', 'jpg', 'jpeg', 'gif', 'webp', 'avif', 'svg', 'ico', 'bmp', 'tif', 'tiff', 'heic', 'heif',
+  'mp4', 'webm', 'mov', 'm4v', 'mp3', 'wav', 'ogg', 'm4a',
+];
+const HTML_EXTS = ['html', 'htm'];
+const MARKDOWN_EXTS = ['md', 'mdx', 'markdown'];
+const APP_CODE_EXTS = ['ts', 'tsx', 'js', 'jsx', 'mdx', 'md'];
+const COMPONENT_EXTS = ['tsx', 'jsx', 'vue', 'svelte', 'astro'];
+const SCRIPT_EXTS = ['ts', 'js', 'mjs', 'cjs'];
+const LOGIC_EXTS = ['sql', 'prisma'];
+
+const STYLE_DIRS = ['styles', 'theme'];
+const CONTENT_DIRS = ['content', 'posts', '_posts'];
+const PART_DIRS = ['components', '_components', 'sections', '_sections'];
+const LOGIC_DIRS = [
+  'lib', 'utils', 'hooks', 'services', 'server', 'actions', 'api', 'store', 'stores', 'context',
+  'contexts', 'providers', 'helpers', 'types', 'db', 'prisma', 'supabase', 'functions', 'netlify',
+  'middleware',
+];
+const APP_CUT_DIRS = [
+  'components', 'lib', 'utils', 'hooks', 'sections', 'ui', 'styles', 'types', 'data', 'helpers',
+  'actions', 'constants', 'content', 'assets', 'icons', 'images',
+];
+const ROUTE_STATE_STEMS = ['error', 'loading', 'default', 'template'];
+
+const DYNAMIC_SEGMENT_RE = /^\[.*\]$/;
+const LOCALE_SEGMENT_RE = /^\[(locale|lang|lng|language)\]$/;
+const ACRONYMS = { faq: 'FAQ', faqs: 'FAQs', seo: 'SEO', cta: 'CTA', ai: 'AI' };
+
+function fixed(kind) {
+  return { kind, name: LABEL[kind], phrase: PHRASE[kind] };
+}
+
+function clampName(name) {
+  if (name.length <= MAX_THING_NAME_LENGTH) return name;
+  return name.slice(0, MAX_THING_NAME_LENGTH - 1).trimEnd() + '…';
+}
+
+function isAllCapsWord(word) {
+  return word.length > 1 && word === word.toUpperCase() && /[A-Z]/.test(word);
+}
+
+/** "old-offer" → "Old offer", "PricingTable" → "Pricing table", "FAQSection" → "FAQ section". */
+export function humanizeSegment(segment) {
+  const spaced = segment
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .replace(/[-_.\s]+/g, ' ')
+    .trim();
+  if (!spaced) return '';
+  return spaced
+    .split(' ')
+    .filter((word) => word.length > 0)
+    .map((word, index) => {
+      const lower = word.toLowerCase();
+      const acronym = Object.prototype.hasOwnProperty.call(ACRONYMS, lower) ? ACRONYMS[lower] : undefined;
+      if (acronym) return acronym;
+      if (isAllCapsWord(word)) return word;
+      return index === 0 ? lower.charAt(0).toUpperCase() + lower.slice(1) : lower;
+    })
+    .join(' ');
+}
+
+function lowerFirst(name) {
+  const firstWord = name.split(' ')[0] ?? '';
+  if (isAllCapsWord(firstWord)) return name;
+  return name.charAt(0).toLowerCase() + name.slice(1);
+}
+
+function pageFromRoute(rawRoute, pageFile) {
+  let segments = rawRoute.split('/').filter((segment) => segment.length > 0);
+  if (segments.length > 0 && LOCALE_SEGMENT_RE.test(segments[0])) segments = segments.slice(1);
+  const route = '/' + segments.join('/');
+  if (segments.length === 0) {
+    return { kind: 'page', name: 'Home', phrase: 'the Home page', route: '/', dynamic: false, pageFile };
+  }
+  const last = segments[segments.length - 1];
+  if (DYNAMIC_SEGMENT_RE.test(last)) {
+    let parent = null;
+    for (let i = segments.length - 2; i >= 0; i--) {
+      if (!DYNAMIC_SEGMENT_RE.test(segments[i])) {
+        parent = segments[i];
+        break;
+      }
+    }
+    const parentName = parent === null ? '' : clampName(humanizeSegment(parent));
+    if (!parentName) {
+      return { kind: 'page', name: 'All pages', phrase: 'every page', route, dynamic: true, pageFile };
+    }
+    const name = parent !== null && parent.toLowerCase() === 'blog' ? 'Blog posts' : `${parentName} pages`;
+    return { kind: 'page', name, phrase: `each page under ${parentName}`, route, dynamic: true, pageFile };
+  }
+  const name = clampName(humanizeSegment(last)) || 'Untitled';
+  return { kind: 'page', name, phrase: `the ${name} page`, route, dynamic: false, pageFile };
+}
+
+function partFrom(rel, stem) {
+  const source = stem.toLowerCase() === 'index' && rel.length >= 2 ? rel[rel.length - 2] : stem;
+  const words = humanizeSegment(source);
+  const bare = /^The .+/.test(words) ? words.slice(4) : words;
+  const name = clampName(bare.charAt(0).toUpperCase() + bare.slice(1)) || 'Site section';
+  return { kind: 'part', name, phrase: `the ${lowerFirst(name)}` };
+}
+
+function inPartFolder(rel) {
+  return rel.slice(0, -1).some((segment) => PART_DIRS.includes(segment));
+}
+
+function classifyApp(path, rel, stem, ext) {
+  const codeFile = APP_CODE_EXTS.includes(ext);
+  if (codeFile && stem === 'not-found') return pageFromRoute('/404', true);
+  if (codeFile && stem === 'global-error') return fixed('layout');
+
+  const route = fileToRoute(path);
+  if (route) {
+    if (route.kind === 'api' || route.kind === 'middleware') return fixed('logic');
+    const page = pageFromRoute(route.route, false);
+    if (route.kind === 'layout' || ROUTE_STATE_STEMS.includes(stem)) {
+      return page.route === '/' ? fixed('layout') : page;
+    }
+    return { ...page, pageFile: stem === 'page' };
+  }
+
+  const kept = [];
+  for (const segment of rel.slice(1, -1)) {
+    if (segment.startsWith('_') || APP_CUT_DIRS.includes(segment)) break;
+    if (segment.startsWith('(') && segment.endsWith(')')) continue;
+    if (segment.startsWith('@')) continue;
+    kept.push(segment);
+  }
+  if (kept[0] === 'api') return fixed('logic');
+  const routeSegments = kept.length > 0 && LOCALE_SEGMENT_RE.test(kept[0]) ? kept.slice(1) : kept;
+  if (routeSegments.length === 0) {
+    if (COMPONENT_EXTS.includes(ext)) return partFrom(rel, stem);
+    if (!inPartFolder(rel) && SCRIPT_EXTS.includes(ext)) return fixed('logic');
+    return fixed('other');
+  }
+  return pageFromRoute('/' + kept.join('/'), false);
+}
+
+function classifyPagesRouter(path) {
+  const route = fileToRoute(path);
+  if (!route) return fixed('other');
+  if (route.kind === 'api' || route.kind === 'middleware') return fixed('logic');
+  const last = route.route.split('/').filter((segment) => segment.length > 0).pop() ?? '';
+  if (last === '_app' || last === '_document' || last === '_error') return fixed('layout');
+  return pageFromRoute(route.route, true);
+}
+
+function classify(input) {
+  const path = normalizeVersionPath(input);
+  if (!path || !isCustomerVisiblePath(path)) return fixed('notes');
+
+  const segments = path.split('/').filter((segment) => segment.length > 0);
+  const rel = segments.length > 1 && segments[0] === 'src' ? segments.slice(1) : segments;
+  const base = rel[rel.length - 1] ?? '';
+  const dot = base.lastIndexOf('.');
+  const ext = dot > 0 ? base.slice(dot + 1).toLowerCase() : '';
+  const stem = dot > 0 ? base.slice(0, dot) : base;
+  const first = rel[0] ?? '';
+  const atRoot = rel.length === 1;
+
+  if (rel.includes('__tests__') || TEST_FILE_RE.test(base)) return fixed('other');
+  if (atRoot && SETTINGS_FILE_RE.test(base)) return fixed('settings');
+  if ((atRoot || first === 'app' || first === 'public') && SITE_FILE_RE.test(base)) return fixed('settings');
+  if (atRoot && /^middleware\.[cm]?[jt]s$/.test(base)) return fixed('logic');
+  if (
+    STYLE_EXTS.includes(ext) ||
+    FONT_EXTS.includes(ext) ||
+    (atRoot && STYLE_CONFIG_RE.test(base)) ||
+    (!atRoot && STYLE_DIRS.includes(first))
+  ) {
+    return fixed('styles');
+  }
+  if (MEDIA_EXTS.includes(ext)) return fixed('images');
+  if (first === 'app' && APP_IMAGE_RE.test(base)) return fixed('images');
+  if (HTML_EXTS.includes(ext)) {
+    const routeSegments = first === 'public' ? rel.slice(1) : rel.slice();
+    routeSegments[routeSegments.length - 1] = stem;
+    if (stem.toLowerCase() === 'index') routeSegments.pop();
+    return pageFromRoute('/' + routeSegments.join('/'), true);
+  }
+  if (first === 'public') return fixed('other');
+  if (CONTENT_DIRS.includes(first) && !atRoot && MARKDOWN_EXTS.includes(ext)) return fixed('content');
+  if (first === 'app' && !atRoot) return classifyApp(path, rel, stem, ext);
+  if (first === 'pages' && !atRoot) return classifyPagesRouter(path);
+  if (atRoot && SPA_SHELL_RE.test(base)) return fixed('layout');
+  if (inPartFolder(rel)) return COMPONENT_EXTS.includes(ext) ? partFrom(rel, stem) : fixed('other');
+  if ((!atRoot && LOGIC_DIRS.includes(first)) || LOGIC_EXTS.includes(ext)) return fixed('logic');
+  return fixed('other');
+}
+
+/** What a file is to the customer: { kind, name, route? }. Never a path or extension in `name`. */
+export function describePath(path) {
+  const classified = classify(path);
+  return classified.route !== undefined
+    ? { kind: classified.kind, name: classified.name, route: classified.route }
+    : { kind: classified.kind, name: classified.name };
+}
+
+function joinList(items) {
+  if (items.length <= 1) return items[0] ?? '';
+  return `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
+}
+
+function plural(count, one, many) {
+  return `${count} ${count === 1 ? one : many}`;
+}
+
+/** Plain character-code order (UTF-16 units), never locale collation. */
+function compareText(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+const PAGE_VERB = { added: 'Added', modified: 'Edited', removed: 'Removed' };
+const THING_VERBS = ['Added', 'Changed', 'Removed'];
+const STATUS_ORDER = ['added', 'modified', 'removed'];
+
+function pageStatus(page) {
+  return page.pageFileStatuses.size === 1 ? [...page.pageFileStatuses][0] : 'modified';
+}
+
+function thingVerb(thing) {
+  if (thing.kind === 'part' || thing.kind === 'images' || thing.kind === 'content') {
+    if (thing.statuses.size === 1 && thing.statuses.has('added')) return 'Added';
+    if (thing.statuses.size === 1 && thing.statuses.has('removed')) return 'Removed';
+  }
+  return 'Changed';
+}
+
+function pageList(pages, first, countForm) {
+  const count = pages.length;
+  if (!first) return count === 1 && !countForm ? pages[0].phrase : plural(count, 'other', 'others');
+  if (countForm || count >= 4) return plural(count, 'page', 'pages');
+  if (pages.every((page) => !page.dynamic)) {
+    return `the ${joinList(pages.map((page) => page.name))} ${count === 1 ? 'page' : 'pages'}`;
+  }
+  return joinList(pages.map((page) => page.phrase));
+}
+
+function thingList(things) {
+  if (things.length >= 4) return plural(things.length, 'part of the site', 'parts of the site');
+  const parts = things.filter((thing) => thing.kind === 'part');
+  const items = [];
+  let partsWritten = false;
+  for (const thing of things) {
+    if (thing.kind === 'part' && parts.length >= 3) {
+      if (!partsWritten) items.push(plural(parts.length, 'site section', 'site sections'));
+      partsWritten = true;
+      continue;
+    }
+    items.push(thing.phrase);
+  }
+  return joinList(items);
+}
+
+function sentence(clauses) {
+  const lowered = clauses.map((clause, index) => (index === 0 ? clause : clause.charAt(0).toLowerCase() + clause.slice(1)));
+  return joinList(lowered);
+}
+
+function filesSentence(counts) {
+  const total = counts.added + counts.modified + counts.removed;
+  const verb = counts.added === total ? 'Added' : counts.removed === total ? 'Removed' : 'Edited';
+  return `${verb} ${plural(total, 'file', 'files')}`;
+}
+
+/**
+ * A plain version name (≤ 80 characters, never a path or file extension) for
+ * the files a change added, modified and removed.
+ */
+export function describeChanges(changes = {}) {
+  const seen = new Set();
+  const pages = new Map();
+  const things = new Map();
+  const otherCounts = { added: 0, modified: 0, removed: 0 };
+  let total = 0;
+  let visible = 0;
+
+  for (const status of STATUS_ORDER) {
+    for (const raw of changes[status] ?? []) {
+      const path = normalizeVersionPath(raw);
+      if (!path || seen.has(path)) continue;
+      seen.add(path);
+      total++;
+      const classified = classify(path);
+      if (classified.kind === 'notes') continue;
+      visible++;
+      if (classified.kind === 'other') {
+        otherCounts[status]++;
+        continue;
+      }
+      if (classified.kind === 'page') {
+        const key = `${classified.dynamic ? 'dynamic' : 'static'}:${classified.name}`;
+        const route = classified.route ?? '/';
+        let page = pages.get(key);
+        if (!page) {
+          page = { name: classified.name, phrase: classified.phrase, route, dynamic: classified.dynamic === true, pageFileStatuses: new Set() };
+          pages.set(key, page);
+        } else if (compareText(route, page.route) < 0) {
+          page.route = route;
+        }
+        if (classified.pageFile) page.pageFileStatuses.add(status);
+        continue;
+      }
+      const key = `${classified.kind}:${classified.name}`;
+      let thing = things.get(key);
+      if (!thing) {
+        thing = { kind: classified.kind, name: classified.name, phrase: classified.phrase, statuses: new Set() };
+        things.set(key, thing);
+      }
+      thing.statuses.add(status);
+    }
+  }
+
+  if (total === 0) return 'No changes';
+  if (visible === 0) return "Updated the assistant's notes";
+  if (pages.size === 0 && things.size === 0) return filesSentence(otherCounts);
+
+  const pageGroups = [];
+  for (const status of STATUS_ORDER) {
+    const group = [...pages.values()]
+      .filter((page) => pageStatus(page) === status)
+      .sort((a, b) => compareText(a.route, b.route) || compareText(a.name, b.name));
+    if (group.length > 0) pageGroups.push({ status, pages: group });
+  }
+
+  const sortedThings = [...things.values()].sort(
+    (a, b) => KIND_ORDER.indexOf(a.kind) - KIND_ORDER.indexOf(b.kind) || compareText(a.name, b.name),
+  );
+  const thingGroups = [];
+  for (const verb of THING_VERBS) {
+    const group = sortedThings.filter((thing) => thingVerb(thing) === verb);
+    if (group.length > 0) thingGroups.push({ verb, things: group });
+  }
+
+  const pageClauses = (countForm) =>
+    pageGroups.map((group, index) => `${PAGE_VERB[group.status]} ${pageList(group.pages, index === 0, countForm)}`);
+  const thingClauses = thingGroups.map((group) => `${group.verb} ${thingList(group.things)}`);
+
+  const oneThingClause = things.size > 0 ? [`Changed ${plural(things.size, 'part of the site', 'parts of the site')}`] : [];
+  const candidates = [
+    sentence([...pageClauses(false), ...thingClauses]),
+    sentence([...pageClauses(false), ...oneThingClause]),
+    sentence([...pageClauses(true), ...thingClauses]),
+    sentence([...pageClauses(true), ...oneThingClause]),
+  ];
+  for (const candidate of candidates) {
+    if (candidate.length <= MAX_VERSION_NAME_LENGTH) return candidate;
+  }
+  return `Edited ${plural(visible, 'file', 'files')}`;
+}
+
+// ── Checking a name someone typed ────────────────────────────────────────────
+
+const COMMIT_PREFIX_RE = /^(fix|feat|chore|refactor|docs|style|test|perf|build|ci|revert)(\([^)]*\))?!?:/i;
+/** The exact legacy agent byline ("Hiveku AI:" or "AI:", this case, at the start). */
+const LEGACY_AGENT_BYLINE_RE = /^(?:Hiveku AI|AI):/;
+/** A file extension a site's files actually use (closed list: "e.g." and "St.Patrick's" are fine). */
+const FILE_EXTENSION_RE =
+  /\.(tsx?|jsx?|[cm]js|s?css|sass|less|html?|json|mdx?|markdown|ya?ml|toml|xml|txt|svg|png|jpe?g|gif|webp|avif|ico|pdf|mp4|webm|woff2?|vue|svelte|astro|py|sql|prisma|sh|env|lock)\b/i;
+
+/** Does `name` start with the exact legacy agent byline ("Hiveku AI:", "AI:")? */
+export function hasLegacyVersionPrefix(name) {
+  return LEGACY_AGENT_BYLINE_RE.test(String(name ?? '').trim());
+}
+
+/** `name` trimmed, with the exact legacy agent byline removed once from the front. */
+export function stripLegacyVersionPrefix(name) {
+  const trimmed = String(name ?? '').trim();
+  return LEGACY_AGENT_BYLINE_RE.test(trimmed) ? trimmed.replace(LEGACY_AGENT_BYLINE_RE, '').trim() : trimmed;
+}
+
+/**
+ * True when `name` reads as a plain version name: non-empty, at most 80
+ * characters, no path separator, no file extension, no "fix:"-style prefix and
+ * no legacy agent byline.
+ */
+export function isPlainVersionName(name) {
+  const trimmed = String(name ?? '').trim();
+  if (!trimmed || trimmed.length > MAX_VERSION_NAME_LENGTH) return false;
+  if (/[\\/]/.test(trimmed)) return false;
+  if (FILE_EXTENSION_RE.test(trimmed)) return false;
+  if (COMMIT_PREFIX_RE.test(trimmed)) return false;
+  if (LEGACY_AGENT_BYLINE_RE.test(trimmed)) return false;
+  return true;
+}
+
+/**
+ * Why a typed name is not a plain version name, in words for the person who
+ * typed it, or null when it is plain.
+ */
+export function versionNameProblem(name) {
+  const trimmed = String(name ?? '').trim();
+  if (!trimmed) return 'it is empty';
+  if (trimmed.length > MAX_VERSION_NAME_LENGTH) return `it is longer than ${MAX_VERSION_NAME_LENGTH} characters`;
+  if (/[\\/]/.test(trimmed)) return 'it contains a file path';
+  if (FILE_EXTENSION_RE.test(trimmed)) return 'it contains a file name';
+  if (COMMIT_PREFIX_RE.test(trimmed)) return 'it starts with a developer prefix like "fix:"';
+  if (LEGACY_AGENT_BYLINE_RE.test(trimmed)) return 'it starts with "AI:" (the history already shows who made each version)';
+  return null;
+}