logwork-cli 0.0.0-stage → 1.0.0

package/lib/os-notification.mjs

@@ -0,0 +1,105 @@
+import { spawn } from 'node:child_process';
+import { runOsascript } from './macos.mjs';
+
+export async function sendOsNotification({
+  title = 'Logwork',
+  message,
+  platform = process.platform,
+  macNotifier = sendMacosNotification,
+  windowsNotifier = sendWindowsNotification
+} = {}) {
+  const notification = normalizeNotification({ title, message });
+  if (platform === 'darwin') {
+    await macNotifier(notification);
+  } else if (platform === 'win32') {
+    await windowsNotifier(notification);
+  } else {
+    throw new Error(`OS notifications are unsupported on ${platform}. Supported platforms are macOS and Windows.`);
+  }
+
+  return {
+    status: 'sent',
+    platform,
+    title: notification.title,
+    message: notification.message
+  };
+}
+
+export async function sendMacosNotification({ title, message }, {
+  run = runOsascript
+} = {}) {
+  const script = String.raw`
+on run argv
+  display notification (item 2 of argv) with title (item 1 of argv)
+end run`;
+  await run(script, [title, message]);
+}
+
+export async function sendWindowsNotification({ title, message }, {
+  run = runPowerShellToast
+} = {}) {
+  await run({ title, message });
+}
+
+export function runPowerShellToast(notification, {
+  command = 'powershell.exe',
+  spawnFn = spawn
+} = {}) {
+  return new Promise((resolveValue, reject) => {
+    const child = spawnFn(command, [
+      '-NoProfile',
+      '-NonInteractive',
+      '-ExecutionPolicy', 'Bypass',
+      '-Command', WINDOWS_TOAST_SCRIPT
+    ], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code !== 0) {
+        reject(new Error(`Windows notification failed with exit code ${code}: ${stderr.trim() || 'no stderr'}`));
+        return;
+      }
+      resolveValue(stdout.trim());
+    });
+    child.stdin.end(JSON.stringify(notification));
+  });
+}
+
+function normalizeNotification({ title, message }) {
+  const normalizedTitle = String(title || '').replace(/[\r\n]+/g, ' ').trim().slice(0, 100);
+  const normalizedMessage = String(message || '').trim().slice(0, 1_000);
+  if (!normalizedTitle || !normalizedMessage) {
+    throw new Error('Notification title and message are required.');
+  }
+  return {
+    title: normalizedTitle,
+    message: normalizedMessage
+  };
+}
+
+const WINDOWS_TOAST_SCRIPT = String.raw`
+$ErrorActionPreference = 'Stop'
+[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+
+$request = [Console]::In.ReadToEnd() | ConvertFrom-Json
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+[Windows.UI.Notifications.ToastNotification, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+
+$template = [Windows.UI.Notifications.ToastTemplateType]::ToastText02
+$toastXml = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent($template)
+$textNodes = $toastXml.GetElementsByTagName('text')
+$textNodes.Item(0).AppendChild($toastXml.CreateTextNode([string]$request.title)) | Out-Null
+$textNodes.Item(1).AppendChild($toastXml.CreateTextNode([string]$request.message)) | Out-Null
+$toast = [Windows.UI.Notifications.ToastNotification]::new($toastXml)
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('PowerShell').Show($toast)
+@{ ok = $true } | ConvertTo-Json -Compress
+`;

package/lib/package-info.mjs

@@ -0,0 +1,17 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+export function readPackageInfo({ packagePath = join(PACKAGE_ROOT, 'package.json'), readFile = readFileSync } = {}) {
+  const packageJson = JSON.parse(readFile(packagePath, 'utf8'));
+  return {
+    name: packageJson.name,
+    version: packageJson.version
+  };
+}
+
+export function readPackageVersion(options = {}) {
+  return readPackageInfo(options).version;
+}

package/lib/paths.mjs

