logwork-cli 1.2.0 → 1.3.0

package/lib/mcp-server.mjs

@@ -135,7 +135,7 @@ server.registerTool('list_tasks', {
 
 server.registerTool('draft_from_commits', {
   title: 'Draft logwork from git commits',
-  description: 'Read-only: read the user\'s own git commits (all branches, git user.email) in one or more repos for a period, group them per day by repo + ticket + kind of work, suggest an RO worklog task per group (feat -> Feature Development, fix -> Bug Fix, refactor/review -> Code Review & Refactoring, test -> Testing Activities, ci/build/release -> Deployment & Release, docs -> Requirements & Design), and resolve each group\'s RO project (a map_project mapping whose repos holds the repo, else ticket/keyword mappings and that day\'s bookings), and split each project\'s remaining RO hours (booked - logged) across its groups; groups without a project share the room of booked projects no group claimed. Returns draftText in the log_work line format plus projectOverrides (preview entry id -> projectMemberId) for every line with a project. Review it with the user, check task names with list_tasks, then pass draftText and projectOverrides unchanged to log_work. unmappedRepos lists repos whose lines got no project: offer map_project with repos.',
+  description: 'Read-only: read the user\'s own git commits (all branches, git user.email) in one or more repos for a period, group them per day by repo + ticket + kind of work, suggest an RO worklog task per group (feat -> Feature Development, fix -> Bug Fix, refactor/review -> Code Review & Refactoring, test -> Testing Activities, ci/build/release -> Deployment & Release, docs -> Requirements & Design), and resolve each group\'s RO project (a map_project mapping whose repos holds the repo, else ticket/keyword mappings and that day\'s bookings), and split each project\'s remaining RO hours (booked - logged) across its groups; groups without a project share the room of booked projects no group claimed. Returns draftText in the log_work line format plus projectOverrides (preview entry id -> projectMemberId) for every line with a project. Review it with the user, check task names with list_tasks, then pass draftText and projectOverrides unchanged to log_work. unmappedRepos lists repos whose lines got no project; repoSuggestions maps each of them to up to 5 ranked projects ({ projectName, projectMemberId, projectId, score, reasons }) from ticket history, repo/remote name and single booked project, and projectCandidates lists every member project. For each unmapped repo ask the user one short question naming the top suggestion ("Is <repo> part of <projectName>?"), then call map_project with projectName (or projectMemberId) and repos (confirm: true after approval), and run draft_from_commits again. Never ask the user for ids.',
   annotations: READ_ONLY,
   inputSchema: {
     period: z.enum(PERIOD_VALUES).optional().describe('Preset period. Defaults to today.'),
@@ -348,7 +348,7 @@ server.registerTool('login', {
 
 server.registerTool('reminder', {
   title: 'Logwork reminder',
-  description: 'The native macOS/Windows weekday logwork reminder. action "status" is read-only. "enable", "disable" and "test" (shows a sample notification) change the OS scheduler or display a notification and require confirm: true after explicit user approval. When RO hours are missing, the notification also counts today\'s commits in the configured repos. status warns when the Node path in the schedule no longer exists. No credentials are stored in the schedule.',
+  description: 'The native macOS/Windows weekday logwork reminder. action "status" is read-only. "enable", "disable" and "test" (shows a sample notification) change the OS scheduler or display a notification and require confirm: true after explicit user approval. When RO hours are missing, the notification also counts today\'s commits in the configured repos. status warns when the command in the schedule (the logwork launcher, or node.exe on Windows) is missing or outdated. No credentials are stored in the schedule.',
   annotations: LOCAL_WRITE,
   inputSchema: {
     action: z.enum(['status', 'enable', 'disable', 'test']).describe('status: show config and scheduler state. enable/disable: install or remove the schedule. test: send a sample notification.'),

package/lib/node-runtime.mjs

@@ -1,12 +1,14 @@
 import { promises as fs } from 'node:fs';
+import { basename } from 'node:path';
 import { atomicWriteFile } from './atomic-file.mjs';
+import { LAUNCHER_FILE_NAME, resolveLaunchCommand } from './launcher.mjs';
 import { runtimeInfoPath } from './paths.mjs';
 
-// The node binary that runs the MCP server and the reminder is stored as an
-// absolute path (IDE configs, the launchd plist, the Windows task). With nvm,
-// Homebrew or a Node installer upgrade that path can disappear or stop being
-// the node the user runs. `logwork setup` records it here so `logwork doctor`
-// and `logwork reminder status` can tell when it went stale.
+// `logwork setup` records the node it ran with here. On macOS/Linux the
+// generated launcher (lib/launcher.mjs) tries that node first and falls back
+// to another Node 22+, so IDE configs and the reminder survive upgrades. On
+// Windows the configs and the task store a node.exe path, which `logwork
+// doctor` and `logwork reminder status` compare with this record.
 
 export async function writeRuntimeInfo({
   path = runtimeInfoPath(),
@@ -83,24 +85,62 @@ export async function inspectNodePath(recordedPath, {
   return { status: 'stale', recordedPath: recorded, currentPath };
 }
 
-// source "runtime": the node recorded by `logwork setup` (used by the printed
-// MCP configs). source "reminder": the node in the installed OS schedule.
+// Compares the command an installed OS schedule runs with the current launch
+// command. Statuses:
+// ok: it runs the current launch command (and that command exists).
+// missing: the command (launcher or node) no longer exists.
+// legacy: macOS/Linux schedule from an older install that runs a raw Node
+//   path instead of the launcher.
+// stale: it runs another launcher or another node.
+export async function inspectScheduledCommand(commandPath, {
+  launch = resolveLaunchCommand(),
+  platform = process.platform,
+  exists = pathExists,
+  inspect = inspectNodePath
+} = {}) {
+  const recorded = String(commandPath || '');
+  const currentPath = launch.command;
+  if (!recorded) {
+    return { status: 'unknown', recordedPath: '', currentPath };
+  }
+  const same = platform === 'win32'
+    ? recorded.toLowerCase() === String(currentPath).toLowerCase()
+    : recorded === currentPath;
+  if (same) {
+    return { status: await exists(recorded) ? 'ok' : 'missing', recordedPath: recorded, currentPath, kind: launch.kind };
+  }
+  if (launch.kind === 'launcher') {
+    if (basename(recorded) === LAUNCHER_FILE_NAME) {
+      return { status: await exists(recorded) ? 'stale' : 'missing', recordedPath: recorded, currentPath, kind: 'launcher' };
+    }
+    return { status: await exists(recorded) ? 'legacy' : 'missing', recordedPath: recorded, currentPath, kind: 'node' };
+  }
+  const checked = await inspect(recorded, { currentPath, platform });
+  return { ...checked, currentPath, kind: 'node' };
+}
+
+// source "runtime": the node recorded by `logwork setup` (Windows MCP configs
+// use it). source "reminder": the command in the installed OS schedule.
 export function formatNodePathIssue(source, inspection) {
-  const { status, recordedPath, currentPath } = inspection || {};
+  const { status, recordedPath, currentPath, kind } = inspection || {};
   if (source === 'reminder') {
+    const what = kind === 'launcher' ? 'the logwork launcher at' : 'Node at';
     if (status === 'missing') {
-      return `Reminder: the OS schedule runs Node at ${recordedPath}, which no longer exists, so the reminder cannot run. Fix: run \`logwork reminder enable\` (or \`logwork setup\`) to re-register it with the current Node.`;
+      return `Reminder: the OS schedule runs ${what} ${recordedPath}, which no longer exists, so the reminder cannot run. Fix: run \`logwork reminder enable\` (or \`logwork setup\`) to re-register it.`;
+    }
+    if (status === 'legacy') {
+      return `Reminder: the OS schedule runs Node at ${recordedPath} directly instead of the logwork launcher, so a Node upgrade will break it. Fix: re-run \`logwork setup\` (or \`logwork reminder enable\`).`;
     }
     if (status === 'stale') {
-      return `Reminder: the OS schedule runs Node at ${recordedPath}, but the current Node is ${currentPath}. Fix: run \`logwork reminder enable\` to re-register it with the current Node.`;
+      return `Reminder: the OS schedule runs ${what} ${recordedPath}, but the current command is ${currentPath}. Fix: run \`logwork reminder enable\` (or \`logwork setup\`) to re-register it.`;
     }
     return '';
   }
   if (status === 'missing') {
-    return `Runtime: \`logwork setup\` recorded Node at ${recordedPath}, which no longer exists, so IDE MCP configs that use it cannot start. Fix: run \`logwork setup\` and paste the new MCP config "command" into your IDE.`;
+    return `Runtime: \`logwork setup\` recorded Node at ${recordedPath}, which no longer exists, so IDE MCP configs that use it cannot start. Fix: run \`logwork setup\`; it updates the MCP configs it can edit.`;
   }
   if (status === 'stale') {
-    return `Runtime: \`logwork setup\` recorded Node at ${recordedPath}, but the current Node is ${currentPath}. Fix: if you switched Node on purpose, run \`logwork setup\` and update the MCP config "command" in your IDE.`;
+    return `Runtime: \`logwork setup\` recorded Node at ${recordedPath}, but the current Node is ${currentPath}. Fix: if you switched Node on purpose, run \`logwork setup\`; it updates the MCP configs it can edit.`;
   }
   return '';
 }

package/lib/project-mapping-workflow.mjs

@@ -1,13 +1,12 @@
 import { homedir } from 'node:os';
 import { resolve } from 'node:path';
-import { ApiError, getProjects } from './api.mjs';
 import { resolveGitRepoRoot } from './commit-workflow.mjs';
 import {
   configPath,
   loadLocalConfig,
   upsertProjectMappingConfig
 } from './logwork-config.mjs';
-import { createResourceOptimiserSession } from './query-workflow.mjs';
+import { createMembershipProjectsFetcher } from './query-workflow.mjs';
 
 export async function listLogworkProjects({
   cwd = process.cwd(),
@@ -167,24 +166,7 @@ export function enrichRoPreviewWithJiraProjects(roPreview, jiraPreview) {
   };
 }
 
-function createMembershipProjectsFetcher() {
-  const session = createResourceOptimiserSession();
-  return async () => {
-    const { token, userId } = await session.get();
-    try {
-      return await getProjects(token, userId);
-    } catch (error) {
-      if (!(error instanceof ApiError) || error.status !== 401) {
-        throw error;
-      }
-
-      const refreshed = await session.get({ forceLogin: true });
-      return getProjects(refreshed.token, refreshed.userId);
-    }
-  };
-}
-
-function resolveProjectSelection(projects, { projectMemberId, projectName }) {
+export function resolveProjectSelection(projects, { projectMemberId, projectName }) {
   if (projectMemberId !== undefined && projectMemberId !== null && String(projectMemberId).trim() !== '') {
     const project = projects.find((candidate) => String(candidate.projectMemberId) === String(projectMemberId));
     return project

package/lib/query-workflow.mjs

@@ -4,6 +4,7 @@ import {
   combineNormalizationDiagnostics,
   getDayLogs,
   getLogworkDay,
+  getProjects,
   getLogworkRejected,
   getNormalizationDiagnostics,
   getTimesheetRangeResult
@@ -288,6 +289,24 @@ export function createDayLogsFetcher() {
   };
 }
 
+// The user's RO project memberships (projectMemberId, projectId, projectName).
+export function createMembershipProjectsFetcher() {
+  const session = createResourceOptimiserSession();
+  return async () => {
+    const { token, userId } = await session.get();
+    try {
+      return await getProjects(token, userId);
+    } catch (error) {
+      if (!(error instanceof ApiError) || error.status !== 401) {
+        throw error;
+      }
+
+      const refreshed = await session.get({ forceLogin: true });
+      return getProjects(refreshed.token, refreshed.userId);
+    }
+  };
+}
+
 export function createResourceOptimiserSession() {
   let cached = null;
 

package/lib/reminder-scheduler.mjs

@@ -3,6 +3,7 @@ import { promises as fs } from 'node:fs';
 import { homedir, userInfo } from 'node:os';
 import { join } from 'node:path';
 import { atomicWriteFile } from './atomic-file.mjs';
+import { resolveLaunchCommand, writeLauncher } from './launcher.mjs';
 import { helperHome } from './paths.mjs';
 import { normalizeReminderConfig } from './reminder-config.mjs';
 
@@ -12,18 +13,24 @@ export const WINDOWS_REMINDER_TASK_NAME = 'Logwork Reminder';
 // point at the old runtime, so installing or removing the reminder clears them.
 export const LEGACY_MACOS_REMINDER_LABEL = 'sg.vinova.logwork-helper.reminder';
 export const LEGACY_WINDOWS_REMINDER_TASK_NAME = 'Logwork Helper Reminder';
-// The scheduler runs `node <home>/bin/logwork.mjs reminder run --home <home>`.
+// The scheduler runs the launch command from lib/launcher.mjs with
+// `reminder run --home <home>`: on macOS the <home>/bin/logwork-launch script
+// (it finds Node itself), on Windows a stable node.exe plus
+// <home>\bin\logwork.mjs.
 export const REMINDER_RUNNER_RELATIVE_PATH = join('bin', 'logwork.mjs');
 
 export async function installReminderScheduler(config, {
   platform = process.platform,
   nodePath = process.execPath,
   home = helperHome(),
+  env = process.env,
+  launch = resolveLaunchCommand({ platform, home, execPath: nodePath, env }),
   userHome = homedir(),
   uid = userInfo().uid,
   run = runCommand,
   writeFile = atomicWriteFile,
-  accessRunner = fs.access
+  accessRunner = fs.access,
+  writeLauncherFn = writeLauncher
 } = {}) {
   const normalized = normalizeReminderConfig({ ...config, enabled: true });
   const runnerPath = join(home, REMINDER_RUNNER_RELATIVE_PATH);
@@ -32,14 +39,17 @@ export async function installReminderScheduler(config, {
   } catch {
     throw new Error(`Reminder runtime is missing at ${runnerPath}. Run \`logwork setup --no-login\` and retry.`);
   }
+  if (launch.kind === 'launcher') {
+    // `reminder enable` can run before `logwork setup` wrote the launcher.
+    await writeLauncherFn({ home, nodePath, platform });
+  }
   await removeLegacyReminderScheduler({ platform, userHome, uid, run });
 
   if (platform === 'darwin') {
     const plistPath = macosReminderPlistPath(userHome);
     await writeFile(plistPath, buildMacosReminderPlist({
       config: normalized,
-      nodePath,
-      runnerPath,
+      launch,
       home
     }));
     const domain = `gui/${uid}`;
@@ -58,8 +68,7 @@ export async function installReminderScheduler(config, {
   if (platform === 'win32') {
     const result = await run('schtasks.exe', buildWindowsReminderCreateArgs({
       config: normalized,
-      nodePath,
-      runnerPath,
+      launch,
       home
     }));
     assertCommandSuccess(result, 'schtasks /Create');
@@ -151,9 +160,10 @@ export async function getReminderSchedulerStatus({
   throw unsupportedReminderPlatform(platform);
 }
 
-// The node binary the installed schedule runs: the first ProgramArguments
-// entry of the launchd plist, or the <Command> of the Windows task. Returns
-// null when no schedule is installed or it cannot be read. Read-only.
+// The command the installed schedule runs: the first ProgramArguments entry of
+// the launchd plist (the launcher, or a raw node path from an older install),
+// or the <Command> of the Windows task (node.exe). Returns null when no
+// schedule is installed or it cannot be read. Read-only.
 export async function readReminderSchedulerNodePath({
   platform = process.platform,
   userHome = homedir(),
@@ -190,7 +200,15 @@ export function parseWindowsTaskNodePath(xml) {
   return unescapeXml(match[1]).trim().replace(/^"(.*)"$/, '$1') || null;
 }
 
-export function buildMacosReminderPlist({ config, nodePath, runnerPath, home }) {
+// `launch` is { command, argsPrefix }. Older callers pass nodePath + runnerPath.
+function scheduleProgram({ launch, nodePath, runnerPath, home }) {
+  const program = launch
+    ? [launch.command, ...(launch.argsPrefix || [])]
+    : [nodePath, runnerPath];
+  return [...program, 'reminder', 'run', '--home', home];
+}
+
+export function buildMacosReminderPlist({ config, launch, nodePath, runnerPath, home }) {
   const normalized = normalizeReminderConfig({ ...config, enabled: true });
   const [hour, minute] = normalized.time.split(':').map(Number);
   const calendarEntries = normalized.days.map((weekday) => `    <dict>
@@ -198,6 +216,9 @@ export function buildMacosReminderPlist({ config, nodePath, runnerPath, home })
       <key>Hour</key><integer>${hour}</integer>
       <key>Minute</key><integer>${minute}</integer>
     </dict>`).join('\n');
+  const programArguments = scheduleProgram({ launch, nodePath, runnerPath, home })
+    .map((part) => `    <string>${escapeXml(assertSafePath(part))}</string>`)
+    .join('\n');
 
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -206,12 +227,7 @@ export function buildMacosReminderPlist({ config, nodePath, runnerPath, home })
   <key>Label</key><string>${escapeXml(MACOS_REMINDER_LABEL)}</string>
   <key>ProgramArguments</key>
   <array>
-    <string>${escapeXml(assertSafePath(nodePath))}</string>
-    <string>${escapeXml(assertSafePath(runnerPath))}</string>
-    <string>reminder</string>
-    <string>run</string>
-    <string>--home</string>
-    <string>${escapeXml(assertSafePath(home))}</string>
+${programArguments}
   </array>
   <key>WorkingDirectory</key><string>${escapeXml(assertSafePath(home))}</string>
   <key>StartCalendarInterval</key>
@@ -225,9 +241,9 @@ ${calendarEntries}
 `;
 }
 
-export function buildWindowsReminderCreateArgs({ config, nodePath, runnerPath, home }) {
+export function buildWindowsReminderCreateArgs({ config, launch, nodePath, runnerPath, home }) {
   const normalized = normalizeReminderConfig({ ...config, enabled: true });
-  const action = [nodePath, runnerPath, 'reminder', 'run', '--home', home]
+  const action = scheduleProgram({ launch, nodePath, runnerPath, home })
     .map(quoteWindowsActionPart)
     .join(' ');
   const dayNames = normalized.days.map((day) => ({

package/lib/reminder-service.mjs

@@ -1,4 +1,5 @@
-import { formatNodePathIssue, inspectNodePath } from './node-runtime.mjs';
+import { checkLaunchCommand, formatLaunchCheckIssue } from './launcher.mjs';
+import { formatNodePathIssue, inspectScheduledCommand } from './node-runtime.mjs';
 import {
   loadReminderConfig,
   normalizeReminderConfig,
@@ -81,7 +82,8 @@ export async function getLogworkReminderStatus({
   loadConfig = loadReminderConfig,
   loadState = loadReminderState,
   schedulerStatus = getReminderSchedulerStatus,
-  inspectNode = inspectNodePath
+  inspectNode = inspectScheduledCommand,
+  checkLaunch = checkLaunchCommand
 } = {}) {
   const [config, state, scheduler] = await Promise.all([
     loadConfig(),
@@ -100,8 +102,9 @@ export async function getLogworkReminderStatus({
   if (!consistent) {
     lines.push('Warning: reminder config and OS scheduler are out of sync; run reminder enable or disable again.');
   }
-  // The schedule stores an absolute node path; nvm or Homebrew can remove it
-  // while the schedule still looks installed.
+  // The schedule stores an absolute command: the launcher on macOS (an older
+  // install: a raw node path), node.exe on Windows. nvm or Homebrew can remove
+  // a node while the schedule still looks installed.
   const nodeCheck = scheduler.nodePath
     ? await inspectNode(scheduler.nodePath).catch(() => ({ status: 'unknown', recordedPath: scheduler.nodePath }))
     : null;
@@ -109,6 +112,16 @@ export async function getLogworkReminderStatus({
   if (nodeIssue) {
     lines.push(`Warning: ${nodeIssue}`);
   }
+  let launchCheck = null;
+  if (nodeCheck?.status === 'ok' && nodeCheck.kind === 'launcher') {
+    launchCheck = await checkLaunch().catch(() => null);
+    const launchIssue = formatLaunchCheckIssue(launchCheck);
+    if (launchIssue) {
+      lines.push(`Warning: ${launchIssue}`);
+    } else if (launchCheck?.node) {
+      lines.push(`Launcher: runs Node ${launchCheck.node}.`);
+    }
+  }
   if (state?.lastRunAt) {
     lines.push(`Last run: ${state.lastRunAt}, status ${state.lastStatus || 'unknown'}.`);
   }
@@ -119,6 +132,7 @@ export async function getLogworkReminderStatus({
     state,
     consistent,
     ...(nodeCheck ? { nodeCheck } : {}),
+    ...(launchCheck ? { launchCheck } : {}),
     summary: lines.join('\n')
   };
 }

package/lib/repo-project-suggestions.mjs

@@ -0,0 +1,285 @@
+// Ranks the user's RO projects for a git repo that has no project mapping yet,
+// so the user (or an agent) can confirm the likely project instead of typing a
+// projectMemberId. Pure: every input is passed in.
+//
+// Evidence, strongest first:
+//   1. ticket history: a ticket key from this repo's commits appears in one of
+//      the user's own RO entries (description or task) of the last 30 days;
+//   2. name similarity: the repo folder name or git remote matches the project
+//      name, its acronym in parentheses, or the initials of its words;
+//   3. single booked project: the repo's commit days had exactly one booked
+//      project.
+import { extractTickets } from './commit-workflow.mjs';
+import { projectIdentityKey, sameProjectIdentity } from './project-identity.mjs';
+
+export const MAX_REPO_SUGGESTIONS = 5;
+
+const SCORE_TICKET = 60;
+const SCORE_TICKET_EXTRA = 5;
+const SCORE_TICKET_MAX = 80;
+const SCORE_ACRONYM = 30;
+const SCORE_INITIALS = 25;
+const SCORE_TOKEN = 15;
+const SCORE_TOKEN_EXTRA = 5;
+const SCORE_TOKEN_MAX = 28;
+const SCORE_SINGLE_BOOKED = 15;
+const MAX_TICKET_REASONS = 3;
+
+// Words that say nothing about which project a repo belongs to.
+export const NAME_STOP_WORDS = new Set([
+  'app', 'apps', 'web', 'website', 'api', 'apis', 'fe', 'be', 'frontend', 'front', 'backend', 'back', 'end',
+  'service', 'services', 'svc', 'mobile', 'the', 'a', 'an', 'of', 'and', 'for', 'project', 'projects', 'prj',
+  'sit', 'uat', 'prod', 'dev', 'staging', 'stg', 'team', 'repo', 'git', 'src', 'main', 'client', 'server',
+  'android', 'ios', 'ui', 'v1', 'v2', 'v3', 'new', 'old', 'core', 'common',
+  // Remote URL noise.
+  'github', 'gitlab', 'bitbucket', 'com', 'org', 'net', 'io', 'www', 'http', 'https', 'ssh', 'scm', 'azure',
+  'visualstudio', 'vs', 'tfs'
+]);
+
+// Lowercase tokens of a name: split on -_./ (and any other non-alphanumeric
+// character) and on camelCase / PascalCase boundaries.
+export function tokenizeName(value = '') {
+  return String(value)
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .split(/[^A-Za-z0-9]+/)
+    .map((token) => token.toLowerCase())
+    .filter(Boolean);
+}
+
+export function meaningfulTokens(value = '') {
+  return tokenizeName(value).filter((token) => token.length >= 2 && !NAME_STOP_WORDS.has(token) && !/^\d+$/.test(token));
+}
+
+// What a repo name can match in a project name: its meaningful tokens, the
+// acronyms in parentheses ("GKE Fair Chem System (FCS)" -> fcs), and the
+// initials of its words, with and without stop words ("gfcs").
+export function projectNameKeys(projectName = '') {
+  const name = String(projectName);
+  const acronyms = [...name.matchAll(/\(([^)]+)\)/g)]
+    .flatMap((match) => tokenizeName(match[1]))
+    .filter((token) => token.length >= 2);
+  const words = tokenizeName(name.replace(/\([^)]*\)/g, ' ')).filter((token) => !/^\d+$/.test(token));
+  const initials = new Set();
+  for (const list of [words, words.filter((word) => !NAME_STOP_WORDS.has(word))]) {
+    if (list.length >= 2) {
+      initials.add(list.map((word) => word[0]).join(''));
+    }
+  }
+  return {
+    tokens: [...new Set(meaningfulTokens(name))],
+    acronyms: [...new Set(acronyms)],
+    initials: [...initials].filter((value) => value.length >= 2)
+  };
+}
+
+// The path part of a git remote ("git@host:org/repo.git",
+// "https://host/org/repo.git", "ssh://git@host:22/org/repo") without the host
+// and the .git suffix.
+export function remoteRepoPath(remoteUrl = '') {
+  const text = String(remoteUrl || '').trim();
+  if (!text) {
+    return '';
+  }
+  let path = text;
+  const scheme = /^[a-z][a-z0-9+.-]*:\/\/[^/]+\/?(.*)$/i.exec(text);
+  const scp = /^[^@/\s]+@[^:/\s]+:(.*)$/.exec(text);
+  if (scheme) {
+    path = scheme[1];
+  } else if (scp) {
+    path = scp[1];
+  }
+  return path.replace(/\.git\/?$/i, '').replace(/^\/+|\/+$/g, '');
+}
+
+// RO entries from queryLogwork(includeEntries: true) as history items.
+export function historyFromQueryResult(queryResult) {
+  return (Array.isArray(queryResult?.entries) ? queryResult.entries : [])
+    .map((entry) => ({
+      date: entry.date || '',
+      projectName: entry.projectName || '',
+      ...(hasValue(entry.projectMemberId) ? { projectMemberId: entry.projectMemberId } : {}),
+      ...(hasValue(entry.projectId) ? { projectId: entry.projectId } : {}),
+      text: [entry.taskName, entry.description].filter(Boolean).join(' ')
+    }))
+    .filter((entry) => entry.text && (entry.projectName || hasValue(entry.projectMemberId) || hasValue(entry.projectId)));
+}
+
+// Booked projects (bookedHours > 0) per date from a queryLogwork result.
+export function bookedProjectsByDateFromQuery(queryResult) {
+  const byDate = {};
+  for (const day of Array.isArray(queryResult?.days) ? queryResult.days : []) {
+    byDate[day.date] = (day.projects || []).filter((project) => Number(project.bookedHours || 0) > 0);
+  }
+  return byDate;
+}
+
+// Every candidate with its score and reasons, highest score first; ties keep
+// the candidates' order. A candidate without evidence scores 0.
+export function rankRepoProjects({
+  repoPath = '',
+  repoGroups = [],
+  candidates = [],
+  history = [],
+  remoteUrl = '',
+  bookedProjectsByDate = {}
+} = {}) {
+  const projects = uniqueProjects(candidates);
+  const tickets = [...new Set(repoGroups.flatMap((group) => group.tickets || []))];
+  const repoName = String(repoPath).split(/[\\/]/).filter(Boolean).pop() || '';
+  const nameSources = [
+    { label: 'repo name', tokens: meaningfulTokens(repoName) },
+    { label: 'git remote', tokens: meaningfulTokens(remoteRepoPath(remoteUrl)) }
+  ].filter((source) => source.tokens.length);
+  const singleBooked = singleBookedProject(repoGroups, bookedProjectsByDate);
+
+  const ranked = projects.map((project, index) => {
+    const reasons = [];
+    let score = 0;
+
+    const ticketHits = ticketEvidence(project, tickets, history);
+    if (ticketHits.length) {
+      score += Math.min(SCORE_TICKET_MAX, SCORE_TICKET + SCORE_TICKET_EXTRA * (ticketHits.length - 1));
+      reasons.push(...ticketHits.slice(0, MAX_TICKET_REASONS)
+        .map((hit) => `ticket ${hit.ticket} was logged to this project on ${hit.date}`));
+    }
+
+    const name = nameEvidence(project, nameSources);
+    if (name) {
+      score += name.score;
+      reasons.push(name.reason);
+    }
+
+    if (singleBooked && sameProjectIdentity(singleBooked.project, project)) {
+      score += SCORE_SINGLE_BOOKED;
+      reasons.push(`the only project booked on this repo's commit days (${formatDates(singleBooked.dates)})`);
+    }
+
+    return { ...projectRef(project), score, reasons, index };
+  });
+
+  return ranked
+    .sort((left, right) => right.score - left.score || left.index - right.index)
+    .map(({ index: _index, ...item }) => item);
+}
+
+// The top suggestions (score > 0), at most MAX_REPO_SUGGESTIONS.
+export function suggestRepoProjects(input = {}) {
+  return rankRepoProjects(input)
+    .filter((item) => item.score > 0)
+    .slice(0, MAX_REPO_SUGGESTIONS);
+}
+
+// Picker order: suggestions first (top one first), then every other candidate
+// in its original order. Each item: { project, suggestion | null }.
+export function orderProjectsForPicker(candidates = [], suggestions = []) {
+  const items = suggestions.map((suggestion) => ({ project: projectRef(suggestion), suggestion }));
+  for (const project of uniqueProjects(candidates)) {
+    if (!items.some((item) => sameProjectIdentity(item.project, project))) {
+      items.push({ project: projectRef(project), suggestion: null });
+    }
+  }
+  return items;
+}
+
+export function formatSuggestionReason(suggestion) {
+  return (suggestion?.reasons || []).join('; ');
+}
+
+function ticketEvidence(project, tickets, history) {
+  if (!tickets.length || !history.length) {
+    return [];
+  }
+  const hits = [];
+  for (const ticket of tickets) {
+    const dates = history
+      .filter((entry) => sameProjectIdentity(entry, project) && extractTickets(entry.text).includes(ticket))
+      .map((entry) => entry.date)
+      .filter(Boolean)
+      .sort();
+    if (dates.length) {
+      hits.push({ ticket, date: dates.at(-1) });
+    }
+  }
+  return hits.sort((left, right) => right.date.localeCompare(left.date));
+}
+
+function nameEvidence(project, sources) {
+  if (!sources.length) {
+    return null;
+  }
+  const keys = projectNameKeys(project.projectName);
+  let best = null;
+  const consider = (candidate) => {
+    if (!best || candidate.score > best.score) {
+      best = candidate;
+    }
+  };
+  for (const source of sources) {
+    const acronym = keys.acronyms.find((value) => source.tokens.includes(value));
+    if (acronym) {
+      consider({ score: SCORE_ACRONYM, reason: `${source.label} matches ${acronym.toUpperCase()}` });
+    }
+    const initials = keys.initials.find((value) => source.tokens.includes(value));
+    if (initials) {
+      consider({ score: SCORE_INITIALS, reason: `${source.label} matches the initials ${initials.toUpperCase()} of the project name` });
+    }
+    const shared = [...new Set(source.tokens.filter((token) => keys.tokens.includes(token)))];
+    if (shared.length) {
+      consider({
+        score: Math.min(SCORE_TOKEN_MAX, SCORE_TOKEN + SCORE_TOKEN_EXTRA * (shared.length - 1)),
+        reason: `${source.label} shares ${shared.map((token) => `"${token}"`).join(', ')} with the project name`
+      });
+    }
+  }
+  return best;
+}
+
+function singleBookedProject(repoGroups, bookedProjectsByDate) {
+  const dates = [...new Set(repoGroups.map((group) => group.date).filter(Boolean))].sort();
+  if (!dates.length) {
+    return null;
+  }
+  const projects = [];
+  for (const date of dates) {
+    for (const project of bookedProjectsByDate?.[date] || []) {
+      if (!projects.some((known) => sameProjectIdentity(known, project))) {
+        projects.push(project);
+      }
+    }
+  }
+  return projects.length === 1 ? { project: projects[0], dates } : null;
+}
+
+function uniqueProjects(projects) {
+  const seen = new Set();
+  const results = [];
+  for (const project of Array.isArray(projects) ? projects : []) {
+    if (!project || !(project.projectName || hasValue(project.projectMemberId) || hasValue(project.projectId))) {
+      continue;
+    }
+    const key = projectIdentityKey(project);
+    if (seen.has(key) || results.some((known) => sameProjectIdentity(known, project))) {
+      continue;
+    }
+    seen.add(key);
+    results.push(project);
+  }
+  return results;
+}
+
+function projectRef(project = {}) {
+  return {
+    projectName: project.projectName || '',
+    ...(hasValue(project.projectMemberId) ? { projectMemberId: project.projectMemberId } : {}),
+    ...(hasValue(project.projectId) ? { projectId: project.projectId } : {})
+  };
+}
+
+function formatDates(dates) {
+  return dates.length > 3 ? `${dates.slice(0, 3).join(', ')} +${dates.length - 3} more` : dates.join(', ');
+}
+
+function hasValue(value) {
+  return value !== undefined && value !== null && String(value).trim() !== '';
+}