logwork-cli 0.0.0-stage → 1.0.0

package/lib/reminder-workflow.mjs

@@ -0,0 +1,299 @@
+import { isAuthRequiredError } from './auth-errors.mjs';
+import { redactText } from './auth-redaction.mjs';
+import { withFileLock } from './file-lock.mjs';
+import { searchJiraIssues } from './jira-api.mjs';
+import {
+  getStoredJiraSession,
+  isJiraAuthRequiredError
+} from './jira-auth.mjs';
+import { sendOsNotification } from './os-notification.mjs';
+import { reminderStatePath } from './paths.mjs';
+import { queryLogwork } from './query-workflow.mjs';
+import { loadReminderConfig } from './reminder-config.mjs';
+import {
+  loadReminderState,
+  saveReminderState
+} from './reminder-state.mjs';
+import { todayLocalDateISO } from './util.mjs';
+
+export async function checkLogworkReminder({
+  target = 'both',
+  date = todayLocalDateISO(),
+  queryRo = queryResourceOptimiserDay,
+  queryJira = queryJiraWorklogDay
+} = {}) {
+  const checks = {};
+  const jobs = [];
+
+  if (target === 'ro' || target === 'both') {
+    jobs.push(runReminderCheck('ro', () => queryRo({ date })).then((result) => {
+      checks.ro = result;
+    }));
+  }
+  if (target === 'jira' || target === 'both') {
+    jobs.push(runReminderCheck('jira', () => queryJira({ date })).then((result) => {
+      checks.jira = result;
+    }));
+  }
+  if (!jobs.length) {
+    throw new Error('Reminder target must be ro, jira, or both.');
+  }
+  await Promise.all(jobs);
+
+  const problemLines = buildProblemLines(checks);
+  const notify = problemLines.length > 0;
+  const notification = notify ? {
+    title: 'Logwork',
+    message: [
+      'Logwork hôm nay chưa hoàn tất',
+      ...problemLines,
+      '',
+      'Mở Terminal và chạy: logwork'
+    ].join('\n')
+  } : null;
+
+  return {
+    date,
+    target,
+    status: notify ? 'notification_required' : 'complete',
+    notify,
+    checks,
+    notification,
+    summary: notify
+      ? `Logwork reminder requires attention: ${problemLines.join(' | ')}`
+      : `Logwork reminder check is complete for ${date}; no notification is needed.`
+  };
+}
+
+export async function queryResourceOptimiserDay({
+  date,
+  query = queryLogwork
+} = {}) {
+  const result = await query({
+    date,
+    includeEntries: false
+  });
+  const bookedHours = roundHours(result?.totals?.bookedHours);
+  const loggedHours = roundHours(result?.totals?.loggedHours);
+  const remainingHours = roundHours(Math.max(0, bookedHours - loggedHours));
+  let status = 'complete';
+  if (bookedHours === 0 && loggedHours === 0) {
+    status = 'not_expected';
+  } else if (remainingHours > 0) {
+    status = 'incomplete';
+  }
+  return {
+    target: 'ro',
+    status,
+    bookedHours,
+    loggedHours,
+    remainingHours
+  };
+}
+
+export async function queryJiraWorklogDay({
+  date,
+  getSession = getStoredJiraSession,
+  searchIssues = searchJiraIssues
+} = {}) {
+  assertDateOnly(date);
+  const session = await getSession();
+  const jql = `worklogAuthor = currentUser() AND worklogDate = "${date}"`;
+  const issues = await searchIssues(session.token, {
+    jql,
+    fields: ['key', 'summary'],
+    pageSize: 100
+  }, {
+    baseUrl: session.baseUrl
+  });
+  return {
+    target: 'jira',
+    status: issues.length ? 'complete' : 'incomplete',
+    issueCount: issues.length,
+    issues: issues.map((issue) => ({
+      key: issue.key,
+      summary: issue.summary
+    }))
+  };
+}
+
+export async function runScheduledReminder({
+  loadConfig = loadReminderConfig,
+  loadState = loadReminderState,
+  saveState = saveReminderState,
+  check = checkLogworkReminder,
+  notify = sendOsNotification,
+  now = () => new Date(),
+  statePath = reminderStatePath(),
+  lockOptions = {}
+} = {}) {
+  return withFileLock(statePath, async () => {
+    const config = await loadConfig();
+    const current = now();
+    const date = todayLocalDateISO(current);
+    const runAt = current.toISOString();
+
+    if (!config.enabled) {
+      return {
+        status: 'disabled',
+        notified: false,
+        summary: 'Logwork reminder is disabled.'
+      };
+    }
+    if (!config.days.includes(current.getDay())) {
+      const result = {
+        status: 'skipped_non_workday',
+        notified: false,
+        summary: 'Logwork reminder skipped because today is not a configured workday.'
+      };
+      await saveState(buildState(result, { date, runAt }));
+      return result;
+    }
+
+    const previous = await loadState();
+    if (previous?.lastNotifiedDate === date) {
+      const result = {
+        status: 'already_notified',
+        notified: false,
+        summary: `Logwork reminder already notified on ${date}.`
+      };
+      await saveState(buildState(result, {
+        date,
+        runAt,
+        lastNotifiedDate: previous.lastNotifiedDate
+      }));
+      return result;
+    }
+
+    const checkResult = await check({
+      target: config.target,
+      date
+    });
+    if (!checkResult.notify) {
+      const result = {
+        ...checkResult,
+        notified: false
+      };
+      await saveState(buildState(result, { date, runAt }));
+      return result;
+    }
+
+    try {
+      await notify(checkResult.notification);
+    } catch (error) {
+      const result = {
+        status: 'notification_failed',
+        notified: false,
+        summary: 'Logwork reminder was required but the OS notification failed.',
+        error: redactText(error.message)
+      };
+      await saveState(buildState(result, { date, runAt }));
+      throw error;
+    }
+
+    const result = {
+      ...checkResult,
+      status: 'notified',
+      notified: true
+    };
+    await saveState(buildState(result, {
+      date,
+      runAt,
+      lastNotifiedDate: date
+    }));
+    return result;
+  }, lockOptions);
+}
+
+export async function sendTestReminderNotification({
+  target = 'both',
+  notify = sendOsNotification
+} = {}) {
+  const lines = [];
+  if (target === 'ro' || target === 'both') {
+    lines.push('RO: 6/8h, còn thiếu 2h');
+  }
+  if (target === 'jira' || target === 'both') {
+    lines.push('Jira: chưa có worklog hôm nay');
+  }
+  if (!lines.length) {
+    throw new Error('Reminder target must be ro, jira, or both.');
+  }
+  const notification = {
+    title: 'Logwork',
+    message: [
+      'Đây là notification thử nghiệm',
+      ...lines,
+      '',
+      'Mở Terminal và chạy: logwork'
+    ].join('\n')
+  };
+  const result = await notify(notification);
+  return {
+    status: 'sent',
+    target,
+    notification,
+    platform: result?.platform || process.platform,
+    summary: `Sent a test logwork notification for ${target}.`
+  };
+}
+
+async function runReminderCheck(target, operation) {
+  try {
+    return await operation();
+  } catch (error) {
+    const authRequired = target === 'ro'
+      ? isAuthRequiredError(error)
+      : isJiraAuthRequiredError(error);
+    return {
+      target,
+      status: authRequired ? 'auth_required' : 'unavailable',
+      error: authRequired ? '' : redactText(error.message).slice(0, 500)
+    };
+  }
+}
+
+function buildProblemLines(checks) {
+  const lines = [];
+  if (checks.ro?.status === 'incomplete') {
+    lines.push(`RO: ${formatHours(checks.ro.loggedHours)}/${formatHours(checks.ro.bookedHours)}h, còn thiếu ${formatHours(checks.ro.remainingHours)}h`);
+  } else if (checks.ro?.status === 'auth_required') {
+    lines.push('RO: chưa đăng nhập, chạy logwork login');
+  } else if (checks.ro?.status === 'unavailable') {
+    lines.push('RO: không thể kiểm tra trạng thái');
+  }
+
+  if (checks.jira?.status === 'incomplete') {
+    lines.push('Jira: chưa có worklog hôm nay');
+  } else if (checks.jira?.status === 'auth_required') {
+    lines.push('Jira: chưa đăng nhập, chạy logwork login jira');
+  } else if (checks.jira?.status === 'unavailable') {
+    lines.push('Jira: không thể kiểm tra trạng thái');
+  }
+  return lines;
+}
+
+function buildState(result, { date, runAt, lastNotifiedDate = '' }) {
+  return {
+    lastRunAt: runAt,
+    lastRunDate: date,
+    lastStatus: result.status,
+    lastNotifiedDate,
+    summary: result.summary,
+    error: result.error || ''
+  };
+}
+
+function roundHours(value) {
+  return Number(Number(value || 0).toFixed(2));
+}
+
+function formatHours(value) {
+  return Number(value || 0).toFixed(2).replace(/\.00$/, '').replace(/(\.\d)0$/, '$1');
+}
+
+function assertDateOnly(value) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(String(value || ''))) {
+    throw new Error('Reminder date must use YYYY-MM-DD format.');
+  }
+}