@@ -0,0 +1,68 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+
+export const HELPER_HOME_DIRNAME = '.logwork-cli';
+export const CONFIG_FILE_NAME = '.logwork.json';
+export const MANUAL_DRAFTS_FILE_NAME = 'manual-drafts.json';
+export const APPLY_LEDGER_FILE_NAME = 'apply-ledger.json';
+export const UPDATE_STATE_FILE_NAME = 'update-state.json';
+export const REMINDER_CONFIG_FILE_NAME = 'reminder.json';
+export const REMINDER_STATE_FILE_NAME = 'reminder-state.json';
+
+// Names used before the package was renamed from logwork-helper to logwork-cli.
+// lib/legacy-migration.mjs copies state from these locations on first run.
+export const LEGACY_HELPER_HOME_DIRNAME = '.logwork-helper';
+export const LEGACY_CONFIG_FILE_NAME = '.logwork-helper.json';
+
+export function helperHome() {
+  return resolve(customHelperHome() || resolve(homedir(), HELPER_HOME_DIRNAME));
+}
+
+export function customHelperHome(env = process.env) {
+  return env.LOGWORK_HOME || env.LOGWORK_HELPER_HOME || '';
+}
+
+export function legacyHelperHome() {
+  return resolve(homedir(), LEGACY_HELPER_HOME_DIRNAME);
+}
+
+export function userConfigPath() {
+  return resolve(helperHome(), CONFIG_FILE_NAME);
+}
+
+export function manualDraftsPath() {
+  return resolve(helperHome(), MANUAL_DRAFTS_FILE_NAME);
+}
+
+export function applyLedgerPath() {
+  return resolve(helperHome(), APPLY_LEDGER_FILE_NAME);
+}
+
+export function updateStatePath() {
+  return resolve(helperHome(), UPDATE_STATE_FILE_NAME);
+}
+
+export function reminderConfigPath() {
+  return resolve(helperHome(), REMINDER_CONFIG_FILE_NAME);
+}
+
+export function reminderStatePath() {
+  return resolve(helperHome(), REMINDER_STATE_FILE_NAME);
+}
+
+export function legacyUserConfigPath() {
+  return resolve(homedir(), LEGACY_CONFIG_FILE_NAME);
+}
+
+// Project-scope mappings live in the repo the user works in. A repo that still
+// has the old .logwork-helper.json (and no .logwork.json) keeps using it, so
+// committed mappings keep working without a rename.
+export function projectConfigPath(cwd = process.cwd(), { exists = existsSync } = {}) {
+  const current = resolve(cwd, CONFIG_FILE_NAME);
+  const legacy = resolve(cwd, LEGACY_CONFIG_FILE_NAME);
+  if (!exists(current) && exists(legacy)) {
+    return legacy;
+  }
+  return current;
+}

package/lib/project-identity.mjs