package/lib/ro-delete-args.mjs

@@ -0,0 +1,38 @@
+export function parseRoDeleteArgs(args = []) {
+  const options = {
+    logworkId: undefined,
+    yes: false,
+    json: false,
+    help: false
+  };
+  const positional = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+      continue;
+    }
+    if (arg === '--yes' || arg === '-y') {
+      options.yes = true;
+      continue;
+    }
+    if (arg === '--json') {
+      options.json = true;
+      continue;
+    }
+    if (String(arg).startsWith('-')) {
+      throw new Error(`Unknown delete option: ${arg}`);
+    }
+    positional.push(arg);
+  }
+
+  if (options.help) {
+    return options;
+  }
+  if (positional.length !== 1) {
+    throw new Error('RO delete requires exactly one logwork id.');
+  }
+  options.logworkId = positional[0];
+  return options;
+}

package/lib/ro-delete-workflow.mjs

@@ -0,0 +1,115 @@
+import { ApiError, deleteLogworkEntry } from './api.mjs';
+import { createResourceOptimiserSession } from './query-workflow.mjs';
+import { createF03LogworkReader } from './ro-entry-reader.mjs';
+
+const DELETABLE_STATUSES = new Set(['submitted', 'approved']);
+
+export async function previewRoLogworkDelete({
+  logworkId,
+  fetchLogwork
+}) {
+  const reader = fetchLogwork || createF03LogworkReader();
+  const current = await reader(assertIdentifier(logworkId, 'logworkId'));
+  assertDeletableStatus(current);
+
+  const preview = {
+    previewId: `delete_${current.id}`,
+    status: 'ready',
+    logworkId: current.id,
+    original: current,
+    originalFingerprint: createLogworkRevisionFingerprint(current)
+  };
+  preview.summary = [
+    'RO logwork delete preview:',
+    `- Entry: ${current.id}`,
+    `- Date: ${current.date || '(unknown)'}`,
+    `- Project: ${current.projectName || current.projectId || '(unknown)'}`,
+    `- Task: ${current.taskName || '(no task name)'}`,
+    `- Hours: ${current.hours}`,
+    `- Status: ${current.status} (will be soft-deleted)`,
+    'Only submitted or approved entries can be deleted on Resource Optimiser.'
+  ].join('\n');
+  return preview;
+}
+
+export async function applyRoLogworkDelete({
+  preview,
+  confirm,
+  fetchLogwork,
+  submitDelete
+}) {
+  if (confirm !== true) {
+    throw new Error('Delete requires confirm: true.');
+  }
+  if (!preview || preview.status !== 'ready') {
+    throw new Error('A valid delete preview is required (delete_entry without confirm).');
+  }
+
+  const reader = fetchLogwork || createF03LogworkReader();
+  const writer = submitDelete || createDeleteWriter();
+  const current = await reader(preview.logworkId);
+  if (createLogworkRevisionFingerprint(current) !== preview.originalFingerprint) {
+    throw new Error('RO logwork changed after preview. Preview the delete again before applying.');
+  }
+  assertDeletableStatus(current);
+
+  const result = await writer(preview.logworkId);
+  if (result?.dryRun) {
+    return {
+      status: 'dry_run',
+      dryRun: true,
+      logworkId: preview.logworkId,
+      result,
+      summary: `Dry run: RO logwork entry ${preview.logworkId} was not deleted.`
+    };
+  }
+  return {
+    status: 'deleted',
+    logworkId: preview.logworkId,
+    result,
+    summary: `Deleted RO logwork entry ${preview.logworkId}.`
+  };
+}
+
+function createDeleteWriter() {
+  const session = createResourceOptimiserSession();
+  return async (logworkId) => {
+    const { token } = await session.get();
+    try {
+      return await deleteLogworkEntry(token, logworkId);
+    } catch (error) {
+      if (!(error instanceof ApiError) || error.status !== 401) {
+        throw error;
+      }
+      const refreshed = await session.get({ forceLogin: true });
+      return deleteLogworkEntry(refreshed.token, logworkId);
+    }
+  };
+}
+
+function assertDeletableStatus(logwork) {
+  const status = String(logwork?.status || '').toLowerCase();
+  if (status === 'rejected') {
+    throw new Error('Rejected entries cannot be deleted. Use resubmit_entry instead.');
+  }
+  if (!DELETABLE_STATUSES.has(status)) {
+    throw new Error(`Only submitted or approved RO logwork entries can be deleted (status: ${status || 'unknown'}).`);
+  }
+}
+
+function assertIdentifier(value, label) {
+  const text = String(value ?? '').trim();
+  if (!text) {
+    throw new Error(`${label} is required.`);
+  }
+  return text;
+}
+
+function createLogworkRevisionFingerprint(logwork) {
+  return JSON.stringify({
+    id: logwork.id,
+    hours: logwork.hours,
+    status: logwork.status,
+    taskName: logwork.taskName
+  });
+}

package/lib/ro-edit-args.mjs

@@ -0,0 +1,142 @@
+export function parseRoEditArgs(args = []) {
+  const options = {
+    logworkId: undefined,
+    hours: undefined,
+    taskName: undefined,
+    description: undefined,
+    typeOfWork: undefined,
+    yes: false,
+    json: false,
+    help: false
+  };
+  const positional = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+      continue;
+    }
+    if (arg === '--yes' || arg === '-y') {
+      options.yes = true;
+      continue;
+    }
+    if (arg === '--json') {
+      options.json = true;
+      continue;
+    }
+    if (arg === '--hours' || arg === '--logtimes') {
+      const value = args[index + 1];
+      if (value === undefined) {
+        throw new Error(`${arg} requires a positive number.`);
+      }
+      options.hours = normalizeHours(value);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith('--hours=') || arg.startsWith('--logtimes=')) {
+      options.hours = normalizeHours(arg.slice(arg.indexOf('=') + 1));
+      continue;
+    }
+    if (arg === '--task-name' || arg === '--task') {
+      const values = [];
+      while (args[index + 1] !== undefined && !String(args[index + 1]).startsWith('-')) {
+        values.push(args[index + 1]);
+        index += 1;
+      }
+      options.taskName = normalizeTaskName(values.join(' '), arg);
+      continue;
+    }
+    if (arg.startsWith('--task-name=') || arg.startsWith('--task=')) {
+      options.taskName = normalizeTaskName(arg.slice(arg.indexOf('=') + 1), arg.split('=')[0]);
+      continue;
+    }
+    if (arg === '--description' || arg === '--desc') {
+      const values = [];
+      while (args[index + 1] !== undefined && !String(args[index + 1]).startsWith('--')) {
+        values.push(args[index + 1]);
+        index += 1;
+      }
+      options.description = normalizeDescription(values.join(' '), arg);
+      continue;
+    }
+    if (arg.startsWith('--description=') || arg.startsWith('--desc=')) {
+      options.description = normalizeDescription(arg.slice(arg.indexOf('=') + 1), arg.split('=')[0]);
+      continue;
+    }
+    if (arg === '--type' || arg === '--type-of-work') {
+      options.typeOfWork = normalizeTypeOfWork(args[index + 1], arg);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith('--type=') || arg.startsWith('--type-of-work=')) {
+      options.typeOfWork = normalizeTypeOfWork(arg.slice(arg.indexOf('=') + 1), arg.split('=')[0]);
+      continue;
+    }
+    if (String(arg).startsWith('-')) {
+      throw new Error(`Unknown edit option: ${arg}`);
+    }
+    positional.push(arg);
+  }
+
+  if (options.help) {
+    return options;
+  }
+  if (positional.length !== 1) {
+    throw new Error('RO edit requires exactly one logwork id.');
+  }
+  if (
+    options.hours === undefined &&
+    options.taskName === undefined &&
+    options.description === undefined &&
+    options.typeOfWork === undefined
+  ) {
+    throw new Error('RO edit requires at least one of --hours, --task, --desc, --type.');
+  }
+  options.logworkId = positional[0];
+  return options;
+}
+
+function normalizeHours(value) {
+  const hours = Number(value);
+  if (!Number.isFinite(hours) || hours <= 0) {
+    throw new Error('--hours must be a positive number.');
+  }
+  const rounded = Number(hours.toFixed(2));
+  if (rounded <= 0) {
+    throw new Error('--hours must be at least 0.01 after rounding.');
+  }
+  return rounded;
+}
+
+function normalizeTaskName(value, option) {
+  const taskName = String(value || '').trim();
+  if (!taskName) {
+    throw new Error(`${option} requires a non-empty value.`);
+  }
+  if (taskName.length > 1_000) {
+    throw new Error('--task-name must not exceed 1000 characters.');
+  }
+  return taskName;
+}
+
+function normalizeDescription(value, option) {
+  const description = String(value || '').trim();
+  if (!description) {
+    throw new Error(`${option} requires a non-empty value.`);
+  }
+  if (description.length > 1_000) {
+    throw new Error('--description must not exceed 1000 characters.');
+  }
+  return description;
+}
+
+const TYPE_OF_WORK = ['create', 'correct', 'improve', 'other'];
+
+function normalizeTypeOfWork(value, option) {
+  const typeOfWork = String(value ?? '').trim();
+  if (!TYPE_OF_WORK.includes(typeOfWork)) {
+    throw new Error(`${option} must be one of: ${TYPE_OF_WORK.join(', ')}.`);
+  }
+  return typeOfWork;
+}