@@ -0,0 +1,66 @@
+export function normalizeProjectName(value) {
+  return String(value || '').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+export function projectIdentityKey(project = {}) {
+  return String(
+    firstPresent(project.projectMemberId, project.projectId) ??
+      normalizeProjectName(project.projectName)
+  );
+}
+
+export function sameProjectIdentity(left = {}, right = {}) {
+  if (hasValue(left.projectMemberId) && hasValue(right.projectMemberId)) {
+    return String(left.projectMemberId) === String(right.projectMemberId);
+  }
+  if (hasValue(left.projectId) && hasValue(right.projectId)) {
+    return String(left.projectId) === String(right.projectId);
+  }
+
+  const leftName = normalizeProjectName(left.projectName);
+  const rightName = normalizeProjectName(right.projectName);
+  return Boolean(leftName && rightName && leftName === rightName);
+}
+
+export function projectMatchesFilter(project = {}, filterValue) {
+  const filter = String(filterValue || '').trim();
+  if (!filter) {
+    return false;
+  }
+
+  const normalizedFilter = normalizeProjectName(filter);
+  return (hasValue(project.projectMemberId) && String(project.projectMemberId) === filter) ||
+    (hasValue(project.projectId) && String(project.projectId) === filter) ||
+    normalizeProjectName(project.projectName).includes(normalizedFilter);
+}
+
+export function projectMatchesMapping(project = {}, mapping = {}, {
+  allowNameContains = true,
+  fallbackToName = false
+} = {}) {
+  if (hasValue(mapping.projectMemberId)) {
+    const memberMatches = hasValue(project.projectMemberId) &&
+      String(mapping.projectMemberId) === String(project.projectMemberId);
+    if (memberMatches || !fallbackToName) {
+      return memberMatches;
+    }
+  }
+
+  const projectName = normalizeProjectName(project.projectName);
+  const mappingName = normalizeProjectName(mapping.projectName);
+  if (!projectName || !mappingName) {
+    return false;
+  }
+
+  return allowNameContains
+    ? projectName.includes(mappingName)
+    : projectName === mappingName;
+}
+
+function firstPresent(...values) {
+  return values.find(hasValue);
+}
+
+function hasValue(value) {
+  return value !== undefined && value !== null && String(value).trim() !== '';
+}

package/lib/project-mapping-workflow.mjs

@@ -0,0 +1,309 @@
+import { ApiError, getProjects } from './api.mjs';
+import {
+  configPath,
+  loadLocalConfig,
+  upsertProjectMappingConfig
+} from './logwork-config.mjs';
+import { createResourceOptimiserSession } from './query-workflow.mjs';
+
+export async function listLogworkProjects({
+  cwd = process.cwd(),
+  fetchProjects
+} = {}) {
+  const projects = sanitizeProjects(await (fetchProjects || createMembershipProjectsFetcher())());
+  const config = await loadLocalConfig(cwd);
+
+  return {
+    projects,
+    mappings: config.projectMappings,
+    configSources: {
+      user: configPath(cwd, 'user'),
+      project: configPath(cwd, 'project')
+    },
+    summary: [
+      `Found ${projects.length} Resource Optimiser project memberships.`,
+      config.projectMappings.length
+        ? `Current mappings: ${config.projectMappings.length}.`
+        : 'No project mappings configured yet.'
+    ].join('\n')
+  };
+}
+
+export async function upsertProjectMapping({
+  projectMemberId,
+  projectName,
+  tickets = [],
+  keywords = [],
+  scope = 'user',
+  confirm,
+  cwd = process.cwd(),
+  fetchProjects
+} = {}) {
+  if (confirm !== true) {
+    throw new Error('map_project requires confirm: true.');
+  }
+
+  if (!Array.isArray(tickets) || !tickets.length) {
+    throw new Error('map_project requires at least one ticket prefix.');
+  }
+
+  const projects = sanitizeProjects(await (fetchProjects || createMembershipProjectsFetcher())());
+  const resolution = resolveProjectSelection(projects, { projectMemberId, projectName });
+  if (!resolution.project) {
+    const suffix = resolution.candidates?.length
+      ? ` Candidates: ${resolution.candidates.map((project) => `${project.projectMemberId}:${project.projectName}`).join(', ')}`
+      : '';
+    throw new Error(`${resolution.reason}.${suffix}`);
+  }
+
+  const result = await upsertProjectMappingConfig({
+    cwd,
+    scope,
+    project: resolution.project,
+    tickets,
+    keywords
+  });
+
+  return {
+    status: result.created ? 'created' : 'updated',
+    scope: result.scope,
+    configPath: result.path,
+    mapping: result.mapping,
+    projects,
+    summary: [
+      `${result.created ? 'Created' : 'Updated'} project mapping for ${result.mapping.projectName}.`,
+      `Tickets: ${result.mapping.tickets.join(', ')}.`,
+      result.mapping.keywords.length ? `Keywords: ${result.mapping.keywords.join(', ')}.` : 'Keywords: none.'
+    ].join('\n')
+  };
+}
+
+export function buildSetupSuggestions(entries, membershipProjects = []) {
+  const candidates = sanitizeProjects(membershipProjects);
+
+  return entries
+    .filter((entry) => entry.status === 'unresolved')
+    .map((entry) => {
+      const ticketPrefixes = ticketPrefixesFromEntry(entry);
+      if (!ticketPrefixes.length) {
+        return null;
+      }
+
+      const candidateProjects = rankCandidatesByTicketPrefix(
+        sanitizeProjects(entry.candidates?.length ? entry.candidates : candidates),
+        ticketPrefixes
+      );
+      if (!candidateProjects.length) {
+        return null;
+      }
+
+      return {
+        entryId: entry.id,
+        date: entry.date,
+        hours: entry.hours,
+        taskName: entry.taskName,
+        tickets: entry.tickets || [],
+        ticketPrefixes,
+        candidateProjects: candidateProjects.map((project) => ({
+          ...project,
+          toolArguments: {
+            projectMemberId: project.projectMemberId,
+            tickets: ticketPrefixes,
+            keywords: [],
+            confirm: true
+          }
+        }))
+      };
+    })
+    .filter(Boolean);
+}
+
+export function enrichRoPreviewWithJiraProjects(roPreview, jiraPreview) {
+  if (!roPreview || !jiraPreview) {
+    return roPreview;
+  }
+
+  const setupByEntry = new Map((roPreview.setupSuggestions || []).map((suggestion) => [suggestion.entryId, suggestion]));
+  const suggestions = (jiraPreview.entries || [])
+    .map((jiraEntry) => buildJiraMappingSuggestion(jiraEntry, setupByEntry.get(jiraEntry.id)))
+    .filter(Boolean);
+
+  if (!suggestions.length) {
+    return roPreview;
+  }
+
+  return {
+    ...roPreview,
+    jiraMappingSuggestions: suggestions,
+    summary: [
+      roPreview.summary,
+      '',
+      'Jira-assisted RO mapping suggestions:',
+      ...suggestions.map(formatJiraMappingSuggestion)
+    ].join('\n')
+  };
+}
+
+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 }) {
+  if (projectMemberId !== undefined && projectMemberId !== null && String(projectMemberId).trim() !== '') {
+    const project = projects.find((candidate) => String(candidate.projectMemberId) === String(projectMemberId));
+    return project
+      ? { project }
+      : { project: null, reason: `Project member ${projectMemberId} was not found in your memberships`, candidates: projects };
+  }
+
+  if (!projectName || !String(projectName).trim()) {
+    return {
+      project: null,
+      reason: 'Pass projectMemberId or projectName to choose a mapping project',
+      candidates: projects
+    };
+  }
+
+  const normalizedName = normalize(projectName);
+  const exactMatches = projects.filter((project) => normalize(project.projectName) === normalizedName);
+  if (exactMatches.length === 1) {
+    return { project: exactMatches[0] };
+  }
+
+  const fuzzyMatches = projects.filter((project) => normalize(project.projectName).includes(normalizedName));
+  if (fuzzyMatches.length === 1) {
+    return { project: fuzzyMatches[0] };
+  }
+
+  if (exactMatches.length > 1 || fuzzyMatches.length > 1) {
+    return {
+      project: null,
+      reason: `Project name "${projectName}" is ambiguous`,
+      candidates: exactMatches.length > 1 ? exactMatches : fuzzyMatches
+    };
+  }
+
+  return {
+    project: null,
+    reason: `Project name "${projectName}" was not found in your memberships`,
+    candidates: projects
+  };
+}
+
+function ticketPrefixesFromEntry(entry) {
+  return [...new Set((entry.tickets || [])
+    .map((ticket) => String(ticket).toUpperCase().match(/^([A-Z][A-Z0-9]+)-\d+/)?.[1])
+    .filter(Boolean))];
+}
+
+function buildJiraMappingSuggestion(jiraEntry, setupSuggestion) {
+  if (!setupSuggestion || !jiraEntry?.issue?.project) {
+    return null;
+  }
+
+  const jiraProject = {
+    key: String(jiraEntry.issue.project.key || '').trim(),
+    name: String(jiraEntry.issue.project.name || '').trim()
+  };
+  const ranked = (setupSuggestion.candidateProjects || [])
+    .map((project) => ({
+      ...project,
+      ...scoreJiraProjectCandidate(project, jiraProject)
+    }))
+    .sort((left, right) => right.confidence - left.confidence || String(left.projectName).localeCompare(String(right.projectName)));
+  const recommendation = ranked[0]?.confidence > 0 ? ranked[0] : null;
+
+  return {
+    entryId: jiraEntry.id,
+    issueKey: jiraEntry.issueKey,
+    jiraProject,
+    ticketPrefixes: setupSuggestion.ticketPrefixes,
+    recommendation,
+    candidates: ranked
+  };
+}
+
+function scoreJiraProjectCandidate(project, jiraProject) {
+  const projectName = normalize(project.projectName);
+  const jiraName = normalize(jiraProject.name);
+  const jiraKey = normalize(jiraProject.key);
+
+  if (jiraName && projectName === jiraName) {
+    return { confidence: 0.99, reason: 'jira_project_name_exact' };
+  }
+  if (jiraName && (projectName.includes(jiraName) || jiraName.includes(projectName))) {
+    return { confidence: 0.94, reason: 'jira_project_name_contains' };
+  }
+  if (jiraKey && projectName.split(/[^a-z0-9]+/).includes(jiraKey)) {
+    return { confidence: 0.9, reason: 'jira_project_key_match' };
+  }
+
+  const jiraTokens = meaningfulTokens(jiraName);
+  const projectTokens = new Set(meaningfulTokens(projectName));
+  const overlap = jiraTokens.filter((token) => projectTokens.has(token));
+  if (overlap.length) {
+    return {
+      confidence: Number(Math.min(0.85, 0.6 + (overlap.length / Math.max(jiraTokens.length, 1)) * 0.25).toFixed(2)),
+      reason: 'jira_project_name_token_match'
+    };
+  }
+
+  return { confidence: 0, reason: 'jira_project_no_match' };
+}
+
+function rankCandidatesByTicketPrefix(projects, ticketPrefixes) {
+  const prefixes = ticketPrefixes.map(normalize);
+  return projects
+    .map((project) => {
+      const tokens = normalize(project.projectName).split(/[^a-z0-9]+/);
+      const prefixMatch = prefixes.some((prefix) => tokens.includes(prefix));
+      return {
+        ...project,
+        suggestedByTicket: prefixMatch
+      };
+    })
+    .sort((left, right) => Number(right.suggestedByTicket) - Number(left.suggestedByTicket));
+}
+
+function meaningfulTokens(value) {
+  return normalize(value)
+    .split(/[^a-z0-9]+/)
+    .filter((token) => token.length >= 3 && !['project', 'team', 'the', 'and'].includes(token));
+}
+
+function formatJiraMappingSuggestion(suggestion) {
+  const jiraProject = [suggestion.jiraProject.key, suggestion.jiraProject.name].filter(Boolean).join(' / ') || 'unknown Jira project';
+  if (!suggestion.recommendation) {
+    return `- ${suggestion.issueKey}: ${jiraProject} has no confident RO project match. Choose a candidate manually.`;
+  }
+
+  const recommendation = suggestion.recommendation;
+  return `- ${suggestion.issueKey}: ${jiraProject} -> ${recommendation.projectName} (${recommendation.projectMemberId}), ${recommendation.reason}, confidence ${recommendation.confidence}. Confirm with /map ${suggestion.ticketPrefixes.join(',')} ${recommendation.projectMemberId}.`;
+}
+
+function sanitizeProjects(projects) {
+  return (Array.isArray(projects) ? projects : [])
+    .filter((project) => project && project.projectMemberId !== undefined && project.projectMemberId !== null)
+    .map((project) => ({
+      projectMemberId: project.projectMemberId,
+      projectId: project.projectId,
+      projectName: project.projectName
+    }));
+}
+
+function normalize(value) {
+  return String(value || '').toLowerCase().replace(/\s+/g, ' ').trim();
+}